diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
index 56aece23167..1fb71f5dfe0 100644
--- a/.github/CODEOWNERS
+++ b/.github/CODEOWNERS
@@ -5,7 +5,7 @@ scripts/release*.sh @cryppadotta @devinfoley @nickyleach @forgottendev
scripts/release-*.mjs @cryppadotta @devinfoley @nickyleach @forgottendev
scripts/create-github-release.sh @cryppadotta @devinfoley @nickyleach @forgottendev
scripts/rollback-latest.sh @cryppadotta @devinfoley @nickyleach @forgottendev
-doc/RELEASING.md @cryppadotta @devinfoley @nickyleach @forgottendev
+doc/RELEASING.md @cryppadotta @devinfoley @nickyleach @forgottendev @tonio-alucema @scotttong
doc/PUBLISHING.md @cryppadotta @devinfoley @nickyleach @forgottendev
doc/RELEASE-AUTOMATION-SETUP.md @cryppadotta @devinfoley @nickyleach @forgottendev
skills/** @cryppadotta @devinfoley @nickyleach @forgottendev
diff --git a/.github/workflows/runner-full-stack-e2e.yml b/.github/workflows/runner-full-stack-e2e.yml
index 0600886144d..97afd34eadc 100644
--- a/.github/workflows/runner-full-stack-e2e.yml
+++ b/.github/workflows/runner-full-stack-e2e.yml
@@ -1294,7 +1294,7 @@ jobs:
- name: Package pruned dashboard with declared screenshots for GitHub Pages
if: vars.RUNNER_FULL_STACK_E2E_PUBLISH_PAGES == 'true'
- uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4
+ uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
with:
name: ${{ steps.pages_artifact_name.outputs.name }}
path: runner-e2e-merged-report/pages
@@ -1313,7 +1313,7 @@ jobs:
steps:
- name: Deploy to GitHub Pages
id: deployment
- uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4
+ uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1
with:
# If only this failed job is rerun, GitHub retains the successful
# publisher job's output from the earlier workflow attempt.
diff --git a/AGENTS.md b/AGENTS.md
index c957ca41ead..53f25d6d514 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -152,6 +152,10 @@ Notes:
## 7. Verification Before Hand-off
+[feature-map/README.md](feature-map/README.md) is an optional reference for user
+entry points, verification recipes, and coverage gaps. The map records coverage
+scope, not proof that a live journey passed.
+
Default local/agent test path:
```sh
diff --git a/DESIGN.md b/DESIGN.md
index ef852568573..9924f21bf91 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -43,6 +43,26 @@ action on the left and the primary action on the right. A step owns its whole
footer: do not render Save & exit in a separate parent block below it. Check this
alignment in every step and conditional state, not just the first screen.
+## Mobile navigation and text fields
+
+The fixed bottom navigation uses an opaque surface so scrolling content cannot
+show through its labels. On touch devices, editable controls use at least the
+16px base typography token to prevent Safari's automatic focus zoom. Larger
+title sizes remain larger.
+
+The bottom navigation responds to accumulated scrolling, ignoring small
+reversals and Safari's edge bounce. It glides out and eases back in with shared
+motion tokens; the task composer follows the same motion. Keep page padding
+stable while the navigation moves, and honor reduced-motion preferences.
+
+Task conversations reveal their initial comments, interaction cards, plan, and
+relevant run history together after positioning the latest message. Keep the
+mobile loading surface at a stable viewport height while that history loads;
+concealed content must not stretch the document. Background refreshes keep an
+already revealed conversation and composer mounted and visible.
+Bound the initial wait to 15 seconds. If a request stalls, reveal the available
+conversation and composer with a notice that some history is still loading.
+
## Contextual feedback
Task chat shows execution errors and waits only while they remain relevant.
@@ -66,10 +86,16 @@ paused.” and “Resume this task to send a message.” with a “Resume task
Subtrees use “Subtree is paused.” and “Resume subtree.” The takeover cannot be
dismissed, retains drafts, and hides message inputs until the pause is released.
+Confirmations whose source work is still syncing show “Preparing approval…” and
+disable acceptance until the server reports readiness. Refresh that state automatically;
+rejection and revision remain available. Live tool reviews keep their own approval flow.
+
Pending questions, confirmations, and other task-thread inputs appear in a separate
card directly above the ordinary composer. The composer stays available for new
-messages while the card is open. Dismissing a card leaves a pending indicator that
-can reopen it; resolving or skipping the input removes that indicator.
+messages while the card is open. Questions use their compact history entry as the
+reminder; dismissing one clears the composer and stays effective after reload for
+that person and task. Other inputs keep a pending indicator that can reopen them;
+resolving or skipping the input removes that indicator.
## Enforcement (what "compliant" means for the extraction run)
@@ -95,6 +121,8 @@ How-to guide for day-to-day UI changes: see `doc/design/CHANGING-THE-UI.md`.
## Motion tokens (Task Chat Redesign)
+Mobile task panels fill the viewport within the safe area. Their top toolbar shows the current tab title, an open-tab count and selector, an add action, and an X to return to the feed. The selector lists tabs vertically with wrapping titles, an explicit current-tab check, and visible close controls. Each touch control uses the 44px size token. Desktop tabs keep their horizontal layout. Document links within the current task open through the router and retain the feed's reading position and query cache.
+
The redesigned task thread (flag `enableTaskChatRedesign`) is the first surface to
tokenize motion. Principles — reasoning only; values live in `ui/src/index.css`:
@@ -119,4 +147,4 @@ tokenize motion. Principles — reasoning only; values live in `ui/src/index.css
block collapses the duration/stagger tokens to zero, cascading to every scoped token,
in addition to each animation's own component-level guard.
-Agent Chat keeps pending questions as compact “Unanswered question” entries at their original position in history. A newer user message dismisses the old question form without resolving it. Opening the history entry restores the original form and its draft; submitting later uses the same durable question response path. Actual permission reviews retain their permission checks.
+Agent Chat and regular task chats keep pending questions as compact “Unanswered question” entries at their original position in history. Dismissing the form or sending a newer user message clears it from the composer without resolving it. Questions never contribute to composer pending counts or navigation. Opening the history entry restores the original form and its draft; submitting later uses the same durable question response path. Actual permission reviews retain their permission checks.
diff --git a/README.md b/README.md
index b3f130123d8..a0db4476643 100644
--- a/README.md
+++ b/README.md
@@ -417,6 +417,9 @@ This starts the UI and API at `http://localhost:3100`. An embedded PostgreSQL da
> **Requirements:** Node.js 24.11+, pnpm 9.15+
+Local Claude and Codex subscription sign-in also needs Python 3 and the
+corresponding provider CLI on the Paperclip host. The Docker image includes them.
+
Source development also builds the native Paperclip Runner when enabled (the self-hosted default). Install a Rust toolchain, or set `PAPERCLIP_RUNNER_BINARY` to a compatible prebuilt runner.
diff --git a/cli/src/__tests__/mcp-auth.test.ts b/cli/src/__tests__/mcp-auth.test.ts
new file mode 100644
index 00000000000..fb600afe63b
--- /dev/null
+++ b/cli/src/__tests__/mcp-auth.test.ts
@@ -0,0 +1,113 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+import { once } from "node:events";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { credentialPath, mcpAccessToken, mcpResource, mcpRpc, replaceMcpCredential, withMcpCredentialLock } from "../client/mcp-auth.js";
+
+const resource = "https://paperclip.example/mcp/paperclip";
+let home: string;
+beforeEach(async () => { home = await fs.mkdtemp(path.join(os.tmpdir(), "mcp-credentials-")); vi.stubEnv("PAPERCLIP_HOME", home); });
+afterEach(async () => { vi.restoreAllMocks(); vi.unstubAllGlobals(); vi.unstubAllEnvs(); await fs.rm(home, { recursive: true, force: true }); });
+async function seed(value: unknown, mode = 0o600) {
+ const file = credentialPath(resource);
+ await fs.mkdir(path.dirname(file), { mode: 0o700 });
+ await fs.writeFile(file, typeof value === "string" ? value : JSON.stringify(value), { mode });
+ return file;
+}
+const stored = () => ({ resource, issuer: "https://paperclip.example", clientId: "client", companyId: "company", accessToken: "private-access", refreshToken: "private-refresh", expiresAt: 0 });
+describe("MCP protected credential transport", () => {
+ it("rejects noncanonical resources and isolates credential files by resource", () => {
+ for (const url of ["http://evil.example/mcp/paperclip", resource + "?token=secret", resource + "#x", "https://u:p@paperclip.example/mcp/paperclip", "https://paperclip.example/other"]) expect(() => mcpResource(url)).toThrow();
+ expect(mcpResource("http://127.0.0.1:3100/mcp/paperclip")).toContain("127.0.0.1");
+ expect(credentialPath(resource)).not.toBe(credentialPath("https://other.example/mcp/paperclip"));
+ });
+ it("serializes rotating refreshes and persists only the replacement token privately", async () => {
+ const file = await seed(stored()); let refreshes = 0;
+ vi.stubGlobal("fetch", vi.fn(async (url: string, init?: RequestInit) => {
+ expect(init?.redirect).toBe("error");
+ if (url.includes("oauth-protected-resource")) return Response.json({ resource, authorization_servers: ["https://paperclip.example"] });
+ if (url.includes("oauth-authorization-server")) return Response.json({ issuer: "https://paperclip.example", token_endpoint: "https://paperclip.example/mcp/oauth/token", device_authorization_endpoint: "https://paperclip.example/mcp/oauth/device_authorization", registration_endpoint: "https://paperclip.example/mcp/oauth/register" });
+ expect(url).toBe("https://paperclip.example/mcp/oauth/token");
+ expect(JSON.parse(init!.body as string).refresh_token).toBe("private-refresh"); refreshes++;
+ return Response.json({ access_token: "replacement-access", refresh_token: "replacement-refresh", token_type: "Bearer", expires_in: 900 });
+ }));
+ expect(await Promise.all([mcpAccessToken(resource), mcpAccessToken(resource)])).toEqual(["replacement-access", "replacement-access"]);
+ expect(refreshes).toBe(1);
+ expect((await fs.stat(file)).mode & 0o077).toBe(0);
+ expect(await fs.readFile(file, "utf8")).not.toContain("private-refresh");
+ });
+ it("never sends a stored credential to another issuer", async () => {
+ await seed({ ...stored(), issuer: "https://evil.example" }); const fetcher = vi.fn(); vi.stubGlobal("fetch", fetcher);
+ await expect(mcpAccessToken(resource)).rejects.toThrow("Connect first"); expect(fetcher).not.toHaveBeenCalled();
+ });
+ it("fails closed when discovery changes without sending refresh credentials", async () => {
+ await seed(stored()); const fetcher = vi.fn(async () => Response.json({ resource, authorization_servers: ["https://evil.example"] })); vi.stubGlobal("fetch", fetcher);
+ await expect(mcpAccessToken(resource)).rejects.toThrow("does not match"); expect(fetcher).toHaveBeenCalledTimes(1);
+ });
+ it("rejects readable or malformed credential files without echoing secrets", async () => {
+ const file = await seed(stored(), 0o644);
+ await expect(mcpAccessToken(resource)).rejects.toThrow("private");
+ await fs.chmod(file, 0o600); await fs.writeFile(file, '{private-secret');
+ await expect(mcpAccessToken(resource)).rejects.toThrow("Invalid MCP credential file. Sign in again.");
+ });
+ it("does not expose upstream response text in protocol errors or retry writes", async () => {
+ const fetcher = vi.fn(async () => new Response("private-upstream-token", { status: 200 })); vi.stubGlobal("fetch", fetcher);
+ await expect(mcpRpc(resource, "private-access", "tools/call", { name: "paperclip_create_task" })).rejects.toThrow("invalid response");
+ expect(fetcher).toHaveBeenCalledTimes(1);
+ });
+ it("releases the refresh mutex after failed work", async () => {
+ const file = credentialPath(resource);
+ await expect(withMcpCredentialLock(file, async () => { throw new Error("failed"); })).rejects.toThrow("failed");
+ await expect(withMcpCredentialLock(file, async () => "recovered")).resolves.toBe("recovered");
+ });
+ it("recovers an OS mutex after its owner is killed without a stale-file takeover", async () => {
+ const file = await seed(stored());
+ await fs.writeFile(file + ".mutex.sqlite", "", { mode: 0o600 });
+ const child = spawn(process.execPath, ["--input-type=module", "-e", 'import {DatabaseSync} from "node:sqlite"; const db=new DatabaseSync(process.argv[1]); db.exec("BEGIN IMMEDIATE"); console.log("locked"); setInterval(()=>{},1000);', file + ".mutex.sqlite"], { stdio: ["ignore", "pipe", "pipe"] });
+ try {
+ await once(child.stdout!, "data");
+ let entered = false;
+ const next = withMcpCredentialLock(file, async () => { entered = true; return "recovered"; });
+ await new Promise(resolve => setTimeout(resolve, 150));
+ expect(entered).toBe(false);
+ const exit = once(child, "exit"); child.kill("SIGKILL"); await exit;
+ await expect(next).resolves.toBe("recovered");
+ } finally { child.kill("SIGKILL"); }
+ });
+ it("preserves a working connection when replacement storage fails", async () => {
+ const file = await seed(stored());
+ const fetcher = vi.fn(); vi.stubGlobal("fetch", fetcher);
+ vi.spyOn(fs, "rename").mockRejectedValueOnce(new Error("disk failure"));
+ await expect(replaceMcpCredential(file, { ...stored(), accessToken: "new-access" }, vi.fn())).rejects.toThrow("disk failure");
+ expect(JSON.parse(await fs.readFile(file, "utf8")).accessToken).toBe("private-access");
+ expect(fetcher).not.toHaveBeenCalled();
+ });
+ it("keeps the OS lock held while a same-process caller waits", async () => {
+ const file = await seed(stored());
+ let release!: () => void;
+ let entered!: () => void;
+ const ready = new Promise(resolve => { entered = resolve; });
+ const held = new Promise(resolve => { release = resolve; });
+ const first = withMcpCredentialLock(file, async () => { entered(); await held; });
+ await ready;
+ let secondEntered = false;
+ const second = withMcpCredentialLock(file, async () => { secondEntered = true; });
+ try {
+ await new Promise(resolve => setTimeout(resolve, 100));
+ const probe = spawnSync(process.execPath, ["--input-type=module", "-e", 'import{DatabaseSync}from"node:sqlite";const db=new DatabaseSync(process.argv[1]);try{db.exec("BEGIN IMMEDIATE");process.exitCode=0}catch(e){process.exitCode=e.errcode===5?5:1}finally{db.close()}', file + ".mutex.sqlite"]);
+ expect(probe.status).toBe(5);
+ expect(secondEntered).toBe(false);
+ } finally { release(); await Promise.all([first, second]); }
+ });
+ it("retains the new saved credential and reports failed previous-grant cleanup", async () => {
+ const file = await seed(stored()); const notify = vi.fn();
+ vi.stubGlobal("fetch", vi.fn(async () => {
+ expect(JSON.parse(await fs.readFile(file, "utf8")).accessToken).toBe("new-access");
+ return new Response(null, { status: 503 });
+ }));
+ await replaceMcpCredential(file, { ...stored(), accessToken: "new-access" }, notify);
+ expect(notify).toHaveBeenCalledWith(expect.stringContaining("revoke it in Paperclip Connections"));
+ });
+});
diff --git a/cli/src/__tests__/worktree.test.ts b/cli/src/__tests__/worktree.test.ts
index 0fb6b2aee32..6d36e060357 100644
--- a/cli/src/__tests__/worktree.test.ts
+++ b/cli/src/__tests__/worktree.test.ts
@@ -511,7 +511,8 @@ describe("worktree helpers", () => {
expect(minimal.excludedTables).toContain("agent_task_sessions");
expect(minimal.nullifyColumns.issues).toEqual(["checkout_run_id", "execution_run_id"]);
- expect(full.excludedTables).toEqual([]);
+ expect(full.excludedTables).toEqual(["agent_identity_keys"]);
+ expect(minimal.excludedTables).toContain("agent_identity_keys");
expect(full.nullifyColumns).toEqual({});
});
@@ -1661,10 +1662,13 @@ describe("worktree helpers", () => {
// A lagging source must also have the prior schema. Deleting only the
// newest receipt from a fully migrated schema relied on that particular
// migration being idempotent and breaks when the new migration creates a
- // table. Build the actual all-but-last schema before shuffling its history.
+ // table. Build the schema before the identity-repair migration, so this
+ // regression keeps testing that repair as later migrations are added.
const migrationsRoot = new URL("../../../packages/db/src/migrations/", import.meta.url);
const journal = JSON.parse(fs.readFileSync(new URL("meta/_journal.json", migrationsRoot), "utf8"));
- const priorEntries = journal.entries.slice(0, -1);
+ const repairIndex = journal.entries.findIndex((entry: { tag: string }) => entry.tag === "0309_loving_the_hood");
+ expect(repairIndex).toBeGreaterThan(0);
+ const priorEntries = journal.entries.slice(0, repairIndex);
const priorMigrations = path.join(tempRoot, "prior-migrations");
fs.mkdirSync(path.join(priorMigrations, "meta"), { recursive: true });
fs.writeFileSync(path.join(priorMigrations, "meta", "_journal.json"), JSON.stringify({ ...journal, entries: priorEntries }));
@@ -1673,7 +1677,19 @@ describe("worktree helpers", () => {
}
const sourceDbClient = createDb(sourceDb.connectionString);
await migrate(drizzle(sourceDbClient.$client), { migrationsFolder: priorMigrations });
- await seedValidWorktreeSource(sourceDb.connectionString);
+ const seed = await seedValidWorktreeSource(sourceDb.connectionString);
+ // An older filtered JavaScript backup retained event IDs but lost the
+ // identity generator. The pending migration must repair that schema.
+ const legacyAgentId = randomUUID();
+ await sourceDbClient.$client`
+ INSERT INTO agents (id, company_id, name, status)
+ VALUES (${legacyAgentId}, ${seed.companyId}, 'Legacy paused agent', 'paused')
+ `;
+ await sourceDbClient.$client`
+ INSERT INTO resource_lifecycle_events (company_id, resource_type, resource_id, action)
+ VALUES (${seed.companyId}, 'agent', ${legacyAgentId}, 'pause')
+ `;
+ await sourceDbClient.$client.unsafe('ALTER TABLE resource_lifecycle_events ALTER COLUMN id DROP IDENTITY');
await sourceDbClient.$client.unsafe(`
WITH pair AS (
SELECT
@@ -1704,7 +1720,7 @@ describe("worktree helpers", () => {
if (laggingMigrationState.status !== "needsMigrations") {
throw new Error("Expected the source migration journal to lag the code journal");
}
- expect(laggingMigrationState.pendingMigrations).toHaveLength(1);
+ expect(laggingMigrationState.pendingMigrations).toHaveLength(journal.entries.length - repairIndex);
const expectedAppliedPrefix = laggingMigrationState.availableMigrations.slice(
0,
laggingMigrationState.appliedMigrations.length,
@@ -1786,6 +1802,16 @@ describe("worktree helpers", () => {
);
const seededUsers = await targetDb.select().from(authUsers);
expect(seededUsers.some((row) => row.email === "existing@paperclip.ing")).toBe(true);
+ const restoredEvents = await targetDb.$client`
+ SELECT id, action FROM resource_lifecycle_events WHERE resource_id = ${legacyAgentId} ORDER BY id
+ `;
+ expect(restoredEvents.map(row => row.action)).toEqual(["pause", "create"]);
+ expect(Number(restoredEvents[1].id)).toBeGreaterThan(Number(restoredEvents[0].id));
+ const [identity] = await targetDb.$client`
+ SELECT is_identity FROM information_schema.columns
+ WHERE table_schema = 'public' AND table_name = 'resource_lifecycle_events' AND column_name = 'id'
+ `;
+ expect(identity.is_identity).toBe("YES");
},
);
@@ -2045,8 +2071,8 @@ describe("worktree helpers", () => {
}
});
- it("uses streaming backup selection for full seeds and transformed backup selection for minimal seeds", () => {
- expect(resolveWorktreeSeedBackupEngine(resolveWorktreeSeedPlan("full"))).toBe("auto");
+ it("uses transformed backups for both seed modes to omit agent identities", () => {
+ expect(resolveWorktreeSeedBackupEngine(resolveWorktreeSeedPlan("full"))).toBe("javascript");
expect(resolveWorktreeSeedBackupEngine(resolveWorktreeSeedPlan("minimal"))).toBe("javascript");
});
diff --git a/cli/src/client/mcp-auth.ts b/cli/src/client/mcp-auth.ts
new file mode 100644
index 00000000000..47e185a9b2c
--- /dev/null
+++ b/cli/src/client/mcp-auth.ts
@@ -0,0 +1,210 @@
+import fs from "node:fs/promises";
+import { constants } from "node:fs";
+import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { createHash, randomUUID } from "node:crypto";
+import { setTimeout as sleep } from "node:timers/promises";
+import { PUBLIC_MCP_PATH, PUBLIC_MCP_SCOPES } from "@paperclipai/shared";
+import { resolvePaperclipHomeDir } from "../config/home.js";
+
+const deviceGrant = "urn:ietf:params:oauth:grant-type:device_code";
+type Json = Record;
+export interface McpCredential {
+ resource: string; issuer: string; clientId: string; companyId: string;
+ accessToken: string; refreshToken?: string; expiresAt: number;
+}
+export function mcpResource(raw: string) {
+ const url = new URL(raw);
+ if ((url.protocol !== "https:" && !(url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)))
+ || url.username || url.password || url.search || url.hash || url.pathname !== PUBLIC_MCP_PATH) throw new Error("Use the exact Paperclip HTTPS MCP URL from Connections.");
+ return url.toString();
+}
+export function credentialPath(resource: string) {
+ return path.join(resolvePaperclipHomeDir(), "mcp", createHash("sha256").update(resource).digest("hex") + ".json");
+}
+async function readCredential(file: string): Promise {
+ let handle;
+ try { handle = await fs.open(file, constants.O_RDONLY | constants.O_NOFOLLOW); }
+ catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return null; throw error; }
+ try {
+ const stat = await handle.stat();
+ if (!stat.isFile() || (stat.mode & 0o077) !== 0) throw new Error("MCP credential file must be private (mode 0600).");
+ let value: McpCredential;
+ try { value = JSON.parse(await handle.readFile("utf8")); }
+ catch { throw new Error("Invalid MCP credential file. Sign in again."); }
+ if (!value || typeof value !== "object" || ![value.resource, value.issuer, value.clientId, value.companyId, value.accessToken].every(v => typeof v === "string" && v.length > 0)
+ || !Number.isFinite(value.expiresAt) || (value.refreshToken !== undefined && typeof value.refreshToken !== "string")) throw new Error("Invalid MCP credential file. Sign in again.");
+ return value;
+ } finally { await handle.close(); }
+}
+async function saveCredential(file: string, credential: McpCredential) {
+ const temporary = file + "." + randomUUID();
+ try {
+ await fs.writeFile(temporary, JSON.stringify(credential), { mode: 0o600, flag: "wx" });
+ await fs.rename(temporary, file);
+ } finally { await fs.unlink(temporary).catch(() => {}); }
+}
+
+/** One refresh owner per resource, including independent CLI/bridge processes. */
+const processLocks = new Map>();
+export async function withMcpCredentialLock(file: string, work: () => Promise) {
+ const key = path.resolve(file);
+ const previous = processLocks.get(key) ?? Promise.resolve();
+ let release!: () => void;
+ const current = new Promise(resolve => { release = resolve; });
+ processLocks.set(key, current);
+ await previous;
+ try { return await withMcpOsLock(key, work); }
+ finally {
+ release();
+ if (processLocks.get(key) === current) processLocks.delete(key);
+ }
+}
+
+async function withMcpOsLock(file: string, work: () => Promise) {
+ const directory = path.dirname(file);
+ await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+ const stat = await fs.lstat(directory);
+ if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o077) !== 0) throw new Error("The MCP credential directory must be private (mode 0700).");
+ // SQLite's OS lock is released when a process exits, including during acquisition.
+ // No PID-file deletion or stale-lock takeover can race a new refresh owner.
+ const lockPath = file + ".mutex.sqlite";
+ // Never open/close an existing SQLite file outside SQLite: POSIX close can
+ // release another connection's process-owned lock. The in-process queue also
+ // serializes initial file creation before any SQLite descriptor is opened.
+ try {
+ await fs.writeFile(lockPath, "", { flag: "wx", mode: 0o600 });
+ } catch (error) { if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; }
+ const lockStat = await fs.lstat(lockPath);
+ if (!lockStat.isFile() || lockStat.isSymbolicLink() || (lockStat.mode & 0o077) !== 0) throw new Error("The MCP mutex file must be private (mode 0600).");
+ const lock = new DatabaseSync(lockPath);
+ const deadline = Date.now() + 30_000;
+ try {
+ lock.exec("PRAGMA busy_timeout = 0");
+ while (true) {
+ try { lock.exec("BEGIN IMMEDIATE"); break; }
+ catch (error) {
+ if ((error as { errcode?: number }).errcode !== 5) throw error;
+ if (Date.now() >= deadline) throw new Error("Another Paperclip MCP login or refresh is in progress. Try again.");
+ await sleep(100);
+ }
+ }
+ try { return await work(); }
+ finally { lock.exec("ROLLBACK"); }
+ } finally { lock.close(); }
+
+}
+
+async function jsonRequest(url: string, body?: Json) {
+ const response = await fetch(url, { redirect: "error", signal: AbortSignal.timeout(20_000),
+ ...(body ? { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) } : {}) });
+ const data = await safeJson(response);
+ return { ok: response.ok, data };
+}
+async function safeJson(response: Response): Promise {
+ try {
+ const value = await response.json();
+ if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error();
+ return value as Json;
+ } catch { throw new Error("Paperclip returned an invalid response. Check the connection before retrying."); }
+}
+async function revoke(credential: McpCredential) {
+ const response = await fetch(credential.issuer + "/mcp/oauth/revoke", { method: "POST", redirect: "error", signal: AbortSignal.timeout(20_000),
+ headers: { "Content-Type": "application/json" }, body: JSON.stringify({ client_id: credential.clientId, token: credential.refreshToken ?? credential.accessToken }) });
+ if (!response.ok) throw new Error("Could not revoke the previous connection.");
+}
+async function discovery(resource: string) {
+ const origin = new URL(resource).origin;
+ const protectedResource = await jsonRequest(origin + "/.well-known/oauth-protected-resource" + PUBLIC_MCP_PATH);
+ if (!protectedResource.ok || protectedResource.data.resource !== resource || !Array.isArray(protectedResource.data.authorization_servers)
+ || !protectedResource.data.authorization_servers.includes(origin)) throw new Error("Paperclip resource discovery does not match this instance.");
+ const metadata = await jsonRequest(origin + "/.well-known/oauth-authorization-server");
+ if (!metadata.ok || metadata.data.issuer !== origin || metadata.data.token_endpoint !== origin + "/mcp/oauth/token"
+ || metadata.data.device_authorization_endpoint !== origin + "/mcp/oauth/device_authorization"
+ || metadata.data.registration_endpoint !== origin + "/mcp/oauth/register") throw new Error("This Paperclip instance does not support device login.");
+ return origin;
+}
+function tokens(data: Json, credential: Omit): McpCredential {
+ if (typeof data.access_token !== "string" || data.token_type !== "Bearer" || typeof data.expires_in !== "number" || data.expires_in <= 0) throw new Error("Invalid Paperclip token response. Reconnect.");
+ return { ...credential, accessToken: data.access_token, expiresAt: Date.now() + data.expires_in * 1000,
+ ...(typeof data.refresh_token === "string" ? { refreshToken: data.refresh_token } : {}) };
+}
+export async function mcpRpc(resource: string, token: string, method: string, params: Json = {}) {
+ const version = "2026-07-28";
+ const response = await fetch(resource, { method: "POST", redirect: "error", signal: AbortSignal.timeout(60_000),
+ headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", "MCP-Protocol-Version": version, "Mcp-Method": method,
+ ...(method === "tools/call" && typeof params.name === "string" ? { "Mcp-Name": params.name } : {}) },
+ body: JSON.stringify({ jsonrpc: "2.0", id: randomUUID(), method, params: { ...params, _meta: {
+ "io.modelcontextprotocol/protocolVersion": version, "io.modelcontextprotocol/clientCapabilities": {},
+ "io.modelcontextprotocol/clientInfo": { name: "Paperclip CLI", version: "1" },
+ } } }),
+ });
+ if (!response.ok) throw new Error(`Paperclip MCP returned HTTP ${response.status}. Check the connection before retrying; a write may already have completed.`);
+ const data = await safeJson(response);
+ if (data.error || !data.result || typeof data.result !== "object") throw new Error("Paperclip could not complete this MCP request. Check the connection before retrying.");
+ return data.result as Json;
+}
+
+export async function loginMcpDevice(raw: string, companyId?: string, notify: (message: string) => void = console.error) {
+ const resource = mcpResource(raw);
+ const issuer = await discovery(resource);
+ const registration = await jsonRequest(issuer + "/mcp/oauth/register", { client_name: "Paperclip CLI (device)", redirect_uris: [], grant_types: [deviceGrant, "refresh_token"], response_types: [], token_endpoint_auth_method: "none" });
+ if (!registration.ok || typeof registration.data.client_id !== "string") throw new Error("Could not register the Paperclip device client.");
+ const clientId = registration.data.client_id;
+ const authorization = await jsonRequest(issuer + "/mcp/oauth/device_authorization", { client_id: clientId, resource, scope: PUBLIC_MCP_SCOPES.join(" "), ...(companyId ? { company_id: companyId } : {}) });
+ const device = authorization.data;
+ if (!authorization.ok || typeof device.device_code !== "string" || typeof device.user_code !== "string"
+ || device.verification_uri !== issuer + "/mcp-device" || typeof device.expires_in !== "number") throw new Error("Could not start device authorization.");
+ const verification = new URL(device.verification_uri); verification.searchParams.set("user_code", device.user_code);
+ notify(`Approve Paperclip access in your browser: ${verification}\nConfirm code: ${device.user_code}\nWaiting for your approval…`);
+ let interval = typeof device.interval === "number" ? Math.max(5, device.interval) : 5;
+ const deadline = Date.now() + Math.min(600, device.expires_in) * 1000;
+ while (Date.now() < deadline) {
+ await sleep(interval * 1000);
+ const result = await jsonRequest(issuer + "/mcp/oauth/token", { grant_type: deviceGrant, client_id: clientId, resource, device_code: device.device_code });
+ if (!result.ok) {
+ if (result.data.error === "authorization_pending") continue;
+ if (result.data.error === "slow_down") { interval += 5; continue; }
+ throw new Error(result.data.error === "access_denied" ? "Connection declined. No access was granted." : "Device authorization expired or failed. Start login again.");
+ }
+ const credential = tokens(result.data, { resource, issuer, clientId, companyId: companyId ?? "" });
+ const identity = await mcpRpc(resource, credential.accessToken, "tools/call", { name: "paperclip_connection", arguments: {} });
+ const connected = identity.structuredContent as Json | undefined;
+ if (identity.isError || typeof connected?.companyId !== "string" || (companyId && connected.companyId !== companyId)) throw new Error("The approved organization did not match. Reconnect before doing work.");
+ credential.companyId = connected.companyId;
+ const file = credentialPath(resource);
+ await replaceMcpCredential(file, credential, notify);
+ return { resource, companyId: credential.companyId };
+ }
+ throw new Error("Device authorization expired. Start login again.");
+}
+
+export async function replaceMcpCredential(file: string, credential: McpCredential, notify: (message: string) => void) {
+ await withMcpCredentialLock(file, async () => {
+ const previous = await readCredential(file);
+ // Persist the working replacement before changing authority on the server.
+ await saveCredential(file, credential);
+ if (previous && previous.resource === credential.resource && previous.issuer === credential.issuer) {
+ try { await revoke(previous); }
+ catch { notify("Connected. The previous connection could not be revoked; revoke it in Paperclip Connections."); }
+ }
+ });
+}
+
+export async function mcpAccessToken(raw: string) {
+ const resource = mcpResource(raw);
+ const file = credentialPath(resource);
+ return withMcpCredentialLock(file, async () => {
+ const credential = await readCredential(file);
+ if (!credential || credential.resource !== resource || credential.issuer !== new URL(resource).origin) throw new Error("Connect first with paperclipai mcp login --device --url .");
+ if (credential.expiresAt > Date.now() + 30_000) return credential.accessToken;
+ if (!credential.refreshToken) throw new Error("Paperclip access expired. Sign in again.");
+ // Validate issuer discovery again before sending a stored credential.
+ await discovery(resource);
+ const result = await jsonRequest(credential.issuer + "/mcp/oauth/token", { grant_type: "refresh_token", client_id: credential.clientId, resource, refresh_token: credential.refreshToken });
+ if (!result.ok) throw new Error("Paperclip access was revoked or expired. Sign in again.");
+ const updated = tokens(result.data, credential);
+ await saveCredential(file, updated);
+ return updated.accessToken;
+ });
+}
diff --git a/cli/src/commands/mcp.ts b/cli/src/commands/mcp.ts
new file mode 100644
index 00000000000..bf080ae04b6
--- /dev/null
+++ b/cli/src/commands/mcp.ts
@@ -0,0 +1,38 @@
+import type { Command } from "commander";
+import { createInterface } from "node:readline";
+import { loginMcpDevice, mcpAccessToken, mcpResource, mcpRpc } from "../client/mcp-auth.js";
+
+export function registerMcpCommands(program: Command) {
+ const mcp = program.command("mcp").description("Connect an assistant to Paperclip as a consenting human");
+ mcp.command("login").requiredOption("--device", "Authorize in a browser without a callback listener")
+ .requiredOption("--url ", "Canonical Paperclip MCP URL").option("--company ", "Restrict consent to this organization")
+ .action(async (options: { url: string; company?: string }) => {
+ const result = await loginMcpDevice(options.url, options.company);
+ console.log(`Connected to ${result.resource}\nOrganization: ${result.companyId}`);
+ });
+ mcp.command("proxy").description("Expose the authorized Paperclip tools over local MCP stdio")
+ .requiredOption("--url ", "The exact MCP URL used during login")
+ .action(async (options: { url: string }) => {
+ const resource = mcpResource(options.url);
+ const lines = createInterface({ input: process.stdin, crlfDelay: Infinity });
+ for await (const line of lines) {
+ let message: { id?: string | number; method?: string; params?: Record };
+ if (Buffer.byteLength(line) > 1024 * 1024) continue;
+ try { message = JSON.parse(line); } catch { continue; }
+ if (!message || typeof message !== "object" || Array.isArray(message)) continue;
+ if (message.id === undefined) continue;
+ try {
+ let result: unknown;
+ if (message.method === "initialize") result = { protocolVersion: "2025-03-26", capabilities: { tools: {} }, serverInfo: { name: "paperclip", version: "1" } };
+ else if (message.method === "ping") result = {};
+ else if (message.method === "tools/list" || message.method === "tools/call") result = await mcpRpc(resource, await mcpAccessToken(resource), message.method, message.params ?? {});
+ else { process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id: message.id, error: { code: -32601, message: "Method not supported." } }) + "\n"); continue; }
+ process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id: message.id, result }) + "\n");
+ } catch (error) {
+ // Never log request arguments, raw provider responses, or credentials.
+ const text = "Paperclip connection failed. Check access before retrying; a write may already have completed.";
+ process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id: message.id, error: { code: -32603, message: text } }) + "\n");
+ }
+ }
+ });
+}
diff --git a/cli/src/commands/worktree-lib.ts b/cli/src/commands/worktree-lib.ts
index 4cdf7ef5364..8d3aa01f6fe 100644
--- a/cli/src/commands/worktree-lib.ts
+++ b/cli/src/commands/worktree-lib.ts
@@ -58,6 +58,7 @@ export type WorktreeSeedPlan = {
};
const MINIMAL_WORKTREE_EXCLUDED_TABLES = [
+ "agent_identity_keys",
"activity_log",
"agent_runtime_state",
"agent_task_sessions",
@@ -118,7 +119,7 @@ export function resolveWorktreeSeedPlan(mode: WorktreeSeedMode): WorktreeSeedPla
if (mode === "full") {
return {
mode,
- excludedTables: [],
+ excludedTables: ["agent_identity_keys"],
nullifyColumns: {},
};
}
diff --git a/cli/src/index.ts b/cli/src/index.ts
index b2f722a4a00..8d924786bf0 100644
--- a/cli/src/index.ts
+++ b/cli/src/index.ts
@@ -1,4 +1,5 @@
import { registerEmailCommands } from "./commands/client/email.js";
+import { registerMcpCommands } from "./commands/mcp.js";
import { Command } from "commander";
import { warnIfUnsupportedNodeVersion } from "@paperclipai/shared/node-version";
import { onboard } from "./commands/onboard.js";
@@ -276,6 +277,7 @@ auth
.action(bootstrapCeoInvite);
registerClientAuthCommands(auth);
+registerMcpCommands(program);
async function main(): Promise {
warnIfUnsupportedNodeVersion(process.versions.node, (message) => console.warn(message));
diff --git a/doc/AGENT-IDENTITY.md b/doc/AGENT-IDENTITY.md
new file mode 100644
index 00000000000..f8dabb3c54a
--- /dev/null
+++ b/doc/AGENT-IDENTITY.md
@@ -0,0 +1,100 @@
+# Agent cryptographic identity
+
+Each agent has one persistent Ed25519 keypair. New agents receive it in the
+agent-creation transaction. Existing agents receive it when Paperclip prepares
+their next managed run. Migration, startup, public API reads, and opening the
+agent page do not provision existing agents. There is no backfill command.
+
+## Storage
+
+`agent_identity_keys` lives in the agent's home instance database, including a
+hosted stack's database. Its agent primary key and composite company/agent
+foreign key enforce one identity and company-consistent ownership. Deleting an
+agent cascades to its identity. Creation locks the agent row inside a transaction,
+so simultaneous first runs use the same stored pair.
+
+Public keys use SPKI PEM and private keys use PKCS#8 PEM. `keyId` is `sha256:`
+followed by the base64url SHA-256 digest of the public key's SPKI DER bytes.
+Private material is encrypted using the existing `local_encrypted` provider and
+stored separately from company secrets. The wrapping key is the stack's
+`PAPERCLIP_SECRETS_MASTER_KEY` or the local instance's secrets master-key file.
+The file is published atomically with mode `0600` on first use. No per-agent
+Cloud secret or Cloud registry record is needed.
+
+Decryption and public/private key validation happen before launch. A wrong
+master key, corrupt ciphertext, or mismatched public key fails the run; none
+causes automatic key replacement. Renames, model changes, pauses, resumes, and
+restarts preserve the keypair.
+
+## Managed runs
+
+Paperclip supplies these server-owned environment variables:
+
+```text
+PAPERCLIP_AGENT_KEY_ID
+PAPERCLIP_AGENT_PUBLIC_KEY
+PAPERCLIP_AGENT_PRIVATE_KEY
+```
+
+The two key values are multiline PEM strings. Runtime-only adapter context and
+native runner environment fields deliver them to managed processes. Configured
+or inherited environment values cannot replace the assigned identity. Session
+compatibility includes the public key ID, so an older warm process is replaced
+before its next turn. Private values are excluded from invocation metadata and
+execution configuration; output and failure diagnostics redact known private
+material. The run-log redactor handles split stdout/stderr chunks independently.
+Native output deltas also buffer potential key fragments before persistence.
+Raw provider trace contents are suppressed for identity-enabled runs; trace
+routing, timing, and interpretation metadata remain available.
+
+Managed remote providers, including Cursor Cloud, receive the same private key
+as managed local processes. Selecting a runtime therefore trusts its host with
+the agent's persistent identity: the agent and its host can retain the key and
+sign outside Paperclip. Encryption at rest protects database storage, not an
+executing runtime. Move an agent only between runtime hosts trusted with that
+identity.
+
+Independently hosted HTTP and gateway agents, including Runner's API-hosted Claude Managed and AWS AgentCore providers, do not receive private keys in v1.
+Their new agent records still get stored identities; their existing records stay
+unprovisioned until a supported managed run.
+
+An agent can sign using an ordinary cryptographic library, for example Node.js:
+
+```js
+import { sign } from "node:crypto";
+const signature = sign(null, challengeBytes, process.env.PAPERCLIP_AGENT_PRIVATE_KEY);
+```
+
+This identity does not change Paperclip bearer-token authentication. There is no
+signing API, private-key download endpoint, Git integration, rotation UI, or
+external-key import. Agents possess their private keys. External consumers must
+define their own authorization, expiry, and revocation rules.
+
+## Public identity
+
+`GET /api/agents/:id/identity` applies the existing agent-read access checks. It
+returns `null` before provisioning, otherwise:
+
+```ts
+{ algorithm: "Ed25519", keyId: string, publicKeyPem: string, createdAt: string }
+```
+
+The agent's Identity section shows a shortened fingerprint and copies the full
+public PEM. Before provisioning it shows “Not created yet” and explains that
+creation happens on the next managed run.
+
+## Copies and recovery
+
+Company/template imports and duplication use normal agent creation and get new
+identities. Minimal and full development seeds omit identity **rows**, while
+retaining the schema, even with live-work preservation. Those copied agents get
+fresh identities on their next managed runs.
+
+Ordinary disaster-recovery backups include encrypted identities. Recovery needs
+both the database and the matching wrapping key; back up the key separately.
+Do not use a disaster-recovery backup as a development clone when agents should
+have distinct identities.
+
+Native failure records and reports redact the assigned key before truncating diagnostics. Streaming output buffers settle at item or turn completion: short structural prefixes (such as a trailing dash) are preserved, longer interrupted key fragments become redaction markers, and pending buffers are cleared. Terminal events carry these settled `outputTails`; transcript projection displays them as deltas without changing the source event receipt.
+
+Codex shell delivery preserves its default `KEY`/`SECRET`/`TOKEN` name exclusions for other configured credentials. The exceptions are the three identity variables and `PAPERCLIP_API_KEY`: the latter is the short-lived, scoped run/bridge credential required by the Paperclip agent skill’s Bash/curl API calls. Disabling Codex’s automatic exclusions is paired with this explicit filtered allowlist; it does not admit arbitrary host environment variables. Provider authentication secrets can still reach the provider process without being newly exposed to shell commands by this feature.
diff --git a/doc/DATABASE.md b/doc/DATABASE.md
index b6258c21acb..c6d747b45bc 100644
--- a/doc/DATABASE.md
+++ b/doc/DATABASE.md
@@ -177,12 +177,20 @@ idempotent actor synchronization operations, not arbitrary transactions. A
persistent outage still fails the request after the bounded retries; each
connection attempt remains subject to the configured database connect timeout.
-The dashboard's company lookup, task counts, pending approval count, and
-monthly spend each retry these connection errors at most twice. Each callback
-is read-only and rebuilds its query for each attempt. A failed read
-does not replay completed reads or the budget workflow. Missing companies,
-authentication errors, and other database errors propagate without retry.
-This does not enable general SQL replay.
+The dashboard's company lookup, agent and task counts, pending approval count,
+monthly spend, and run activity aggregate each retry these connection errors
+at most twice. The heartbeat run list and base issue lookup by UUID or identifier
+use the same bounded retries. Each callback is read-only and rebuilds its query
+for each attempt. A failed read does not replay completed reads, the budget
+workflow, or issue label and watchdog enrichment. Missing resources,
+authentication errors, and other database errors retain their usual behavior.
+This does not enable general SQL replay or retry a full request.
+
+The task run list also opts its execution-status projection into these bounded
+retries. Each of its four read-only lookups rebuilds only the failed query;
+completed lookups and the separate liveness backfill are not replayed. Projection
+callers that use a transaction retain single-attempt reads. The opt-in is only
+for a pooled database handle outside a transaction.
## Execution identity row locks
@@ -239,6 +247,38 @@ public identity, and the existing unique singleton-key index makes concurrent
or later attempts to replace it fail closed. The server loads the row before
constructing URL-dependent runtime services on every boot.
+### Unclaimed Cloud warm standby
+
+`PAPERCLIP_CLOUD_WARM_STANDBY=1` is an opt-in control-plane marker for an
+unclaimed warm application. It requires Cloud configuration, a stack identity,
+and runtime identity verification keys. After restoring the durable identity,
+startup checks once for company data. Existing companies or a persisted claim
+keep the application fully active. A failed database check fails startup.
+
+An empty unclaimed application keeps its HTTP server and sandbox plugins ready,
+but skips recurring database work: chat/email delivery, plugin jobs, browser
+cleanup, feedback export, import cleanup, execution reconciliation, heartbeat
+schedules, and automatic backups. Startup migrations, plugin installation, and
+other one-time preparation still run. Normal anonymous health probes return
+`warmStandby: true` without SQL or session lookups. This is application liveness,
+not a current database connectivity check. Other API requests and WebSocket upgrades return 503 until
+the signed claim succeeds. Page and asset requests serve only the static UI
+router, bypassing session, bearer-key, tenant, and other dynamic handlers.
+
+The existing signed claim on `GET /api/health` writes the identity durably before
+normal requests and polling resume. No polling discovers claims and no process
+restart is required. Timers resume on their next normal tick; request-driven
+work can proceed immediately. Claim failure leaves standby intact. A restart
+restores the claim even if provider environment alignment has not completed.
+Deleting a claimed workspace's last company never puts it back into standby.
+
+Deploy support before enabling the marker. Validate idle database transactions
+and health probes, claim/bootstrap latency, recurring work after claim, and a
+restart with stale provider variables on an isolated warm application first.
+Rollback by setting the marker to `0` and restarting. No schema changes are
+required. This mechanism does not sleep claimed workspaces or replace a durable
+scheduler for their background work.
+
## Resource membership tables
Paperclip stores current-user sidebar membership state in:
@@ -450,6 +490,74 @@ Hosted AWS provider notes live in [SECRETS-AWS-PROVIDER.md](./SECRETS-AWS-PROVID
Migration `0274_agent_chat.sql` adds conversation identity/state and session generation/boundary columns to `issues`, plus idempotent client request IDs and processed session-boundary generations to `issue_comments`. The company/agent/user unique index resolves concurrent first writes to one issue. A check constraint preserves the assigned-agent identity and prevents terminal conversation status. Comment request IDs are unique per issue and user. There is no separate chat/message store. Provider sessions continue to use `agent_task_sessions`; `/new` removes only the matching conversation session, and session writers fence stale generations against the issue row.
+## Resource lifecycle events
+
+`resource_lifecycle_events` records content-free lifecycle hooks in the same
+transaction as the resource change. Hired agents and new projects emit `create`.
+Pending hires emit creation only when `activatePendingApproval` succeeds.
+Rejected hires emit termination without creation. Agents created as terminated
+emit no creation event. Capture is generic and works on self-hosted and managed
+instances; recording an event does not authorize a provider operation.
+
+A partial unique `(company_id, resource_type, resource_id)` index deduplicates
+creation. Each actual agent pause, resume, or termination appends another event,
+including budget actions and generic status updates. The agent row stays locked
+until status and event commit, so concurrent repeat requests emit one hook.
+Project edits and workspace additions, updates, and removals append `update`.
+Repository replacement emits one aggregate update; project creation with repositories
+emits only creation. Project mutations hold the project row lock until their record
+commits. An active-to-archived transition emits `archive`; restoring an archived
+project emits `update`. Repeat archive or restore requests emit no new status
+record. An edit combined with archive emits `update` followed by `archive` in
+the same transaction. Archiving preserves workspace records and authorizes no
+provider cleanup.
+Termination commits API-key revocation in that same transaction.
+Hire approval and rejection commit with agent activation or termination, so a
+failed event write leaves the decision pending and retryable.
+
+Creation is delivered first for each resource, including a backfilled creation
+whose ID is newer than earlier captured transitions. The remaining events follow
+numeric ID order. Plugin delivery
+must enforce company scope, preserve resource order, and track acknowledgments
+per plugin. A global high-water mark can skip transactions that have not yet
+committed; it is not a safe delivery cursor. The journal stores only identity,
+action, and timestamps, not repository snapshots, credentials, provider config,
+or resource health. Company deletion cascades to its events. Resource deletion
+retains events, so consumers must revalidate existence and eligibility and load
+current authorized repository data. A termination hook does not authorize
+provider cleanup without the plugin's own authorization and retention policy.
+
+Migration `0309_loving_the_hood.sql` seeds a one-time current-state baseline before
+plugin delivery is available. It records creation for existing hired agents and
+all projects, including archived projects. Pending hires stay behind approval.
+Paused and terminated agents receive missing final status intents. A partial
+journal ending at pause receives resume when the current agent is running.
+Archived projects receive missing archive intents. A partial journal ending at
+archive receives update when the current project is active.
+Existing records remain intact, and rerunning the baseline does not duplicate it.
+The migration also repairs the journal ID generator in older JavaScript restores
+that lost identity metadata, starting above existing IDs. New JavaScript backups
+preserve identity generation, sequence options, and sequence progress.
+Resource writes wait for the migration transaction to commit. These records
+represent current desired state, not reconstructed historical transitions.
+There is no later or runtime journal backfill. Plugins use `ctx.events.listLifecycle(companyId, limit?, afterId?)` and
+`ctx.events.acknowledgeLifecycle(companyId, eventId)` with `events.subscribe`.
+The host requires a matching company invocation (or configured-company proactive
+access) and a ready plugin enabled for that company.
+`plugin_lifecycle_acknowledgments` stores progress independently
+for each plugin and event; plugin and event deletion cascade acknowledgments.
+Reads return creation first, then the earliest unacknowledged transition for each resource, up to 100
+resources. Acknowledging a later event is rejected. Reads never consume work, so
+crashes, retries, and restarts cannot lose a hook; concurrent reads can repeat an
+event. There is no global cursor or runtime backfill scan. Consumers must serialize their
+processing and make provider operations idempotent before acknowledging success.
+Retention and provider integration remain separate work.
+
+Lifecycle polls can page past failed resources using the last returned event id as
+`afterId`. Reset `afterId` at the start of every polling sweep: it is a page
+cursor, never a persisted high-water mark. This retries failures and includes
+transactions that commit later with lower ids.
+
## Legacy controller ownership
Legacy run claims atomically record `controller_boot_id`, a database-clock
@@ -491,3 +599,21 @@ reservation cannot silently disappear. Failed cleanup or an ambiguous storage
write requires operator reconciliation before an unattached reservation is
removed. The table stores no response bodies. See `doc/runner-api-tools.md` for
limits and the operator override.
+
+## Internal agent commentary
+
+`agent_commentary` stores company-scoped, attributed complaints and suggestions
+as free-form text in the instance database. Legacy agents use the default
+`complain` and `suggestion-box` runtime skills; native runs use dedicated tools
+in standard, ask, and planning modes. Submission never changes task disposition
+or routes feedback externally. See [Agent commentary](agent-commentary.md) for
+authentication, replay, document-sized limits, inspection, and deletion semantics.
+
+## Agent identity keys and backups
+
+`agent_identity_keys` stores one encrypted Ed25519 identity per agent. Its migration
+creates schema only: existing agents provision on their next managed run. Public
+reads and server startup do not provision them. Normal backups preserve identity
+rows and need the matching secrets master key for recovery. Both development seed
+modes omit identity rows, including with live-work preservation, so copied agents
+get fresh identities. See [Agent cryptographic identity](AGENT-IDENTITY.md).
diff --git a/doc/DEVELOPING.md b/doc/DEVELOPING.md
index c88890e98a9..fede68c1399 100644
--- a/doc/DEVELOPING.md
+++ b/doc/DEVELOPING.md
@@ -103,6 +103,12 @@ pnpm build-storybook
These run the `@paperclipai/ui` Storybook on port `6006` and build the static output to `ui/storybook-static/`.
+**Composer → New task** includes agent/user/project/task mentions, skill and
+routine slash commands, and populated rich chips on desktop and mobile. Agent
+mentions use the same avatars in suggestions, inserted chips, and the mocked
+creation receipt. The creation stories preserve the original Markdown references;
+they do not create real tasks or run agents.
+
Use **Components → Agent setup prompt** to review the shared setup handoff:
hover/focus logo motion, one-click copying with a prompt preview, animated
confirmation, and manual-copy recovery. Opening the preview copies immediately;
@@ -140,11 +146,61 @@ choices, item verdicts, suggested tasks, tool reviews, runtime questions, and ph
the bottom navigation. The normal message composer remains usable below the
pending card.
+Use **Chat & Comments → Task Chat Unanswered Questions → Test Drive** to
+try a regular task question: dismiss it, reload, reopen its compact feed entry,
+and submit the preserved draft. The composer has no question pending badge.
+The demo uses real thread/form components with fixture response callbacks.
+The Agent Chat stories share the same component fixture.
+
+Use **Composer → New task** to review task creation through the production
+`TaskChatComposer`. The editor, file menu, work modes, assignee/model picker,
+and send control are shared with task chat. An inset bar above the composer uses
+the queued-message container and holds Project on the left. Its searchable picker
+shows project colors. Worktrees sits beside Project when the selected project has
+isolation enabled. Choose a new worktree, reuse an eligible worktree from that
+project, or keep the shared project workspace. Reuse carries the worktree's source
+checkout, including a non-primary checkout. Changing projects clears the
+previous worktree choice. Switching from reuse to a new worktree or the project
+workspace restores the project default checkout. Task creation uses the selected company and has
+no separate heading or settings control.
+Fresh tasks start with an empty request and the last task assignee chosen in that
+company, including a human. If that assignee is unavailable, the CEO is the
+default, or the first eligible agent when the company has no CEO. Explicit launch
+assignees and saved drafts keep their selection. Selecting an assignee never
+inserts a mention. Clicking the assignee opens its searchable list directly;
+model and effort have a separate trigger and appear only for agents whose
+harness supports those settings.
+Fresh tasks also keep the company's last project (including No project); launch
+context and saved drafts take precedence. New projects receive a random palette
+color and become the remembered project. The shared composer remembers the last
+effort within the company and applies it only when the selected model supports
+that level. Explicit task overrides and drafts take precedence. Default model
+labels show the configured or known adapter model, otherwise simply Default.
+Claude defaults supplied by the server's host environment remain Default unless
+the agent explicitly configures the model. Project edits on an existing task
+become the remembered project only after the task update succeeds.
+Clicking or tapping outside either selector dismisses it and preserves the task
+draft and selections. Mobile sheets return focus to the trigger without reopening.
+Stories cover empty and prefilled drafts, remembered, human, and unassigned
+selections, the direct assignee picker, sub-tasks, planning, files, saving,
+retryable failures, creation, light theme, and mobile, plus worktree reuse,
+loading, empty, error, and isolation-disabled states. Story submissions use local
+fixtures and never start an agent.
+
Use **Composer → Model and effort picker** to review harness-specific model
choices. Codex uses the curated adapter catalog unless the instance declares
`PAPERCLIP_ADAPTER_MODELS`; general OpenAI API models are not Codex choices.
The Paperclip Runner Codex profile shows the same known model effort levels.
Its selected effort is saved with the run and sent to Codex for each turn.
+When Codex reports that a selected model is not supported with a ChatGPT account,
+the task shows **Model unavailable**, the provider's account restriction, and
+guidance to choose a supported model or clear the task's model override before
+retrying. The run retains this reason even when the runner saves a generic
+failure result.
+When a committed Codex terminal reports `serverOverloaded`, the task displays
+the model capacity error and **Model at capacity** on its scheduled retry card.
+Automatic retries wait one and two minutes, then stop. Use
+**Tasks → Model capacity retry** in Storybook to inspect the waiting state.
Claude Code uses model-specific effort levels; Haiku has no effort slider.
Grok uses its adapter's reasoning levels, including for its default model.
Kimi shows effort only when its agent uses the CLI engine, including with its
@@ -228,10 +284,14 @@ are not automatically deleted and will accumulate until an operator prunes them.
Publishing requires both the original actor and the current rerunner to be
individual GitHub accounts named in `.github/CODEOWNERS` on the current default
-branch. Comments, teams and email entries do not grant access. Authorization runs
-before the build and again before deployment, including deployment-only reruns.
+branch. Individual accounts from every ownership rule are included, regardless
+of which paths they own. Comments, teams and email entries do not grant access.
+Authorization runs before the build and again before deployment, including
+deployment-only reruns.
GitHub also requires a CODEOWNER environment approval, so editing authorization
code on a branch cannot grant AWS access without an authorized reviewer.
+CODEOWNERS membership does not automatically add an account to the environment's
+required reviewers; a configured reviewer must approve each deployment.
The build downloads the public source archive with no GitHub token permissions,
AWS credentials or repository secrets. Dependency caching and install lifecycle
@@ -409,6 +469,11 @@ npx paperclipai allowed-hostname dotta-macbook-pro
## Test Commands
+The [feature map](../feature-map/README.md) is an optional reference for user
+entry points, targeted tests, manual verification recipes, and coverage gaps.
+Its page inventory is a source snapshot. The documented journeys have separate
+verification steps and do not run automatically from the map.
+
Use the cheap local default unless you are specifically working on browser flows:
```sh
@@ -1152,6 +1217,11 @@ operator-controlled [runner API tools](runner-api-tools.md) rollout; enabling
Agent Chat does not enable that API surface. Failed-turn retries restore the
selected run's user comments so the agent can answer the original request.
+An unsaved Agent Chat uses an ephemeral `chat:` view-model ID. Task
+browser polling starts after the first send or upload creates a persisted task
+UUID. Saved chats retain the task browser's company and credential access checks.
+Task browser routes reject malformed task IDs with `404` before querying PostgreSQL.
+
A native continuation that requires reconciliation shows **Recovery needed**
with **Inspect run**; inspect the original outcome before resolving its recovery
hold. A generic retry cannot resolve this incident. The runner's
@@ -1212,6 +1282,29 @@ the updated sandbox image with the matching runner qualification changes.
### Native runner restart recovery
+Project discovery through `list_projects` returns up to 50 compact summaries.
+It uses `GET /api/companies/:companyId/projects?view=summary&limit=50&cursor=...`;
+the cursor is optional. The database reads bounded summary projections. Agent
+and run trust boundaries narrow database candidates before per-project access
+checks. Projects with their own authorization policy remain candidates because
+that policy can contribute scope; every result still passes the full access check.
+Only visible projects determine page boundaries and continuations.
+The default project-list API response remains unchanged.
+Use its `nextCursor` as the next call's `cursor` until it is null; `limit` accepts
+1–50. Descriptions include at most 1,000 characters and an explicit truncation
+flag. Full project records remain available through the authorized project API.
+Workspace configuration is excluded from discovery responses so large projects
+cannot overflow the runner's durable tool-result command limit.
+
+When an accepted result survives a shutdown failure, workspace repair uses a
+new assessment for the repaired workspace state. Its status decision and
+assessment reference commit together. Recovery completes from the saved result
+without another provider turn, clears stale successful-run errors, and retains
+the original error in `recoveredExecutionFailure`. Exact-state session cleanup
+recognizes both the legacy `adapter_failed` and current `provider_transport_failed`
+close-failure labels. Process ownership, pending tool outcomes, and checkpoint
+verification still control whether that session can be reused.
+
Paperclip Runner keeps its heartbeat run, native session, logical runner, and
provider session identities across server restarts. A coordinated hot restart
registers a correlated recovery request before it signals the dev supervisor.
@@ -1309,7 +1402,9 @@ Skill-capable legacy local adapters always select the bundled
runtime inventory. This applies to existing agents without a stored skill
preference and to explicit empty optional-skill selections. The operational
skill supplies the control-plane workflow that those adapters need for
-heartbeats. Other runtime skills remain controlled by
+heartbeats. The `complain` and `suggestion-box` runtime skills are also selected
+automatically alongside it; see [Agent commentary](agent-commentary.md).
+Other runtime skills remain controlled by
`paperclipSkillSync.desiredSkills`. The native `paperclip_runner` does not use
this legacy default because its protocol supplies the control-plane contract.
diff --git a/doc/DOCKER.md b/doc/DOCKER.md
index 7d9bb1ea954..d59ddc102bd 100644
--- a/doc/DOCKER.md
+++ b/doc/DOCKER.md
@@ -212,24 +212,25 @@ The image pre-installs:
- `claude` (Anthropic Claude Code CLI)
- `codex` (OpenAI Codex CLI)
+- `python3` (used to run local subscription sign-in in a pseudo-terminal)
-If you want local adapter runs inside the container, pass API keys when starting the container:
+Start the container, then open **Apps → Connections** to connect a Claude or
+Codex subscription in your browser. You can also enter a provider API key there.
+You do not run a shell command or configure a CLI home.
```sh
docker run --name paperclip \
-p 3100:3100 \
-e HOST=0.0.0.0 \
-e PAPERCLIP_HOME=/paperclip \
- -e OPENAI_API_KEY=... \
- -e ANTHROPIC_API_KEY=... \
-v "$(pwd)/data/docker-paperclip:/paperclip" \
paperclip-local
```
Notes:
-- Without API keys, the app still runs normally.
-- Adapter environment checks in Paperclip will surface missing auth/CLI prerequisites.
+- The image provides the CLI and Python prerequisites for local subscription sign-in.
+- Adapter environment checks in Paperclip surface missing authentication or CLI prerequisites.
## Podman Quadlet (systemd)
diff --git a/doc/PRODUCT.md b/doc/PRODUCT.md
index 15ab6854106..502b1d42dd9 100644
--- a/doc/PRODUCT.md
+++ b/doc/PRODUCT.md
@@ -209,10 +209,26 @@ telemetry. See [Announcements](ANNOUNCEMENTS.md).
### Agent chat discovery
-With Agent Chat enabled, the Chats sidebar always includes the company's
-earliest-created agent, plus personal starred agents and up to four other recent
-conversations. First use has the same compact rows as returning use. The compose
-icon shares a column with stars and appears on hover or keyboard focus (always on
-touch). It opens a company-wide name/role search, independent of sidebar membership.
+With Agent Chat enabled, Chat is the first row of the Work section and opens a
+secondary sidebar beside the primary nav. It lists every agent you can chat
+with: the open conversation first, then your other conversations by recent
+activity, then the rest of the roster alphabetically. Terminated agents and
+agents you have left are omitted unless you have history with them. Search
+filters by name, title, or role; **+** starts or reopens a conversation.
Selecting an agent opens their persistent conversation; it does not reset history
or create a task until the existing first-write flow requires one.
+
+Beside a conversation, the side panel opens on the agent's tasks: one card per
+task the agent created, was assigned, commented on, or acted on, newest first,
+with the task list's filters and a sort control. The agent's artifacts are a
+second card stack available from the panel's **+** menu. Both open in a new tab
+so the conversation stays open.
+
+### Combined Inbox + Task List
+
+An opt-in experimental setting (`enableCombinedInboxTasks`, off by default)
+folds Inbox into Tasks. The Inbox nav row goes away and its unread badge moves
+to Tasks. A Views menu on the task list covers the inbox views (Mine, Unread,
+Blocked, Recent, Everything) and the task-status views (All, Active, Backlog,
+Done). Bare `/issues` opens the last-used view, defaulting to Mine; links that
+carry a task filter open All. Old `/inbox` links redirect to the matching view.
diff --git a/doc/SPEC-implementation.md b/doc/SPEC-implementation.md
index 533a41e49cb..93a81ac6fcc 100644
--- a/doc/SPEC-implementation.md
+++ b/doc/SPEC-implementation.md
@@ -188,6 +188,18 @@ Invariants:
Invariant: plaintext key shown once at creation; only hash stored.
+### Agent cryptographic identity
+
+Each agent also has one Ed25519 identity in `agent_identity_keys`, separate from
+API bearer keys and company secrets. New-agent creation provisions it atomically;
+existing agents provision lazily before their first managed run. The schema-only
+migration and public reads never provision existing agents. Private PKCS#8 PEM
+material uses `local_encrypted`; public SPKI PEM and its SHA-256 key ID are readable
+through `GET /api/agents/:id/identity` and the agent Identity section. Managed
+processes receive the pair through runtime-only environment fields. See
+[Agent cryptographic identity](AGENT-IDENTITY.md) for storage, runtime, and copy
+semantics.
+
## 7.4 `goals`
- `id` uuid pk
@@ -548,7 +560,7 @@ V1 non-terminal liveness rule:
- recovery-action ownership is separate from source-task ownership: automatic repair and board escalation preserve both source assignee fields; reassignment requires an explicit board decision or a policy-defined serious failure
- source-scoped recovery routing is cause-keyed: bounded continuity and disposition repair may retry only the original agent; provider-quota failures create/reuse a scheduled wait-recovery monitor; every other exhausted or unsafe path creates/reuses a board-owned recovery action with `routingPolicy: board_escalation_no_takeover_v1` and no substitute-agent wake
- legacy active agent-owned recovery actions remain readable, resolvable, and API-compatible after upgrade, but reconciliation does not enqueue another takeover wake for them
-- active-run output silence is an informational board UI signal at one hour (`suspicious`) and four hours (`critical`); it does not create or update issues or recovery actions, comment on or block source work, change assignments, or wake an agent
+- active-run output silence is an informational board UI signal at five minutes (`suspicious`) and fifteen minutes (`critical`); it does not create or update issues or recovery actions, comment on or block source work, change assignments, or wake an agent
- board snooze and continue decisions suppress the run signal until their stored re-arm time; a false-positive decision suppresses it permanently for that run; open legacy evaluation issues remain readable and manually resolvable without automatic refresh
Detailed ownership, execution, blocker, active-run watchdog, crash-recovery, and non-terminal liveness semantics are documented in `doc/execution-semantics.md`.
@@ -572,6 +584,18 @@ conversation lifecycles, and protection against replaying superseded requests.
- Board has full read/write across all companies in deployment
- Every board mutation writes to `activity_log`
+Human invitations default to the Operator role. Its default grants allow agent
+creation and configuration, skill editing, environment management, invitations,
+task assignment, pipeline editing, connection and tool management/use, and tool
+and agent-action audit views. Operators do not receive `joins:approve` or
+`users:manage_permissions`. Explicit invitation grants remain authoritative.
+Creating a human invitation also requires any of these two membership powers
+included in its selected role. Operators can invite Operators and Viewers;
+inviting an Admin requires join approval, and inviting an Owner also requires
+member-permission management.
+This preset change adds no database migration; existing role-default seeding
+continues to insert missing grants without replacing custom scopes.
+
## 9.2 Agent Auth
- Bearer API key mapped to one agent and company
@@ -592,7 +616,7 @@ conversation lifecycles, and protection against replaying superseded requests.
| Action | Board | Agent |
|---|---|---|
| Create company | yes | no |
-| Hire/create agent | yes (direct) | request via approval |
+| Hire/create agent | yes (direct) | new standard agents: direct via `canCreateAgents`; low-trust policy or approval gates can restrict |
| Pause/resume agent | yes | pause: no; resume: direct `agents:configure` grant only |
| Create/update task | yes | yes |
| Force reassign task | yes | limited |
@@ -611,6 +635,14 @@ access does not bypass that decision, and `agents:suggest-changes` alone cannot
apply the lifecycle change. Pause, clear-error, terminate, approval, and
key-management routes remain board-only.
+An ordinary standard agent receives a direct `agents:configure` grant on
+creation. Existing agents keep their current permissions; no backfill runs.
+Low-trust and managed built-in agents do not receive this default. See
+[agent permission defaults](agent-permission-defaults.md) for the full inventory.
+Agent-authenticated changes cannot set or restore host-executed process adapter
+configuration, including commands and environment values. Agent-authenticated
+rollbacks cannot restore host-executed workspace commands either.
+
### 9.3.1 Shared default-open issue writes
For standard-trust agents, issue comments, issue field/status updates, child
@@ -1502,6 +1534,13 @@ Required UX behaviors:
- conflict toasts on atomic checkout failure
- no silent background failures; every failed run visible in UI
+Regular task chats and Agent Chat keep unanswered questions as compact,
+reopenable entries at their original position in the feed. Dismissing a question
+or sending a newer message clears its form from the composer without resolving
+the saved question. Questions do not contribute to composer pending counts.
+Dismissal persists locally for the person and task across reloads; reopening
+restores the original form and draft. Approval and permission gates are unchanged.
+
## 15. Operational Requirements
## 15.1 Environment
@@ -1702,12 +1741,18 @@ Confirmed project creation appears as a durable card in the shared task transcri
### User continuation after execution recovery stops
-An authenticated user message or an exact failed-run Retry can start a fresh
+An authenticated user message, a validated undelivered native message queue, or an exact failed-run Retry can start a fresh
native or legacy conversation turn once the prior execution is confirmed stopped. Retain the source history and uncertain
action outcomes; do not replay tool calls or reset the failed incident's automatic
retry budget. Existing pause, approval, budget, ownership, and dependency gates
remain in effect. See `doc/execution-semantics.md` for admission and stop-proof
requirements.
+The task recovery notice offers Retry for eligible failures and verified native
+startup cancellations, with failed attempts explained inline. Preparing native
+turns keep the Steer label. Steer and Interrupt immediately move the submitted
+messages from the composer queue into the conversation while delivery proceeds.
+Provider acknowledgement remains authoritative; failed delivery restores the
+latest queue with an inline error. Neither action produces a toast.
### Managed AI authentication
@@ -1720,6 +1765,13 @@ Legacy agents retain their authentication until validated adoption. See
[AI Connections](connections/AI-CONNECTIONS.md) for company isolation, compatible
methods, lifecycle, runtime enforcement, and migration details.
+Missing personal AI credentials detected before adapter dispatch also produce
+the inline connection card. Every missing binding must belong to the same
+compatible AI provider. The responsible user connects their own account and
+explicitly adopts Connections; another user's onboarding key is never reused.
+Acceptance resumes only the matching configuration-blocked task through durable
+continuation delivery. Unrelated configuration gaps retain operator recovery.
+
The selected AI connection supports an on-demand usage probe through the common
connection service, independent of legacy/native execution. The board usage
endpoint rechecks company membership and the credential's human audience before
@@ -1905,3 +1957,49 @@ See [Public MCP](public-mcp.md) for the implemented instance-side boundary,
configuration, plugin packages and outstanding hosted release gates. The
[delivery plan](plans/2026-09-30-paperclip-public-mcp-and-plugins.md) separates
external agent participation and granted third-party tools into later releases.
+
+The experimental OpenAI Dot Runner provider uses a separate `/mcp/runner`
+agent OAuth resource. It reuses the public gateway's browser/device consent,
+client metadata verification and signed event delivery, but requires one-use
+agent pairing and normal run admission. Personal grants cannot authorize
+Runner operations. See [OpenAI Dot Runner](openai-dot-runner.md) for the
+self-hosted release boundary and remaining account qualification.
+
+### Experimental AI connection routing
+
+Opt-in plugin routers may represent a pool as an AI runtime binding. Core keeps
+company and credential authorization, atomically records task/agent affinity and
+a pool cursor, and persists concrete native recovery evidence. The full contract
+is in [AI-CONNECTION-ROUTERS.md](connections/AI-CONNECTION-ROUTERS.md). Disabled
+routing cannot allocate new tasks; already admitted native runs remain recoverable.
+
+### Connection instructions
+
+Connections can store optional, versioned agent instructions independently of
+provider and transport. Catalog templates control editor visibility; saved
+settings and runtime delivery also support connections without a template.
+The server includes instructions only when the connection and at least one
+action are available to the run's agent and responsible identity. An immutable
+per-turn snapshot participates in session compatibility, so subsequent turns
+remove stale instructions after edits or access revocation. See
+[Connection instructions](connections/CONNECTION-INSTRUCTIONS.md) for contracts,
+UI conventions, custom adapter integration, and initial memory templates.
+
+### Native provider capacity retry
+
+Committed, run-bound Codex `serverOverloaded` terminal failures display the model
+capacity error directly and schedule at most two automatic retries, after one
+and two minutes. Retries share the execution failure budget, retain task history,
+and honor current ownership, review, governance, pause, dependency, budget, and
+cleanup gates. Restart or duplicate finalization must not create another
+successor. Permanent model/auth incompatibility and usage-limit exhaustion retain
+their existing operator recovery requirements.
+
+## Internal agent commentary
+
+`agent_commentary` stores company-scoped, attributed complaints and suggestions
+as free-form text in the instance database. Legacy agents use the default
+`complain` and `suggestion-box` runtime skills; native runs use dedicated tools
+in standard, ask, and planning modes. Submission never changes task disposition
+or routes feedback externally. See [Agent commentary](agent-commentary.md) for
+authentication, replay, document-sized limits, inspection, and deletion semantics.
diff --git a/doc/SPEC.md b/doc/SPEC.md
index 3382f5474b4..b892429d97a 100644
--- a/doc/SPEC.md
+++ b/doc/SPEC.md
@@ -21,6 +21,12 @@ A Company is a first-order object. One Paperclip instance runs multiple Companie
Every Company has a **Board** that governs high-impact decisions. The Board is the human oversight layer.
+Human invitations default to Operator, with company editing, invitations,
+connections, tools, environments, pipelines, and audit views available by
+default. Join approval and member-permission management remain separate grants.
+An inviter must hold these membership grants to invite a role that includes them.
+See [human Operator defaults](SPEC-implementation.md#91-board-auth).
+
**V1: Single human Board.** One human operator.
#### Board Approval Gates (V1)
@@ -37,6 +43,8 @@ outcome. See [the implementation contract](SPEC-implementation.md#124-connection
Model authentication failures also surface a provider-specific Connections card
on the task immediately after failure. Users can reconnect inline and resume;
legacy agents keep their authentication until an explicit, validated adoption.
+Missing personal AI credentials found before a run starts use the same card.
+The responsible user connects their own account inside the task and continues.
See [AI Connections](connections/AI-CONNECTIONS.md).
AI connections also expose an on-demand, credential-scoped usage probe. It
@@ -85,6 +93,15 @@ The Board sets Company-level budgets. The CEO can set budgets for Agents below t
Every employee is an agent. Agents are the workforce.
+### Cryptographic identity
+
+Agents have persistent Ed25519 identities, encrypted in their home instance.
+New agents receive keys during creation; existing agents receive them lazily on
+their next managed run. Agents can read their keys from the managed process
+environment, and authorized readers can view or copy the public key from the
+agent page. This does not grant external authorization or change bearer-token
+access. See [the implementation contract](AGENT-IDENTITY.md).
+
### Agent Identity (Adapter-Level)
Concepts like SOUL.md (identity/mission) and HEARTBEAT.md (loop definition) are **not part of the Paperclip protocol**. They are adapter-specific configurations. For example, an OpenClaw adapter might use SOUL.md and HEARTBEAT.md files. A Claude Code adapter might use CLAUDE.md. A bare Python script might use command-line args.
@@ -299,7 +316,7 @@ should name the rejected action and the specific restriction.
There is no separate messaging or chat system. Tasks are the communication channel. This keeps all context attached to the work it relates to and creates a natural audit trail.
-Experimental Agent Chat presents one persistent task per person and agent as a simplified conversation. Chat has a searchable secondary sidebar with agent avatars; adding an agent starts or reopens their single conversation. It retains the task composer, transcript, tools, attachments, documents, and existing Subtasks panel, with ordinary company visibility. New execution tasks are ordinary project tasks, not children of the conversation. Idle conversations wait for a message without entering execution-task work queues. Agents clarify goals here and create assigned tasks for substantial execution. `/new` resets provider context at an ordered session boundary within the same task while preserving visible history. `enableAgentChat` is disabled by default; the V1 lifecycle and rollout contract is specified in `SPEC-implementation.md`.
+Experimental Agent Chat presents one persistent task per person and agent as a simplified conversation. Chat has a searchable secondary sidebar with agent avatars that lists every eligible agent, conversations first; adding an agent starts or reopens their single conversation. It retains the task composer, transcript, tools, attachments, documents, and existing Subtasks panel, with ordinary company visibility. New execution tasks are ordinary project tasks, not children of the conversation. Idle conversations wait for a message without entering execution-task work queues. Agents clarify goals here and create assigned tasks for substantial execution. `/new` resets provider context at an ordered session boundary within the same task while preserving visible history. `enableAgentChat` is disabled by default; the V1 lifecycle and rollout contract is specified in `SPEC-implementation.md`.
### Question recipients
@@ -698,3 +715,25 @@ See [Public MCP](public-mcp.md) for the implemented instance-side boundary,
configuration, plugin packages and outstanding hosted release gates. The
[delivery plan](plans/2026-09-30-paperclip-public-mcp-and-plugins.md) separates
external agent participation and granted third-party tools into later releases.
+
+The experimental OpenAI Dot Runner provider uses a separate `/mcp/runner`
+agent OAuth resource. It reuses browser/device consent and signed event delivery
+while preserving agent pairing, normal run admission and task authority.
+Personal grants cannot authorize Runner operations. See
+[OpenAI Dot Runner](openai-dot-runner.md) for its supported release boundary.
+
+### Experimental connection routing
+
+A virtual AI connection can rotate new task/agent allocations through an
+authorized pool while preserving session affinity. Admission, credentials and
+durable recovery remain host responsibilities; policy can be supplied by an
+opt-in plugin. See [the experimental contract](connections/AI-CONNECTION-ROUTERS.md).
+
+## Internal agent commentary
+
+`agent_commentary` stores company-scoped, attributed complaints and suggestions
+as free-form text in the instance database. Legacy agents use the default
+`complain` and `suggestion-box` runtime skills; native runs use dedicated tools
+in standard, ask, and planning modes. Submission never changes task disposition
+or routes feedback externally. See [Agent commentary](agent-commentary.md) for
+authentication, replay, document-sized limits, inspection, and deletion semantics.
diff --git a/doc/adapter-model-audit-2026-10-02.md b/doc/adapter-model-audit-2026-10-02.md
new file mode 100644
index 00000000000..5c86e25bd68
--- /dev/null
+++ b/doc/adapter-model-audit-2026-10-02.md
@@ -0,0 +1,93 @@
+# Adapter model and harness audit: October 2, 2026
+
+This audit follows the [September 22, 2026 audit](adapter-model-audit-2026-09-22.md).
+It covers model selection in the coding-agent adapters and the shared harness
+pins in the runner, the provider pack, and the evaluation image. Catalog
+entries identify models; provider accounts and installed CLIs determine access.
+No agent defaults or saved model selections are migrated.
+
+## Model changes
+
+| Adapter | Changes from the audit |
+| --- | --- |
+| Codex and the Codex runner catalog | Add GPT-6.1 Sol (`gpt-6.1-sol`). Expose efforts through Ultra and Fast mode, as documented. Keep `gpt-5.6-sol` as the default. |
+| Claude on Bedrock | Add Sonnet 5.5 (`us.anthropic.claude-sonnet-5-5`), using the catalog's existing US inference-profile convention. Sonnet 5.5 IDs (direct or Bedrock-qualified) get the documented `xhigh` and `max` efforts and require Claude Code 2.1.284 or later on the CLI lane. |
+| OpenCode | Add `openai/gpt-6.1-sol` and `anthropic/claude-sonnet-5-5` to the static fallback used by remote environments. Both IDs are present in the OpenCode model registry. |
+| Claude Code (direct) | No change in this audit. [#14993](https://github.com/paperclipai/paperclip/pull/14993) (merged October 5, 2026, superseding #14816) adds Sonnet 5.5 (`claude-sonnet-5-5`, Claude Code 2.1.284 or later) and refreshes the Claude runtime. |
+| Grok Build, Gemini CLI, Kimi Code, Cursor | No new verified model IDs. Grok 4.7, Gemini 3.8 Flash, and Kimi K3 remain the newest documented models. |
+
+## Harness changes
+
+| Harness | Before | After |
+| --- | --- | --- |
+| Codex CLI (shared provider pack) | 0.156.0 | 0.160.0 |
+| OpenCode (shared provider pack) | 1.18.32 | 1.18.34 |
+| Grok CLI (`@xai-official/grok`) | 1.0.41 | 1.0.46 |
+| Gemini CLI | 0.60.0 | 0.62.0 |
+| Kimi Code CLI | 2.0.2 | 2.1.1 |
+| Cursor CLI | 2026.09.18-9a7762b | 2026.10.01-e373342 |
+| GitHub CLI | 2.101.0 | 2.102.0 |
+| Claude Agent SDK / Claude Code | 0.3.280 / 2.1.280 | 0.3.286 / 2.1.286 via #14993 (merged); this branch keeps that pin |
+| Hermes | 0.19.0 | 0.19.0 (current) |
+| ACPX, `claude-agent-acp`, `codex-acp` bridges | 0.13.1 / 0.73.0 / 1.6.2 | Unchanged; separately qualified |
+| Pi (`@earendil-works/pi-coding-agent`) | 0.87.1 (fleet image) | Unchanged; Pi 1.0 is qualified upstream in the Pi runner stack |
+
+The remote Codex compatibility window moves to `>=0.149.0 <0.161.0`. The
+minimum stays fixed. See
+[paperclip-runner-compatibility.md](architecture/paperclip-runner-compatibility.md).
+
+## Sources and verification
+
+- [OpenAI's Codex model guide](https://learn.chatgpt.com/docs/models) lists
+ GPT-6.1 Sol (`gpt-6.1-sol`) with reasoning efforts from Light to Ultra and
+ Standard and Fast modes at launch. The bundled Codex 0.160.0 model metadata
+ also contains `gpt-6.1-sol`. The same page records that `gpt-5.4` and
+ `gpt-5.4-mini` retired from Codex with ChatGPT sign-in on August 31, 2026,
+ and that `gpt-5.5` retires from Codex with ChatGPT sign-in on October 14,
+ 2026. Neither retirement applies to the OpenAI API, so the picker keeps
+ those IDs for API-key users; see "Deferred items".
+- [Codex CLI releases](https://github.com/openai/codex/releases) 0.157.0
+ through 0.160.0 add GPT-6 Sol and Luna metadata, app-server pagination, and
+ authoritative provider catalogs. The Linux x64 executable digest comes from
+ the integrity-verified `@openai/codex@0.160.0-linux-x64` archive.
+- [Claude Sonnet 5.5](https://platform.claude.com/docs/en/models/sonnet-5-5/overview)
+ documents the Bedrock ID `anthropic.claude-sonnet-5-5` and the September 28,
+ 2026 release. The [Claude Code changelog](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md)
+ entry for 2.1.284 adds `claude-sonnet-5-5`, so that version is the CLI minimum. [Models overview](https://platform.claude.com/docs/en/about-claude/models/overview)
+ lists `xhigh` and `max` effort support for the 5.5 generation.
+- [OpenCode releases](https://github.com/anomalyco/opencode/releases)
+ 1.18.33 and 1.18.34 contain fixes only. The OpenCode model registry at
+ models.dev lists both added provider-qualified IDs.
+- Grok CLI 1.0.46 is the `latest` tag on npm. [xAI's model list](https://docs.x.ai/docs/models)
+ still ends at Grok 4.7. Gemini CLI 0.62.0 and Kimi Code 2.1.1 are the
+ `latest` tags on npm; [Google's model catalog](https://ai.google.dev/gemini-api/docs/models)
+ and [Kimi's model page](https://www.kimi.com/code/docs/en/kimi-code/models.html)
+ list no newer coding models.
+- Cursor CLI 2026.10.01-e373342 is the version the official installer
+ resolves; the pinned archive digest comes from the versioned tarball, and
+ the extracted binary reports that version. [Cursor's catalog](https://cursor.com/docs/models-and-pricing)
+ shows new Grok 4.7 500k and Kimi K3 rows without exact CLI IDs, so no
+ fallback IDs were added.
+- [GitHub CLI 2.102.0](https://github.com/cli/cli/releases/tag/v2.102.0)
+ contains security fixes for download commands. The pinned digest matches the
+ release `checksums.txt`.
+- [Hermes on PyPI](https://pypi.org/project/hermes-agent/) remains at 0.19.0.
+
+## Deferred items
+
+- `gpt-5.4` and `gpt-5.4-mini` stay in the Codex picker because the OpenAI API
+ still serves them. A later audit can remove them once API retirement is
+ published or operators confirm no API-key agents depend on them. `gpt-5.5`
+ needs the same review after October 14, 2026.
+- The ACP bridges (ACPX 0.19.4, `claude-agent-acp` 0.85.1, `codex-acp` 2.1.1)
+ are newer upstream. They carry reviewed patches and qualified executable
+ digests, so they need a separate qualification campaign rather than a pin
+ bump. ACPX 0.15.1 and 0.17.0 also change message limits and session
+ journal records.
+- Pi 1.0.0 is published, but the runner's Pi profile and the fleet image stay
+ on the qualified 0.84.2 / 0.87.1 pins until the Pi 1.0 runner stack lands.
+- The native Grok runtime (`native:grok` 1.0.13) is bound by a qualified
+ profile digest and is not refreshed by this audit.
+- Claude Mythos 5.1 remains invitation-only with no public selectable ID.
+- Cursor's exact IDs for Grok 4.7 500k, Kimi K3, and GLM 5.3 are not shown
+ in the documentation and the unauthenticated CLI returns no list.
diff --git a/doc/agent-commentary.md b/doc/agent-commentary.md
new file mode 100644
index 00000000000..2fe7ee8cdd3
--- /dev/null
+++ b/doc/agent-commentary.md
@@ -0,0 +1,155 @@
+# Agent complaints and suggestions
+
+Agents submit incidental feedback into the current instance's `agent_commentary`
+table. Complaints preserve a raw reaction; suggestions describe an improvement.
+Both are free-form, internally attributed records, not anonymous feedback.
+
+## Agent entry points
+
+Skill-capable legacy adapters automatically receive `complain` and
+`suggestion-box` alongside the `paperclip` operational skill, including existing
+agents with empty optional-skill selections. The shared helper lives in that
+operational skill at `scripts/submit-agent-commentary.mjs`. It reads the body
+from stdin and uses the existing `PAPERCLIP_API_URL`, `PAPERCLIP_API_KEY`,
+`PAPERCLIP_COMPANY_ID`, and `PAPERCLIP_RUN_ID`. The helper uses the existing
+Node.js runtime with no additional dependencies; custom runtimes can call HTTP
+directly. Sandboxed runs use the callback bridge.
+
+Native runs receive `submit_complaint({body, idempotencyKey})` and
+`submit_suggestion({body, idempotencyKey})` in standard, ask, and planning modes.
+Specialized completion-review runs retain their restricted tool set. Native
+submission uses the bound authority without a shell or API credential.
+Submit before finishing the run.
+
+Instructions closely adapt Warp's
+[complain](https://github.com/warpdotdev/common-skills/blob/main/.agents/skills/complain/SKILL.md)
+and [suggestion-box](https://github.com/warpdotdev/common-skills/blob/main/.agents/skills/suggestion-box/SKILL.md)
+skills, with their MIT notices included. Paperclip changes the transport,
+attribution, suggestion form, and size limit. Agents submit proactively when
+warranted, without routine previews or announcements, then continue working.
+Answer truthfully if a user asks about feedback or submitted content. Operators
+can exclude these legacy skills through the existing runtime skill policy.
+Brevity and at most three suggestions per run are guidance, not server quotas.
+Do not report the same incident through both paths or retry failed submissions.
+
+## HTTP contract
+
+`POST /api/companies/:companyId/agent-commentary` accepts an authenticated agent
+and its active run (`Authorization: Bearer …`, `X-Paperclip-Run-Id: …`):
+
+```json
+{"kind":"suggestion","body":"The tool returned before persistence completed. Wait for the write before returning success.","idempotencyKey":"write-completion-1"}
+```
+
+Only these three fields are accepted. Identity and the optional task reference
+are server-derived. Board callers cannot impersonate agent feedback. Native runs
+use their dedicated tools rather than this legacy HTTP path.
+
+Bodies must contain non-whitespace text and may contain up to 524,288 JavaScript
+string code units, matching ordinary issue documents. No truncation is applied.
+Existing 10 MiB HTTP and callback bridge request limits remain. Keys are nonempty
+and at most 240 characters.
+
+Creation returns HTTP 201 with `{id, kind, createdAt, replayed:false}`. Identical
+replay in the same company/run returns HTTP 200 with the same ID and timestamp
+and `replayed:true`. Conflicting key reuse returns 409. Invalid input returns 400;
+invalid authority returns 401/403; storage failure returns a sanitized 503.
+Authorization precedes replay. The helper accepts an optional second argument
+for a stable key, generating one otherwise. It makes one request with a
+10-second HTTP deadline and exits zero on failure with a content-free diagnostic.
+It never follows redirects with credentials or claims an uncertain write succeeded.
+
+## Storage and inspection
+
+Rows contain company, agent, run, nullable issue, kind, body, retry key, payload
+hash, and timestamp. Known run secrets and credential syntax are redacted before
+storage; instructions remain essential because redaction cannot guarantee
+secrecy. Writes and one content-free activity record commit together. Feedback
+bodies are excluded from HTTP diagnostics and dedicated mutation receipts.
+
+There is no feedback UI, read API, notification, automatic task creation, or
+external forwarding. This is separate from first-party Telemetry, OpenTelemetry
+Observability, and the run log. Ordinary provider transcripts can still contain
+submitted tool arguments; there is no anonymity or ephemeral-storage promise.
+
+Authorized operators inspect the instance database, for example:
+
+```sql
+SELECT id, kind, body, agent_id, run_id, issue_id, created_at
+FROM agent_commentary
+WHERE company_id = ''
+ORDER BY created_at DESC;
+```
+
+The service enforces company/run ownership. Foreign keys clear the task reference
+on task deletion and cascade deletion with its run, agent, or company. Normal
+logical database backups include these rows. No retention scheduler or backfill.
+
+## Verification
+
+Focused coverage lives in `server/src/__tests__/agent-commentary.integration.test.ts`,
+`agent-commentary-helper.test.ts`, `agent-commentary-skills.test.ts`, the shared validator tests, and the HTTP logger
+and sandbox callback bridge suites. These exercise real PostgreSQL and routes,
+atomic audit rollback, replay races, authority changes, deletion, default mounts,
+Unicode, and the exact document-body boundary.
+
+The opt-in live smoke uses existing Codex login credentials, copied to a private
+temporary home, and a disposable instance database. It calls the real legacy
+adapter and production native-session executor. It incurs normal provider usage:
+
+```sh
+node cli/node_modules/tsx/dist/cli.mjs server/scripts/verify-agent-commentary-live.ts
+```
+
+To run the same checks on real Daytona sandboxes, install the standalone
+provider's dependencies, provide its API key and an immutable image reference,
+and specify a Linux amd64 runner built from this checkout:
+
+```sh
+pnpm --dir packages/plugins/sandbox-providers/daytona install --frozen-lockfile
+PAPERCLIP_LIVE_ENVIRONMENT=daytona \
+PAPERCLIP_LIVE_DAYTONA_ENV_FILE=/path/to/private.env \
+PAPERCLIP_LIVE_LINUX_RUNNER=/path/to/linux-amd64/paperclip-runnerd \
+PAPERCLIP_LIVE_EVIDENCE_PATH=/tmp/commentary-evidence.json \
+node cli/node_modules/tsx/dist/cli.mjs server/scripts/verify-agent-commentary-live.ts
+```
+
+The private env file needs only `DAYTONA_API_KEY` and
+`PAPERCLIP_E2E_DAYTONA_IMAGE` (`...@sha256:...`). Alternatively, export those
+variables directly. A positional `legacy` or `native` argument selects one path.
+For a current Linux runner, add an export stage to a temporary copy of the root
+Dockerfile and build it with `--platform linux/amd64 --target commentary-runner-export
+--output type=local,dest=/tmp/commentary-runner-linux`:
+
+```dockerfile
+FROM scratch AS commentary-runner-export
+COPY --from=runner-build /app/packages/paperclip-runner/runner/target/release/paperclip-runnerd /paperclip-runnerd
+```
+
+The smoke calls the production Daytona provider hooks for creation, execution,
+file transfer, private ingress, and confirmed deletion. Legacy feedback crosses
+the sandbox queue callback bridge. Native feedback crosses the runner's private
+WebSocket and live tool authority. The current Linux runner is staged and
+verified independently of the base image. Fixture setup creates authority;
+the real agent submits all feedback. This is a focused feedback transport smoke,
+not a full Runner E2E catalog qualification or browser onboarding test.
+
+Both paths passed locally and on Daytona on 2026-10-06. Each persisted one complaint and one suggestion
+with company, agent, run, and task attribution; each then wrote the continuation
+marker. Both exited zero, left task status unchanged, created no task comments,
+and recorded two content-free activity entries. The script emits the attributed
+row IDs and timestamps as evidence, optionally saves a JSON report, and deletes
+its temporary data, credentials, and remote sandboxes. Remote reports are emitted
+only after confirmed sandbox deletion.
+
+The Daytona verification used base image
+`ghcr.io/paperclipai/paperclip-daytona-runner@sha256:b81a86d5242088f9d832666a411f09da7438d92e99f9962ccf88ebe439cd3b32`
+and the Linux runner built from `abf47b5953d14aa7a8dbf2941460b5df8a4d66c3`
+(binary SHA-256 `c794141152ae2e2986da0df14b01a54e4448949e06ec4031c83bad8a9fff8bac`).
+
+| Environment | Runner | Complaint row | Suggestion row | Submitted at (UTC) |
+| --- | --- | --- | --- | --- |
+| Local | Legacy Codex | `59413a00-1de2-4bb1-bcc6-9c4b54c64aa6` | `3db2364d-3e15-4f47-846f-875d3902999d` | 20:35:10 |
+| Local | Native Codex | `5da22b5f-41df-4de5-8ba0-d9345ab01267` | `2d5abe17-dd41-403c-a5ee-4729f2d58921` | 20:35:26–20:35:27 |
+| Daytona | Legacy Codex | `27c9d0aa-8477-409f-9da0-e8ffa48dee50` | `209681c9-d1e9-4ce1-999e-48fa07692389` | 20:33:07–20:33:09 |
+| Daytona | Native Codex | `6eb001bb-4bcf-43f7-8717-f662f53dc7c3` | `77c383d8-a997-49e5-a33e-25c70e15c0b2` | 20:31:54 |
diff --git a/doc/agent-files.md b/doc/agent-files.md
index 2cfd67c668a..a4154551f19 100644
--- a/doc/agent-files.md
+++ b/doc/agent-files.md
@@ -180,6 +180,12 @@ unavailable local copy can still contain uncollected edits; this cleanup path
preserves those bytes even if local stop proof arrives later.
Deferred cleanup retries after a
delay so one blocked copy does not prevent other copies from being cleaned.
+If releasing a run's instruction copy fails, the run records a cleanup warning
+and leaves the durable copy for the recovery sweep. Cleanup does not replace the
+provider's result, discard usage accounting, or prevent environment lease release.
+It does not claim that unsaved agent-file changes were saved; collection failures
+keep their separate failed-save receipts. A run attempts failed cleanup only once
+before handing it to recovery, rather than repeating the lock wait in teardown.
Re-preparing an existing run uses the same lock as cleanup and rechecks its
receipt under that lock. Preparing a new run keeps its separate admission path.
Missing stop proof or lost remote bytes produce a visible diagnostic, never a
diff --git a/doc/agent-permission-defaults.md b/doc/agent-permission-defaults.md
new file mode 100644
index 00000000000..49ee70192f1
--- /dev/null
+++ b/doc/agent-permission-defaults.md
@@ -0,0 +1,31 @@
+# Agent permission defaults
+
+This document describes the server defaults for an ordinary, standard trust agent. An agent must belong to the same company and be active where the action requires active membership. A responsible user's authority, project or run trust policy, scope rules, and approval gates can narrow these defaults.
+
+## Granted by default
+
+| Capability | Source and limit |
+| --- | --- |
+| Agent configuration and suggestions | New standard agents receive direct, company-scoped `agents:configure` and `agents:suggest-changes` grants. Protected-change and responsible-user checks still apply. |
+| Skill changes | New standard agents receive direct `skills:create` and `skills:suggest-changes` grants. |
+| Tool access and management | New standard agents receive `tools:manage_connections`, `tools:manage_profiles`, `tools:view_audit`, `tools:use`, and `tools:manage_runtime` grants. Tool, connection, profile, and runtime policy checks still apply. |
+| Audit and inbox | New standard agents receive `audit:view_agent_actions` and `inbox:manage` grants. The default inbox grant is limited to the responsible-user path and still follows that user's inbox policy. Cross-user management requires a separately configured grant or the target user's saved consent policy. |
+| Task assignment and checkout control | New standard agents receive `tasks:assign`, `tasks:assign_scope`, and `tasks:manage_active_checkouts` grants, subject to company and route checks. The `tasks:assign_scope` grant covers the new agent's own reporting subtree; an explicit invitation scope is preserved. |
+| Agent creation | New standard agents have `canCreateAgents: true`. This is a legacy authorization path for `agents:create`, not an `agents:create` grant row. Stored legacy records without the flag stay closed. |
+| Skill creation setting | `canCreateSkills: true` is the normalized setting. Protected skill configuration changes still require a direct `skills:create` grant or a consented `skills:suggest-changes` grant. |
+| Same-company visibility and work | Standard agents can read same-company agents, projects, issues, and company scope; read and manage decision queues; read runtime and secret metadata where the route allows it; comment or mutate their own or unassigned issues; and assign tasks under the assignment policy. The route and resource checks still apply. |
+| Own configuration and wake | An agent can read its own configuration, update unprotected parts of it, and wake itself. Protected changes still require the relevant grant. |
+
+## Not granted by default
+
+These permission keys have no blanket grant for new standard agents: `agents:create` (the flag above is separate), `environments:manage`, `tools:admin`, `users:invite`, `users:manage_permissions`, `pipelines:write`, and `joins:approve`. Existing agents keep their current permissions. The defaults above apply when a new standard agent is created or a pending new hire is activated. Some actions have separate bounded paths; the absence of a grant row does not describe every route decision.
+
+The new direct grants do not grant company administration, user permission management, blanket tool administration, or cross-company access. The responsible user's permissions, route checks, and the normal approval gates still apply.
+
+Agent-authenticated callers cannot set process adapter configuration or switch an existing agent onto the process adapter. For local adapters, they cannot change host command, argument, working-directory, arbitrary environment, or filesystem sandbox command settings. Provider credential secret references on known environment keys remain allowed so agents can hire peers with their own credentials. When a caller uses an AI connection pool, a new peer can use a plain provider authentication override on the small allowlist of supported keys. Arbitrary environment keys remain blocked. The same limits apply to creation, hiring, adapter switches, and configuration rollback. They also cannot restore host-executed workspace commands through a configuration revision. This keeps host-executed commands under board control while standard agents configure other supported agent settings.
+
+## Exceptions and rollout
+
+The new direct grants are withheld from low trust agents and managed built-in agents. Low trust run or project policies can also deny privileged actions even if an agent has a grant. There is no permission backfill or upgrade migration for existing agents. A standard pending new hire receives the new default set when approved and activated. Invitation approval retains the set when it replaces a new agent's grants and preserves any explicitly scoped default grant. Existing scoped grants stay unchanged. A grant removed by an operator stays removed; ordinary updates and startup do not reapply it.
+
+The standard agent configuration default supports the agent setup in the linked runner task. Enabling a warm runtime can still depend on the target agent's adapter and runtime configuration, provider availability, and any responsible-user or approval checks.
diff --git a/doc/architecture/paperclip-runner-compatibility.md b/doc/architecture/paperclip-runner-compatibility.md
index effabc1eba4..d148a7dc754 100644
--- a/doc/architecture/paperclip-runner-compatibility.md
+++ b/doc/architecture/paperclip-runner-compatibility.md
@@ -46,15 +46,15 @@ would hide the runtime that executed the task.
## Remote Codex version window
-Remote native Codex runs accept stable CLI versions **`>=0.149.0 <0.157.0`**.
-The install pin remains `0.156.0`. A sandbox image can therefore use an older
+Remote native Codex runs accept stable CLI versions **`>=0.149.0 <0.161.0`**.
+The install pin is `0.160.0`. A sandbox image can therefore use an older
compatible Codex without failing startup or installing another copy.
The minimum is fixed at **`0.149.0`** until maintainers deliberately change it.
It is not a rolling one-month support window. The official
[`@openai/codex` publication history](https://registry.npmjs.org/@openai/codex)
-records `0.149.0` on 2026-08-20, `0.153.4` on 2026-09-04, and `0.156.0` on
-2026-09-22. See also the [Codex changelog](https://learn.chatgpt.com/docs/changelog).
+records `0.149.0` on 2026-08-20, `0.153.4` on 2026-09-04, `0.156.0` on
+2026-09-22, and `0.160.0` on 2026-10-01. See also the [Codex changelog](https://learn.chatgpt.com/docs/changelog).
This is an explicit compatibility window, not a claim that every Codex minor
release follows a backward-compatible protocol.
@@ -65,7 +65,7 @@ release follows a backward-compatible protocol.
- The same check applies to discovered, explicitly staged, and npm-installed
remote Codex executables, including the final executable after linking.
- For an incompatible image, the existing
- `PAPERCLIP_RUNNER_REMOTE_CODEX_NPM_SPEC=@openai/codex@0.156.0` configuration
+ `PAPERCLIP_RUNNER_REMOTE_CODEX_NPM_SPEC=@openai/codex@0.160.0` configuration
allows installation of the pinned runtime. Without that configuration,
startup reports the supported range and the remediation.
- Runner binary contracts, required runner capabilities, artifact digests,
@@ -85,6 +85,12 @@ app-server binaries with a local deterministic Responses API fixture. Both
passed initialization, thread creation with a dynamic tool, a tool-call/result
round trip, turn completion, and thread resume. This verifies the tested
protocol path; it is not a live model, Linux sandbox, or exhaustive feature test.
+The 2026-10-02 refresh moved the install pin and the upper bound to `0.160.0`
+after verifying the integrity-checked Linux x64 `0.160.0` executable digest and
+the installed ACP package contract. Codex `0.157.0` through `0.160.0` add the
+GPT-6.1 Sol catalog entry and app-server pagination without a documented
+app-server protocol break; the Linux CI qualification workflow covers the real
+startup and session-resume probes for the new pin.
Version-boundary and remote artifact-preparation regressions are covered by
`codex-runtime-compatibility.test.ts` and `native-session-executor.test.ts`.
diff --git a/doc/architecture/paperclip-runner-daytona-networking.md b/doc/architecture/paperclip-runner-daytona-networking.md
index 769206bff82..8ab0f2a3dc2 100644
--- a/doc/architecture/paperclip-runner-daytona-networking.md
+++ b/doc/architecture/paperclip-runner-daytona-networking.md
@@ -21,7 +21,7 @@ The PRP identity binds company, issue, agent, run, environment lease, runner ins
- Allow the sandbox outbound access only to destinations explicitly required by the provider runtime.
- Use Daytona's `wss://` preview URL with normal certificate and hostname validation. The preview token is sent only as the `X-Daytona-Preview-Token` header by Paperclip.
- Runnerd rejects public plaintext `ws://` destinations. Public dial targets require `wss://` with hostname validation and either the platform trust store or an explicitly staged private CA bundle.
-- Listener mode binds only `0.0.0.0:43127`, accepts only the run-specific `/api/runner/v1/connect/:runId` path, and rejects WebSocket extension negotiation. PRP authentication and application-layer secure frames remain mandatory above the preview-proxy hop.
+- Listener mode binds only `0.0.0.0`. The optional `--listen-port` selects a port in `1..=65535` and defaults to `43127`. The listener accepts only the run-specific `/api/runner/v1/connect/:runId` path and rejects WebSocket extension negotiation. PRP authentication and application-layer secure frames remain mandatory above the preview-proxy hop.
- Do not put the bootstrap ticket in argv, files, provider environment, logs, or model context. Inject it into runnerd's initial environment/secret channel; runnerd already removes it from its environment immediately.
- Runnerd is the only process allowed to reach PRP. The provider communicates with runnerd over inherited pipes.
diff --git a/doc/connections/AI-CONNECTION-ROUTERS.md b/doc/connections/AI-CONNECTION-ROUTERS.md
new file mode 100644
index 00000000000..06f092c556f
--- /dev/null
+++ b/doc/connections/AI-CONNECTION-ROUTERS.md
@@ -0,0 +1,133 @@
+# Experimental AI connection routers
+
+AI routers are virtual, company-scoped connections owned by a capability-gated
+plugin (`ai.connections.route`). The instance flag `enableAiConnectionRouters`
+defaults to false. Pools also default to disabled. The host must implement this
+contract; the plugin's minimum version alone does not establish compatibility.
+Routing has no visible enable control in Experimental settings on either
+self-hosted or Cloud instances, even after an operator enables it. Self-hosted
+operators can set `enableAiConnectionRouters` through the instance-admin
+`PATCH /api/instance/settings/experimental` API. Cloud operators use the existing
+fleet or per-stack managed feature configuration. Installing a plugin does not
+enable routing; enabling routing does not enable individual pools.
+
+The host authorizes members using the ordinary company, user, sharing, install,
+health and harness checks. Saving a binding or changing its harness requires
+at least one usable member for that agent. New-agent creation installs only
+members authorized by the ordinary personal-owner or shared-install policy,
+in the same transaction as the agent. Pool membership cannot install a
+restricted shared connection. It sends authorized metadata and sanitized usage
+observations to `onRouteAiConnection`. The plugin proposes an opaque member ID;
+it cannot receive credentials or expand authorization. Pure round robin does
+not probe usage. Usage-aware selection has a shared 15-second probe budget,
+60-second freshness cache and ordinary grant/secret freshness invalidation.
+Concurrent starts share an in-flight probe for the same grant and credential
+freshness. Each caller retains its selection deadline.
+
+One cursor spans all agents in a pool. An allocation transaction locks the
+cursor, checks config and cursor revisions, rechecks authorization, and writes
+the task pin and cursor advance together. Pins use company, pool, agent and the
+existing task key (including `__heartbeat__`). Wakes without a task key retain
+the original run ID as an affinity key in retry context. Conflicts retry at most
+20 times; contention beyond that returns an actionable conflict.
+
+Pins snapshot the concrete binding and member profile. Removing or editing a
+member affects future allocations. Composer changes can change a supported
+model or effort, with a note on fallback, but never the account or harness.
+Session reset and compaction retain the pin. Revocation requires operator repair.
+Authentication repair uses the failed run’s durable concrete allocation and
+current member permissions; reconnect-and-continue preserves the agent’s pool
+binding. Changing the agent’s pool invalidates the old repair card.
+A pre-existing managed session can adopt its saved account when it is an
+eligible member; otherwise the operator must explicitly reset the session.
+
+Credential `ai_session_epoch` changes on reconnect or manual rotation. Only
+verified runtime refresh write-back preserves it. Session fingerprints use the
+secret ID and epoch while authentication failure attribution still uses the
+token generation. A reconnect that replaces an indexed legacy secret changes
+the session identity even when both secret epochs are zero.
+Adopting a valid account preserves a session only when the complete effective
+configuration matches a prior fingerprint. Core can bridge binding-only agent
+revisions (up to 20) and unchanged legacy token identities at epoch zero. Changes
+to other settings, explicit resets, and credential replacement retain their
+existing reset behavior; no fingerprint category is exempted.
+Native recovery retains concrete routing evidence and can finish after the
+router flag or plugin is disabled or uninstalled; it revalidates underlying
+account access and never makes a new allocation.
+
+The private Cloud plugin owns round-robin and quota policy. Its manifest declares
+`aiConnectionRouter: { name, description }` alongside `ai.connections.route`.
+Core adds that connector to the regular catalog and hosts its setup and account
+management using authenticated, company-scoped pool APIs. No separate plugin
+page or sidebar entry is needed. New allocations over
+the chosen threshold wait; known exhaustion defers pinned turns. The deferred
+run schedules `ai_connection_pool_wait` without spending the failure retry
+budget, and the UI labels that retry as **Pool exhausted**.
+
+Operators choose **Connectors → AI connection pool → Add connection pool**,
+select existing accounts, arrange their order, and create a paused connection.
+The normal account page supports rename, member changes, enabling, and removal.
+**Used by** lists the company’s non-terminated agents configured to use the pool,
+with their avatars and links to their profiles. Paused agents remain listed.
+Optional usage and runtime defaults live under **Advanced**. Creating another
+account opens the normal catalog in a new tab so the pool draft stays intact.
+The catalog marks experimental-disabled or unavailable plugins as unavailable.
+
+Deletion uses
+`DELETE /api/companies/:companyId/ai-connection-pools/:poolId` with the current
+`expectedRevision`. Core disables and archives the virtual connection, retaining
+its task pins, cursor and run records. It rejects stale edits and new allocations;
+already admitted runs keep their concrete recovery evidence. Cleanup remains
+available when experimental routing or the plugin is disabled. The catalog captures the reviewed pool revision before showing its removal
+confirmation and uses the pool endpoint. Ordinary connection update and removal
+endpoints reject pools so they cannot bypass configuration revisions. Non-managers
+see the permission requirement without making a denied management request.
+
+Configuration and committed selection are recorded in activity records. Runs
+record the selected member/profile and override notes in the local run log and
+recovery context. These records stay in the instance database.
+
+Tests: `cd server && pnpm exec vitest run src/__tests__/ai-connection-router.test.ts`
+plus the existing AI connection, retry accounting, run-dispatch and UI suites.
+
+## UI review in Storybook
+
+Run `pnpm --filter @paperclipai/ui storybook` from Core, then open
+**AI Connections / Connection pools**. The 16 stories use production components
+for pool selection, legacy-session adoption, unavailable/read-only selections,
+mixed-provider composer models and effort, mobile composer settings, usage waits,
+run selections and override notes, and scheduled retries.
+`AllCoreSurfaces` provides an overview; individual stories expose the expanded
+menus and adoption dialog. Run `pnpm --filter @paperclipai/ui build-storybook`
+to build the preview.
+
+Pool configuration stories belong to the private Cloud plugin's own Storybook
+in `extensions/plugin-connection-pool/storybook/`. Both previews use fictional
+accounts; they do not call live providers or mutate a Paperclip instance.
+Core also owns **Connectors / Pool host** stories for the generic native
+extension. The overview links to Cloud's **In Connectors** preview on port 6010;
+its stories mount these same production routes, header, sidebar and tokens.
+**Full Setup And Management** exercises the complete catalog-to-pool journey.
+Both previews include **Operator Setup Required** for a manually disabled host.
+
+## Full-app browser acceptance
+
+Install the compatible plugin into an isolated, loopback `local_trusted` instance,
+enable the experimental flag, and use a company named for an E2E or test drive
+with two saved, authorized AI accounts. Run:
+
+```sh
+PAPERCLIP_CONNECTION_POOL_E2E=1 \
+AI_CONNECTIONS_TEST_URL=http://127.0.0.1:3100 \
+AI_CONNECTIONS_TEST_COMPANY_ID= \
+pnpm exec playwright test --config tests/ai-connections-app/playwright.config.ts connection-pools.spec.ts
+```
+
+These opt-in tests exercise the shipped app, installed plugin and database without
+mocking browser routes or pool APIs. They cover catalog navigation, setup, ordering,
+paused defaults, rename, member changes, refresh persistence, stale edits and
+removal. They verify that an operator-enabled host still offers no Experimental
+control for routing. With a test agent already bound to a saved pool, they also verify
+the **Used by** list, avatars and profile links. Cleanup archives only the test's own pool and verifies that existing
+accounts and pools remain intact. This suite does not execute agents or probe
+live usage; provider and restart acceptance remain separate gated test drives.
diff --git a/doc/connections/AI-CONNECTIONS.md b/doc/connections/AI-CONNECTIONS.md
index d31ce5fea97..2e74412af1b 100644
--- a/doc/connections/AI-CONNECTIONS.md
+++ b/doc/connections/AI-CONNECTIONS.md
@@ -10,6 +10,11 @@ homes. Managed default/shared accounts are additional choices in that same
selector. Selecting “Sign in to another account” survives background refreshes;
Claude authorization paste keeps upstream's immediate Connecting feedback.
+New-agent Connect offers three persistent tiles: the provider's subscription,
+the provider's API key, and Advanced. All three stay visible while the selected
+mode's form is shown below. Advanced opens the existing compatible-connection
+picker and provider setup. Execution environment selection lives in Configure.
+
Storybook's simulated controllers and page annotations do not run in the app.
## Compatibility and selection
@@ -20,16 +25,17 @@ The shared `AI_CONNECTION_CAPABILITIES` contract defines these combinations:
| --- | --- | --- |
| Claude / Anthropic | Claude subscription token or Anthropic API key | Claude |
| OpenAI | ChatGPT/Codex subscription or OpenAI API key | Codex |
-| OpenRouter | API key | OpenCode, with an `openrouter/` model |
+| OpenRouter (legacy, no routing metadata) | API key | OpenCode, with an `openrouter/` model |
+| Google | API key | Gemini CLI |
| Grok / xAI | Grok subscription or xAI API key | Grok |
Native runner supports the corresponding existing Codex, OpenCode, and Claude
ACP profiles. Connections creation and reconnect mount `AgentProviderConnection`,
the same provider tiles, method controls, API entry, and `AdapterLoginPanel` used
by agent setup. Supported sandbox environments use onboarding's existing browser
-sign-in controllers. Self-hosted installations use the shared terminal sign-in
-instructions described below and require no sandbox. Environment selection does
-not change agent execution settings.
+sign-in controllers. Self-hosted Claude and Codex installations use the same
+browser sign-in presentation with a local login runner and require no sandbox.
+Environment selection does not change agent execution settings.
API keys are validated against fixed provider endpoints; redirects
and caller-supplied validation URLs are rejected.
@@ -38,9 +44,9 @@ and caller-supplied validation URLs are rejected.
- `responsible_user`: resolve the run's responsible user's personal provider default, using that account's subscription or API key. The `method` hint does not restrict the responsible user's account.
- `shared`: use the named `connectionId` and `grantId`, with audience and agent
access checks.
-- `delegated`: retained only to read legacy bindings. It cannot bypass human
- access; a personal credential remains available only for its owner's tasks.
- New configuration offers personal defaults or shared accounts.
+- `delegated`: an explicit personal account selection (the wire name is retained
+ for compatibility). It cannot bypass human access; a personal credential
+ remains available only for its owner’s tasks.
“Which humans can use this credential?” is the sole permission for whose work
can use the account. “Just me” means the personal owner; shared accounts allow
@@ -48,7 +54,8 @@ selected company members or every company member. The separate agent-access
setting determines which agents can use it. There is no additional AI agent
authorization, and old delegation records do not override the human audience.
-A connection choice never changes the harness, model, or provider routing.
+A connection choice never changes the harness or model. For a routed connection,
+the selected connection owns its provider routing.
Changing those separately may make a binding incompatible; saving then requires
a compatible choice. Agent configuration cannot grant access to another account.
@@ -230,6 +237,17 @@ repairs the connection. Unsupported providers and failures that could not create
a card retain their existing recovery path. Tool permission errors and provider quota failures do not
request model authentication.
+Pre-dispatch `configuration_incomplete` failures also show this card when every
+missing binding is a personal `user_secret_ref` for the same compatible AI
+provider. This includes a teammate who has no value for an onboarding
+`ANTHROPIC_API_KEY` definition. The card asks that person to connect their own
+account. It does not use another teammate's secret. Mixed gaps, company secrets,
+and unrelated tool credentials keep the existing operator recovery path.
+After explicit, validated adoption, the durable delivery reopens only the
+blocked task whose latest failure and active configuration recovery still match
+the card. A newer failure, reassignment, manual hold, or restricted external chat
+does not resume through an old card.
+
An attributed managed credential is marked as needing reauthorization only if
its stored generation still matches the failed run. Late failures cannot
invalidate a refreshed or reconnected credential. Repair preserves the selected
@@ -374,19 +392,16 @@ the server preserves the managed binding and will not restore legacy fallback.
Local installations do not need a sandbox to connect a subscription. Connections,
onboarding, and agent setup share `LocalProviderLoginInstructions` and
-`useLocalAiLogin`. In local-trusted mode, Claude checks the operator’s existing
-Claude Code login. Authenticated self-hosted users instead get a separate
-`CLAUDE_CONFIG_DIR` for `claude auth login`; checking and saving only read that
-attempt’s credential files, never the server operator’s account or Keychain.
-
-Codex and Grok start a separate terminal sign-in for each connection or reconnect.
-The shared component shows a server-generated command with a fresh `CODEX_HOME`
-or `GROK_HOME`. Codex uses file credential storage in that home and `login --device-auth`, so
-signing in from another computer does not depend on a localhost callback. The home is never
-seeded with the operator's existing login: copying a rotating refresh token would
+`useLocalAiLogin`. Claude and Codex start a local provider process behind the
+browser sign-in card. Claude accepts the authorization code in that card; Codex
+displays its device code there. The user does not run a shell command. Each
+local runner requires Python 3 for its pseudo-terminal (included in the Docker
+image) and the corresponding provider CLI on the Paperclip host. Each
+attempt retains a private credential home. The home is never seeded with the
+operator's existing login: copying a rotating refresh token would
allow managed runs to invalidate credentials still used by legacy agents or the
-operator's terminal. The user completes browser sign-in from that command, then
-clicks Connect. This does not require a sandbox or change the host login.
+operator's terminal. The user completes browser sign-in, then clicks Connect.
+Grok retains its terminal sign-in flow until it has a local browser login runner.
Attempts reuse `adapter_auth_sessions`, binding company, owner, provider, access
intent, reconnect target, and a 30-minute expiry. Validation and completion are
@@ -399,8 +414,7 @@ subsequently update only that grant. Reconnect preserves IDs and access settings
Starting an isolated attempt requires normal company-scoped AI-connection creation
permission. Checks, completion, cancellation, and resumption are owner-bound.
Authenticated users cannot import host credentials or use another user’s attempt.
-Claude Keychain reads remain limited to the explicit local-trusted default-home import. A failed verification creates
-no healthy connection. Preview-era Codex/Grok managed connections without the
+A failed verification creates no healthy connection. Preview-era Codex/Grok managed connections without the
isolated-subscription marker require reconnect before another managed execution;
unmanaged legacy agents retain their existing authentication paths.
@@ -439,16 +453,13 @@ authentication with a live account.
Local subscription screens share the same credential check on entry and when the
window regains focus. Waiting screens also poll until sign-in verifies. A successful
check shows the account is signed in; only **Connect** creates or reconnects the grant.
-In local-trusted mode, Claude checks the local operator’s Claude Code login.
-Authenticated Claude users, plus all Codex and Grok users, check only their
-connection-specific login home. The health response selects credential isolation,
-not whether a self-hosted user may sign in.
+Claude, Codex, and Grok check only their connection-specific login home. The
+health response selects whether a self-hosted user may sign in.
Leaving and returning to a local sign-in screen resumes its active attempt. Navigation
-does not delete a directory referenced by a copied command. **Start sign-in again**
+does not delete its credential home. **Start sign-in again**
explicitly cancels the old attempt; abandoned attempts expire after 30 minutes.
-Commands create their directory if necessary, and completed/expired attempts are
-cleaned up through the existing lifecycle.
+Completed and expired attempts are cleaned up through the existing lifecycle.
### Disposable live inline-repair test
@@ -463,7 +474,7 @@ provider key with `AI_REPAIR_TEST_KEY`. The test verifies these boundaries befor
revoking credentials or submitting work. Delete the disposable instance and revoke
its provider key after the test; failed tests may leave a paused task for inspection.
-Authenticated public deployments must configure a trusted runtime host (`PAPERCLIP_TRUSTED_MCP_RUNTIME_HOST` or `PAPERCLIP_TOOL_RUNTIME_TRUSTED_HOST`) before offering server-host subscription login, matching the local stdio runtime boundary. Health reports this capability so setup can offer a supported environment or API key instead of an unusable terminal command. Private authenticated self-hosted instances support isolated local login without that extra setting. Isolated Claude credential files must be private, owned by the server user, bounded, and free of symlinks.
+Authenticated public deployments must configure a trusted runtime host (`PAPERCLIP_TRUSTED_MCP_RUNTIME_HOST` or `PAPERCLIP_TOOL_RUNTIME_TRUSTED_HOST`) before offering server-host subscription login, matching the local stdio runtime boundary. Health reports this capability so setup can offer a supported environment or API key when local sign-in is unavailable. Private authenticated self-hosted instances support isolated local login without that extra setting. Isolated Claude credential files must be private, owned by the server user, bounded, and free of symlinks.
### Hiring and delegated work
@@ -512,3 +523,152 @@ identity, a different grant or responsible user, or a changed credential generat
requires a fresh session. The metadata is removed before passing session params
to an adapter. Temporary authentication-home paths do not change the configuration
fingerprint. These checks do not relax current connection authorization.
+
+
+## Advanced provider routing (2026-10-02)
+
+Use the regular rows on **Connectors** to add OpenRouter, Amazon Bedrock,
+Google Gemini, a Responses API, Messages API, Chat Completions API, or local
+endpoint connection. Each row has its own Connect action and saved accounts.
+The catalog tags these entries `model-provider`; no category UI is shown.
+Responses-compatible gateways such as Emissary use the Responses API row.
+The native subscription/API-key onboarding remains the default. Provider choices
+show the existing local brand artwork and reuse the existing access step. Custom
+URLs, protocol, AWS region, and credential fields appear only after choosing the
+corresponding connector. New connections default to everyone in the organization
+and all agents when the actor has permission; the existing Advanced disclosure
+contains the controls to narrow access, without a separate Access step. New-agent setup also offers the connection picker in its persistent
+**Advanced / Custom Gateway** tile.
+
+At **Agents → [agent] → Harness / Runtime**, **Connection** is a dropdown of
+compatible saved connections, including explicit personal accounts. The existing
+model picker uses that connection’s optional model IDs and accepts manual IDs.
+Changing connections preserves the model for explicit review. URLs and
+credentials belong to the connection; the model belongs to the agent.
+
+| Harness | Implemented managed routes |
+| --- | --- |
+| Codex legacy and Codex New Runner (app-server) | OpenRouter; custom/local OpenAI Responses endpoints |
+| Claude legacy and Claude New Runner (ACPX) | OpenRouter; custom/local Anthropic Messages; Bedrock API key |
+| OpenCode legacy and New Runner | OpenRouter; custom/local Chat Completions |
+| Hermes local | OpenRouter; custom/local Chat Completions |
+| Gemini CLI, Grok | Their native API connections; custom routes are not advertised |
+
+Migration `0306` adds Google to both account-default provider constraints. Local
+Gemini connections seed the API-key auth choice in their disposable home before
+environment probes and task execution. The settings file contains no credential.
+
+OpenClaw Gateway, Hermes Gateway, Claude Managed, AWS AgentCore, Process, HTTP,
+and legacy `acpx_local` are excluded: external agents retain their own model
+configuration, and `acpx_local` is retired. Cursor/Pi/Copilot custom routing,
+Vertex, ambient AWS identity, arbitrary authentication headers, and automatic
+catalog discovery for custom gateways are not part of this implementation.
+
+OpenRouter connections without an explicit model list automatically load its public
+[model catalog](https://openrouter.ai/docs/api/api-reference/models/list-all-models-and-their-properties),
+ordered with `sort=most-popular`. New-agent setup and agent settings share this
+discovery path, preserve the provider's ordering, and adapt model IDs to the selected
+harness. Explicit connection model lists take precedence. Catalog discovery sends
+no credentials; a failed request offers refresh and manual model entry.
+
+`config.ai.routing` stores only kind, protocol, URL, auth method, region, and
+optional model IDs/labels. The vault stores provider API keys, including Bedrock API keys.
+Fixed bindings contain only connection/grant identity. The server checks actual
+connection metadata, company, owner/audience, installation, status, and protocol
+before resolving secrets. Advanced connections cannot silently become native
+personal defaults. Reconnect replaces credentials and preserves destination;
+changing destination requires a separate connection. Credentials are never
+submitted to a new URL as part of reconnect.
+
+Native OpenCode custom gateways keep the reusable key in the runner process.
+The harness configuration contains a session-scoped loopback capability, limited
+to the configured model's Chat Completions endpoint. Streaming and provider error
+status are preserved; redirects are rejected. Closing or failing the harness
+revokes the capability and aborts outstanding requests. Upstream requests use
+session-local Node HTTP/HTTPS agents with the runtime's HTTP_PROXY, HTTPS_PROXY,
+ALL_PROXY fallback, NO_PROXY bypasses, and SSL_CERT_FILE/SSL_CERT_DIR trust. The
+harness bypasses outgoing proxies for loopback broker/MCP calls. This bounds key exposure
+from shell tools reading the configuration; it is not an OS isolation boundary
+against a process debugger running as the runner user.
+
+Only fixed official provider endpoints receive control-plane key checks. Custom
+endpoints and Bedrock are exercised by the selected harness in the selected
+execution environment, through **Run test**. Saving a custom connection records
+configuration; it is not proof that the model can respond. HTTPS is required for
+remote URLs; loopback endpoints may use HTTP. Localhost refers to the agent’s
+execution environment, including when it is a sandbox. URLs cannot contain user
+credentials, query parameters, or fragments.
+
+Managed Grok uses a disposable runtime home. Paperclip does not retain or restore
+Grok transcript files into host temporary directories: private file modes do not
+isolate agents running as the same OS user. Archives from earlier development
+builds are ignored. Provider session metadata still saves normally. If the selected
+session has no history in its current execution environment, Grok starts a fresh
+session with the Paperclip task handoff rather than attempting remote subscription
+recovery. Transcript continuation requires an isolated provider history solution
+and is not qualified by this change.
+
+Runtime projection clears alternate provider credentials and routing overrides,
+uses disposable homes, and never falls back to host authentication. Codex probes
+retain the selected provider home. The new runner copies only the validated
+Paperclip provider stanza into its isolated Codex home, preserves its own tool
+and sandbox policy, and disables shell snapshots. TypeScript and Rust launch
+boundaries explicitly allow only the corresponding provider credential and
+routing fields. Keys remain outside model-issued command environments on the
+new Codex runner. Hermes custom endpoints use an isolated `config.yaml` with an
+environment reference for the key.
+
+Primary configuration references consulted:
+[Codex custom providers](https://developers.openai.com/codex/config-advanced/),
+[OpenRouter Codex](https://openrouter.ai/docs/cookbook/coding-agents/codex-cli),
+[OpenRouter Claude](https://openrouter.ai/docs/cookbook/coding-agents/claude-code-integration),
+[Claude gateways](https://code.claude.com/docs/en/llm-gateway),
+[Claude Bedrock](https://code.claude.com/docs/en/amazon-bedrock),
+[OpenCode providers](https://opencode.ai/docs/providers/), and
+[Hermes providers](https://hermes-agent.nousresearch.com/docs/integrations/providers).
+
+Validation includes negative company/owner/revocation/protocol checks, no-auth
+vault behavior, immutable reconnect destinations, credential projection, Codex
+probe isolation, and new-runner home/environment boundaries. The isolated local
+test-drive exercised live OpenRouter requests using the Codex and Claude CLI
+probes, then completed real tasks using Codex, Claude, and OpenCode New Runner.
+The app walkthrough verified connection selection, saving, and completed tasks.
+A follow-up Codex/OpenRouter acceptance test ran a shell calculation, completed
+the task, then resumed from a new user message and completed a second shell
+calculation with the prior context. Reconnect coverage round-trips routing
+through PostgreSQL JSONB and verifies that credential rotation retains identity
+and agent access.
+General AWS access keys are not accepted or forwarded to Claude; use a Bedrock
+API key. Support for AWS roles requires a credential broker before it can ship.
+The initial OpenCode tool-use check was denied terminal access. The native driver
+now includes the assigned workspace and its canonical path in the allowed
+directories while preserving the configured tool policy. Subsequent local
+qualification verified tool use and follow-up on the affected OpenCode route.
+Live Bedrock verification subsequently passed with a short-lived Bedrock API key,
+region `us-east-1`, and `us.anthropic.claude-sonnet-4-6`. The saved connection
+passed **Run test**. Claude legacy and Claude New Runner each ran a terminal
+calculation, completed the task, and ran a context-dependent follow-up. Actual
+tool output was verified for all four successful runs. Private gateways still
+have deterministic mapping and validation coverage but need live verification
+in the target deployment. Short-lived Bedrock keys must be rotated before expiry.
+
+The repeatable provider connection campaign is documented in
+[`tests/runner-e2e/PROVIDER-CONNECTIONS.md`](../../tests/runner-e2e/PROVIDER-CONNECTIONS.md).
+It preserves actual tool outputs, downloaded artifacts, completion and follow-up
+receipts, source provenance, cleanup, and provider failures. The retained local
+qualification has 43 passing API/gateway cells out of 46; staging and all
+subscription combinations remain unqualified. Gemini CLI 0.58.0 has an upstream
+ACP new-file error conversion defect. The provider-free filesystem probe exposes
+that defect without modifying the installed CLI. Provider overloads and one
+follow-up timeout also remain live qualification limits.
+
+### Gateway completion compatibility
+
+Provider-facing `paperclip_finish` accepts an omitted or `null` continuation for
+`done`, `completed`, and `needs_review`. This supports gateways that require all
+declared tool properties to be present. Normalization removes only `null`;
+non-yielding tool calls still reject a continuation object, and `yielded` still
+requires a complete `response_wake` object.
+
+Task-card account repair uses the provider reconnect form for routed accounts,
+retaining the saved endpoint, protocol, model aliases, and connection identity.
diff --git a/doc/connections/CONNECTION-INSTRUCTIONS.md b/doc/connections/CONNECTION-INSTRUCTIONS.md
new file mode 100644
index 00000000000..5afca12342a
--- /dev/null
+++ b/doc/connections/CONNECTION-INSTRUCTIONS.md
@@ -0,0 +1,120 @@
+# Connection instructions
+
+Connection instructions are an optional, provider-independent capability. A saved
+connection can contribute a short paragraph to an authorized agent’s execution
+prompt. Memory providers are the first catalog templates; custom and non-memory
+connections use exactly the same settings, authorization, and delivery path.
+
+## Catalog and saved settings
+
+A connector can declare `agentInstructions: { id, version, text }` in its
+`AppDefinition`. Author reviewed defaults directly in that app's
+`packages/shared/src/app-definitions/.json`, alongside its configuration
+and supporting provider `docsUrl`. This field is the source of truth; there is
+no separate template registry. Catalog ingestion validates and preserves it,
+including edits or removal, when regenerating the other definition fields. Run
+`node scripts/ingest-app-definitions.mjs --definitions-only` to verify. Template
+text is limited to 2,000 characters. Remote MCP initialization prose is never
+adopted as trusted instructions automatically.
+
+Every `ToolConnection` has nullable `agentInstructions`:
+
+```json
+{
+ "enabled": true,
+ "text": "Use the release handbook before changing a deployment. Cite the checklist.",
+ "template": { "id": "handbook.usage", "version": 1 }
+}
+```
+
+The template provenance is optional. Authorized custom instructions can be saved
+without a catalog template. `null` means no instructions. Disabling retains text
+and tool access. New catalog connections persist the current default enabled;
+the initial migration backfills existing connections for the five participating
+providers. A reconnect, OAuth return, or catalog refresh retains saved settings.
+Catalog version changes do not replace custom text or opt-outs. **Reset to
+default** explicitly adopts the current template and preserves the toggle.
+
+Existing connect, finish, and connection PATCH requests accept the same nullable
+setting. Mutations use connection configuration permissions and company checks,
+and write activity records. Required provider configuration lives in
+`config.methodConfig`, independently of instruction text and enabled state.
+
+## UI convention
+
+The editor appears only when explicit template metadata exists. Setup (including
+inline setup and OAuth) uses the current flow, without another wizard step. The
+Permissions page places **Agent instructions** after agent access and before
+Actions. It shows **Tell agents to use {provider}**, visible text, editing,
+**Reset to default** after changes, and an amber notice when off. Failed saves
+retain the draft. Agent Instructions includes a read-only **From connections**
+section with source links and an explanation of task-dependent availability.
+Disabled instructions remain inspectable there with an amber notice.
+
+## Runtime delivery and compatibility
+
+The gateway resolves instructions using the stored run’s company, agent, task,
+project, active responsible identity, connection grants, and effective action
+policy. At least one tool must be available (including tools requiring approval).
+The resolver uses persisted settings and the cached catalog; it does not contact
+providers. It does not gate delivery on a provider name, memory category, or the
+presence of a catalog template.
+Prompt assembly checks access to candidate connections’ cached tools directly,
+using the same task restrictions and policy decisions as discovery. It does not
+enter the discovery queue, so queue saturation neither drops guidance nor replaces
+an otherwise compatible session. Revocation is still checked on every turn.
+
+Eligible blocks are sorted by connection ID. Each block identifies its
+connection, selected grant, optional template provenance, and declared public
+configuration. Secret/password fields are excluded. Missing required public
+configuration withholds standing instructions. The snapshot is `{ text, digest }`,
+where `digest` is SHA-256 of the complete UTF-8 text. Declared public configuration and
+source changes therefore change the digest as well as text edits.
+
+The server replaces caller-supplied runtime instruction fields before executing.
+Native Runner receives the snapshot in `runtimeContext.connectionInstructions`
+and composes it alongside agent instructions. Legacy adapters receive it through
+shared wake-prompt composition on fresh and resumed turns. Session compatibility
+includes the snapshot: changing or removing it replaces an incompatible session,
+including when live tool refresh would otherwise retain that session. Active
+turns retain the snapshot with which they started. Older native snapshots without
+this field remain valid. No AGENTS.md or shared harness home is modified.
+
+Custom integration contracts:
+
+- **HTTP adapter:** the JSON request contains top-level `connectionInstructions`
+ (`{ text, digest }` or `null`), also available on invocation `context`.
+ This server-owned field overrides `payloadTemplate`. Append its text alongside
+ agent instructions before invoking a model; do not reuse a session with a
+ different digest.
+- **Process adapter:** `PAPERCLIP_CONNECTION_INSTRUCTIONS_FILE` points to a private
+ JSON file containing the same snapshot. Read it during the invocation and
+ append `.text` to your model prompt. It is empty when no instructions apply.
+ Configured or inherited paths cannot override it. The temporary file is removed
+ when the process exits, including failure paths.
+
+Instruction guidance grants no new permissions. Approval requirements remain
+attached to tool calls, and remembered content does not override the current task.
+Provider memory scope follows the provider’s real configuration; Paperclip does
+not claim isolation from invented agent IDs or tags.
+
+## Honcho configuration
+
+Honcho requires `config.methodConfig.workspaceId` for new setup. The field is
+expanded above instructions, with validation beside it. For tools declaring a
+`workspace_id` argument, the existing managed-argument mechanism projects the
+configured workspace after caller arguments and removes the field from the
+agent-visible schema. Pending approvals compare against the current projected
+arguments, so changing the workspace invalidates the old approved invocation.
+Existing connections missing a workspace retain their tools and manual workspace
+arguments, but receive no standing guidance until configured.
+
+## Verification
+
+`server/src/__tests__/connection-instructions.test.ts` persists a non-memory
+fixture, resolves effective access, captures a real process invocation, and checks
+shared/native prompt composition. Route tests cover permissions and OAuth draft
+preservation. Session tests cover edits/removal and incompatible resumes.
+Storybook uses production components backed by stateful mock APIs, including
+Notion with and without explicit templates. Model behavior evaluations and new
+agent/company memory scope controls are deferred.
diff --git a/doc/connections/CONNECTOR-PERMISSION-AUDIT.md b/doc/connections/CONNECTOR-PERMISSION-AUDIT.md
index 07942d7504f..8b41d07f228 100644
--- a/doc/connections/CONNECTOR-PERMISSION-AUDIT.md
+++ b/doc/connections/CONNECTOR-PERMISSION-AUDIT.md
@@ -1,11 +1,15 @@
# Tool connection permission audit — 2026-09-30
-This review covers 117 tool methods (84 OAuth methods). The machine-readable
+This review covers 119 tool methods (85 OAuth methods). The machine-readable
[source of reviewed defaults](./tool-method-permission-reviews.json) lists each
method's exact requested scopes, supported actions, restrictions, sources and
verification limits. AI runtime authentication and chat/channel setup are
separate contracts and were not changed.
+Methods reviewed after this audit carry their own `reviewedAt` date in the same
+ledger; the counts above are not restated. Later additions: [Neon](./NEON.md)
+(`mcp-oauth`, `mcp-api-key`; 2026-10-02).
+
## Shared credential failure
Zapier's secret URL exposed a shared ownership/resolution problem. The same
diff --git a/doc/connections/CONNECTOR-PLAYBOOK.md b/doc/connections/CONNECTOR-PLAYBOOK.md
index cd2db9348c8..6c5f7913b2f 100644
--- a/doc/connections/CONNECTOR-PLAYBOOK.md
+++ b/doc/connections/CONNECTOR-PLAYBOOK.md
@@ -122,6 +122,7 @@ read/write proof separately and never describe metadata discovery as live proof.
- [Current access defaults](#current-default-access-policy)
- [Golden-path agent tutorial](#golden-path-agent-tutorial)
- [Connection UX and user journeys](#connection-ux-and-user-journeys)
+- [Optional agent instructions](#optional-agent-instructions)
- [Chat and email connector UX](./CHAT-CONNECTOR-UX.md)
- [Production validation evidence](#step-9-align-with-production-validation)
- [AppDefinition field reference](#appdefinition-field-reference)
@@ -147,6 +148,59 @@ A complete connector proposal produces:
denied/quarantined call when the method declares one, revoke, and audit
evidence.
+## Optional agent instructions
+
+Some connections need standing guidance: tools tell an agent what it *can* do,
+while a short paragraph explains when it should use them. Memory is the first
+use case. See [Connection instructions](CONNECTION-INSTRUCTIONS.md) for the
+generic catalog metadata, saved settings, API, runtime, and integration contracts.
+**Design explorations → Connections → Agent instructions** in Storybook uses
+production components with mocked APIs.
+
+When adding a template:
+
+- Show the section only when the connector explicitly provides a nonempty
+ instruction template. Use **Agent instructions** and the checkbox
+ **Tell agents to use {provider}**, with the exact paragraph visible. No template
+ means no instructions UI, including no blank editor.
+ Keep setup in the existing flow and its single footer; add no required test or
+ extra wizard step. Use the current shared access defaults/disclosure.
+- Use a reviewed, versioned provider-specific suggestion. Explain when to recall,
+ when to save, the allowed context, and what to do if a call fails. Prefer one
+ short paragraph over a full skill or a pasted tool catalog. Avoid unsupported
+ promises about hooks, automatic transcript capture, or private memory.
+- Default provided instructions on for every participating connector. Let users
+ edit, **Reset to default** after changes, or disable guidance while retaining
+ tools. Show a compact amber notice when off. Reconnect and catalog refresh
+ preserve explicit opt-outs and custom text. Omit suggestion attribution badges
+ and routine lifecycle/storage helper copy.
+- Edit in an optional **Agent instructions** section of the existing **Permissions**
+ page, between agent access and Actions. Use the actual connection page shell,
+ credential form, and footers in review stories; include a baseline story for
+ comparison rather than constructing parallel page chrome. Show recipients
+ from current assignments and a read-only, source-linked copy on the agent.
+ Keep action controls and tests in the existing **Permissions** screen.
+- Resolve runtime guidance with the same company, agent, task, responsible-user,
+ and grant checks used for tools. Compose a revisioned block alongside agent
+ instructions; never permanently edit AGENTS.md or shared harness home files.
+ Verify fresh and resumed turns, removal, revoked access, and unsupported adapters.
+- Keep required provider settings, such as Honcho workspace, expanded near the
+ top of setup and configuration, above instructions. Put validation beside the
+ field and block completion while required values are missing. Memory stays an
+ ordinary connection; do not add a default-memory chooser or agent preference.
+ Keep provider binding identifiers separate from editable prose. Agent IDs,
+ tags, and query filters alone are not access-control boundaries. Any promised
+ isolation needs server enforcement across all relevant tool paths.
+- Treat MCP initialization instructions as external provider content. Review
+ them as template source; do not silently inject arbitrary remote text or let
+ a provider update overwrite an operator's instructions. Guidance never grants
+ additional tool permissions.
+- Prove both delivery and behavior: deterministic assignment/resume checks, then
+ a bounded save → **fresh session** recall with synthetic data through the real
+ run gateway. Record exact model/template/catalog versions, tool receipts,
+ costs, ingestion timeout, and cleanup. Discovery and a model's “saved” reply
+ do not prove memory works. See the linked plan for the minimal matrix.
+
## Use This Document As The Checklist
An agent implementing a connection should be able to begin with only a provider
@@ -158,7 +212,7 @@ The shortest valid implementation usually changes these files:
```text
scripts/ingest-app-definitions.mjs # human-authored definition source
-packages/shared/src/app-definitions/.json # generated definition
+packages/shared/src/app-definitions/.json # definition with app-owned instruction template
packages/shared/src/app-definitions.generated.ts # generated registry
ui/public/brands/apps/.svg # official, sanitized mark
ui/public/brands/apps/manifest.json # runtime branding paths
@@ -648,7 +702,7 @@ controls and precise labels over explanatory paragraphs. Remove repeated
headings, redundant access summaries, implementation details, and reassurance
that does not help the user decide or act. Keep necessary warnings, meaningful
consequences, and actionable errors. Put optional expert settings under a
-collapsed Advanced disclosure. Link to provider-owned administration, such as
+collapsed disclosure through **Change**. Link to provider-owned administration, such as
AgentMail allowlists, rather than rebuilding it in Paperclip.
**Keep ongoing interactions in Paperclip tasks.** Connections are where users
@@ -708,7 +762,13 @@ definitions and visible manifest entries to match exactly.
### Phase 5: Author the definition at the durable source
-The checked-in provider JSON files are generated. Do not edit one and stop.
+Transport/auth fields in the checked-in provider JSON files are generated. Do
+not edit those fields and stop. Optional `agentInstructions: { id, version, text }`
+templates are authored directly in each app's JSON definition, alongside its
+supporting `docsUrl`. Ingestion validates and preserves that field; edit or
+remove it there, and increment its version when changing the default. There is
+no central instruction-template registry. See
+[Connection instructions](./CONNECTION-INSTRUCTIONS.md) for the runtime contract.
1. Add or update the provider in `scripts/ingest-app-definitions.mjs`.
2. Update `packages/shared/src/self-serve-mcp-research.json` when it belongs to
@@ -1511,11 +1571,16 @@ The operator should see Apps, Connections, and Review language. Keep protocol la
Request only the documented scope set the reviewed connection needs; never
adopt every scope returned by discovery. Operators should not have to predict
every future tool during setup. Keep the default view to the minimum inputs
-needed for a working connection, fold optional expert controls under one
-collapsed **Advanced** disclosure, and enforce execution afterward through
+needed for a working connection, fold optional expert controls under the
+**Change** link beside the access summary, and enforce execution afterward through
Paperclip's resource boundaries, risk classification, tier defaults, optional
quarantine, and audit.
+When a provider supplies its MCP endpoint, keep that URL out of the initial
+form. Composio exposes it through **Reuse an existing session** for operators
+with a custom session URL; resumed custom endpoints and URL validation errors
+keep the field visible. Preserve the endpoint when its disclosure is closed.
+
### Step 8: Apply Governance Defaults
Governance is automatic because every catalog entry becomes a normal tool-access object:
@@ -2326,3 +2391,147 @@ in-memory provider responses. The `provider-native`, `provider-decline`, and
`provider-second` Product E2E cases exercise native preference, persisted choice,
restart recovery, and an independently observed gateway read. They do not prove
compatibility with the real external providers.
+
+### Public aggregator apps in Connectors
+
+The Connectors catalog combines native definitions with the public Composio and
+Arcade app snapshots in `packages/shared/src/aggregator-app-catalog.ts`. Native
+definitions always take precedence, including definitions temporarily hidden or
+unavailable on the instance. Each remaining app has one card with its provider
+logos; Connect opens a provider picker when multiple providers support the app.
+An app with one provider goes directly to setup or its saved gateway flow.
+Search covers names, aliases, providers,
+and saved accounts. The uninstalled catalog uses pages of 50 entries; matching
+installed connectors remain above every page. Listing an upstream app never
+creates a Paperclip connection or marks that app authorized.
+Provider filters include native cards only when they contain accounts managed
+by that provider. A matching public catalog entry alone does not include a
+native card; its native onboarding remains in Paperclip and All.
+
+Composio app setup offers a dropdown of connected Composio accounts and an option
+to connect a new one. The board calls `COMPOSIO_MANAGE_CONNECTIONS` directly to
+check the requested toolkit and generate its hosted authorization link. This
+creates no task and starts no agent run. An already active app skips new link
+creation. After the human signs in, completion checks the toolkit's ACTIVE
+account status again. New gateways default to all humans and all agents; app
+setup preserves the selected gateway's saved access and tool policies without
+adding agent-specific grants. Access remains gateway-wide, not app-level
+isolation. Saved credentials are resolved for the acting human and authorization
+URLs stay outside audit/result storage. A failed or uncertain add is never
+retried automatically; the user can explicitly request a new link.
+
+Composio is authoritative for app accounts and authorization. Paperclip stores
+only account observations in `tool_connection_app_snapshots`: IDs, aliases,
+statuses, default flags, check times, and failure times. Observations are scoped
+to company, saved gateway, viewing human, and credential identity, including
+secret versions. Credential replacement or rotation hides the old inventory.
+Discovery and app setup never create agent grants or change saved policies.
+
+Apps starts a background check of the entire supported public Composio catalog,
+independent of search and pagination. `POST /tool-connections/:id/composio/apps/sync`
+returns cached observations and sync progress; `{force:true}` requests a refresh.
+`tool_connection_app_syncs` holds a per-credential lease and progress. Repeated
+visits and concurrent tabs share the lease. Checks use explicit `action:list`,
+batches of 32, a four-minute deadline, and five-minute freshness. Known accounts
+are checked first. Polling updates account rows while browsing stays usable.
+Manual **Refresh Composio** belongs in the saved Composio account's kebab menu;
+it checks that account only. Do not add a catalog-wide refresh button.
+Composio gateway setup finishes on its Permissions page. That page lists detected
+apps in a bounded, scrollable list and starts a refresh on first load. Its
+**Refresh Composio** button shows catalog-check progress and refreshes only that
+gateway. The same connected-app list and refresh controls serve Arcade and
+Executor gateways when discovery is available. Executor remains available as a
+connection, but its catalog filter chip is temporarily hidden.
+A complete empty list removes an observed account; EXPIRED accounts show Needs
+sign-in. Failed or incomplete evidence retains the last accounts, visibly
+unverified, and offers retry. Interrupted jobs can be restarted after the lease
+expires. A late response cannot replace a newer check or a changed credential.
+
+The saved Connect MCP OAuth credential supports listing accounts by toolkit;
+it is not a consumer user API key or a developer project API key. This discovery
+covers the supported public catalog, including toolkit variants. It does not
+claim complete enumeration of custom apps outside that catalog. A future
+identity-bound inventory endpoint should replace this scan when available.
+Never forward an MCP OAuth token to an unrelated REST inventory endpoint.
+
+Imported accounts appear above the paginated catalog with their actual source:
+**Via “saved connection name”**, rather than attributing upstream authorization
+to the gateway creator. Already connected Composio accounts remain visible even
+when Paperclip has a native connector; native Connect offers still take
+precedence. Imported account menus offer only **Open in Composio**. Access
+controls remain on the saved gateway and apply to all apps on that connection.
+The Manage dialog displays provider observations
+and links to Composio; it does not offer local rename or upstream removal.
+Use `https://dashboard.composio.dev/~/org/connect/apps` for Connect app management.
+The organization placeholder resolves to the signed-in user's For You area.
+The bare dashboard opens Platform developer projects, which have a separate
+account inventory and are the wrong destination for saved Connect MCP accounts.
+Remove connection remains available on the saved gateway itself. Its confirmation
+states that removing it from Paperclip does not delete accounts in Composio.
+
+Targeted Composio app setup URLs reuse the saved-account chooser when an active
+gateway exists. Explicit `new=1`, resume, and reconnect keep their own gateway
+setup flow. Existing ACTIVE app accounts are checked without creating another
+hosted link or a task. New app authorization remains a direct hosted sign-in
+handoff, followed by a fresh account check.
+
+Arcade still offers an agent task draft to verify the requested app and obtain
+any provider authorization link. It requires the app's tools in the selected
+gateway, a catalog refresh, and any tool authorization. New gateway setup retains
+the app name through `targetToolkit`; it creates only the provider gateway.
+Composio then returns to direct app setup; Arcade opens the task draft.
+Setup entry points preselect an assignable agent: prefer an agent named
+**Default agent**, then organizational rank and leadership roles, then creation
+date. If there is no named default, use the same rank and age ordering on the
+remaining agents. The user can change the selection before continuing.
+The board's Create Task action creates a new task even when an open task has the
+same title. A request key protects retries of the same submitted draft, and the
+success confirmation links to the created task.
+Connection setup drafts opt into the dialog's `navigateOnCreate` option, taking
+the operator to the created task after submission. Other callers stay on their
+current page by default; the option does not add a visible control.
+The task asks the assigned agent to perform setup directly without hiring or
+delegating, and to provide a browser link and wait when human authorization is
+needed. Before provider calls, it checks access for the task's current assignee.
+Missing access uses `connection_request` with the saved `connectionId` and exact
+indexed `toolNames`, producing an embedded card with the requesting agent's
+avatar and a **Grant access** action. The addressed human connection manager
+approves the frozen tool set; acceptance adds agent-scoped access and resumes
+the task. Composio setup asks for Search Tools as Allowed and Manage Connections
+as Ask first. Writes and unknown-risk tools retain per-call approval. Changed or
+quarantined tools require a new request. Existing policies, identity selection,
+and other agents' access are preserved. The task never grants itself permissions
+or requests access for every agent.
+The connection's Permissions page lists additional agent access separately
+and lets the connection manager remove it without changing the default action
+permissions. Removing that grant also disables its Ask-first tools.
+A successful agent run or a local gateway fixture does not prove that
+the underlying app is authorized; verify against the real provider gateway.
+OAuth recovery exposes a validated native sign-in link on both page and dialog
+hosts. A blocked window or navigation retains the existing connection and OAuth
+session so the link can continue sign-in without creating another gateway.
+
+Composio reuses `composio-search-catalog.json`. Arcade's snapshot records its
+official logo and evidence URLs, excluding hidden and coming-soon entries. To
+review and refresh only Arcade's claims, run:
+
+```sh
+node scripts/update-arcade-app-catalog.mjs --verified-at YYYY-MM-DD
+```
+
+Use the date of the public catalog review. The script preserves the prior file
+if the source structure or entries fail validation. `--input ` allows
+reproducing the snapshot from the same official catalog response. Neither public
+snapshot proves a user's gateway configuration or app authorization.
+
+### Managed aggregator account inventory
+
+Composio, Arcade, and Executor observations share the existing app snapshot/sync tables and the manager-only `/api/tool-connections/:connectionId/aggregator/apps` list, `/sync`, and `/refresh` endpoints. Legacy Composio endpoints remain supported. These rows are observations, never executable connections or authorization grants. Company, gateway, viewing human, and effective credential version define the cache; fully successful enumeration reconciles removal, while partial failure retains stale observations.
+
+Arcade discovery paginates its [admin account list](https://github.com/ArcadeAI/arcade-go/blob/main/adminuserconnection.go) and [tool requirements](https://github.com/ArcadeAI/arcade-go/blob/main/tool.go), filters to the configured user and exposed gateway tools, and stores only allowlisted account metadata. An existing project key plus `Arcade-User-ID` can be reused. Otherwise optional manager-only sync setup stores a separate user-owned vault key for discovery; it is excluded from gateway invocation credentials and tool access grants. OAuth gateway tokens are not substituted for project keys.
+
+Executor reads its [MCP integration inventory](https://github.com/UsefulSoftwareCo/executor/blob/main/packages/hosts/mcp/src/tool-server.ts) or uses fixed, read-only `connections.list` and `integrations.list` calls in code mode. Its pure `connections.createHandoff` URL builder can supply the upstream console destination. No arbitrary generated code or provider REST endpoint is used. Unknown integrations remain separate, without guessed branding. Last-health `healthy` is connected, `expired` needs sign-in, and unverified or degraded health never earns a green check. Missing inventory support is visible as discovery unavailable. Managers can set a trusted HTTPS console URL for gateways that do not expose a destination, preserving workspace and self-hosted paths.
+
+Apps groups native and imported accounts under canonical app cards, preserving all upstream account identities. Native onboarding wins over aggregator connect offers. Imported account menus only open their upstream provider; deletion and per-app authorization stay upstream. Parent gateway menus own refresh and optional discovery setup. Paperclip policies continue to govern invocation through the gateway.
+
+Acceptance fixtures: `server/src/__tests__/aggregator-app-discovery.test.ts`, `server/src/__tests__/aggregator-app-sync.test.ts`, `ui/src/pages/apps/Browse.test.tsx`, and the production-page/full-stack test drive at `tests/aggregator-accounts/test-drive.ts`. The expected stories and evidence are recorded in `doc/plans/2026-10-05-managed-aggregator-account-user-stories.md`. Fixture runs do not replace live provider proof when working credentials are available.
diff --git a/doc/connections/ENTERPRET.md b/doc/connections/ENTERPRET.md
new file mode 100644
index 00000000000..768f20e20c3
--- /dev/null
+++ b/doc/connections/ENTERPRET.md
@@ -0,0 +1,634 @@
+# Enterpret connection
+
+Enterpret's hosted MCP server answers questions about an organization's customer
+feedback — themes, accounts, sentiment, and verbatim quotes with citations back
+to the source records.
+
+This document follows the template in
+[Connection Authoring Runbook](./CONNECTOR-PLAYBOOK.md) and records exactly what
+was and was not verified.
+
+**The connector has now been exercised against a real Enterpret account** — a
+named account holder signed in through an isolated Paperclip runtime on
+2026-09-25 (PAP-18538), and agent tool calls reached the live server. The
+organization-token method was separately exercised on an isolated self-hosted
+runtime on 2026-09-30.
+
+**Release path:** the **organization auth token** (`mcp-api-key`) is the
+primary connection method. Generate a Bearer token under Enterpret
+**Settings → Enterpret MCP** and paste it into Paperclip. Public MCP tools are
+read-only today; the token path does not depend on Enterpret honouring a
+narrowed OAuth grant.
+
+**Current product decision — 2026-10-01:** support both organization tokens
+and browser OAuth for the official **read-only Enterpret MCP** at
+`https://wisdom-api.enterpret.com/server/mcp`. The account holder reported a
+live conversation with Vivek confirming that Enterpret Agent's write MCP is a
+separate beta service with known bugs. That service is outside this connector's
+scope and will be reviewed separately when ready.
+
+Vivek committed to fixing OAuth scope behavior and reducing the token
+revocation cache window. This is a provider commitment relayed by the account
+holder, **not verified deployment evidence**. The earlier inference that an
+`mcp:write` scope name made this connector write-capable is withdrawn. Both
+methods are selectable on this draft branch; fresh OAuth authorization,
+refresh and real-agent allow/deny checks remain release QA. The account holder
+confirmed the provider fixes are fast follows after deployment, not prerequisites
+for shipping this connector.
+
+Several live read and gateway checks passed on the OAuth method. The primary
+token path passed connection, catalog, safe read, refresh, and reconnect checks;
+a real agent process and server/VPS or Cloud deployment remain unverified.
+The dashboard's token revocation did not immediately invalidate the token. See
+[Validation Hook](#validation-hook) for the scenario-by-scenario record.
+
+Authored against Paperclip App `fff410dfe777ae0427385e8297df992ba9aed4ce`, with
+`CONNECTOR-PLAYBOOK.md` blob `5efd4cca05a1c94bb47d619833ba347f416bbbed` as the
+authority. Provider metadata read 2026-09-23 and re-read unchanged 2026-09-25.
+Live validation ran on App `ef1606f037a7828a7ba774949e811847c1a1d386`.
+
+## Vendor
+
+- App key: `enterpret`
+- App name: Enterpret
+- Owner: unassigned. No Paperclip maintainer currently owns an Enterpret account.
+- Reuse classification: **MCP-direct**
+- Reason for classification: Enterpret publishes an official hosted MCP server
+ over Streamable HTTP whose authorization server is discoverable from the
+ endpoint itself. No REST shim and no vendor-specific wrapper is needed; the
+ tools map onto ordinary read grants.
+- Security tier: **S3**
+- Plugin needed? No. The provider is expressible as metadata plus a transport:
+ no plugin tables, workers, webhooks, or dedicated UI.
+
+### Why a catalog entry at all
+
+An operator can already reach this server with no Paperclip code change, through
+**Connect your own MCP server** or **Advanced → Paste a config**
+([Generic remote MCP](./GENERIC-REMOTE-MCP.md)). The catalog entry adds only:
+official artwork, two labelled methods with the correct client-ownership and
+grant-identity shape, a reviewed scope allowlist narrower than the advertised
+set, a recorded risk tier, and the provider docs link. Those are real but
+incremental. Treat the generic path as the baseline, not as a lesser fallback.
+
+## Transport And Auth
+
+- Transport: `mcp_remote` (Streamable HTTP)
+- Endpoint: `https://wisdom-api.enterpret.com/server/mcp`. The bare and
+ trailing-slash forms behave identically — `401`, no redirect.
+- Auth modes: **API key / organization auth token** (`mcp-api-key`, primary)
+ and **OAuth** (`mcp-oauth`). Both methods are selectable on one catalog entry.
+- OAuth scopes: requested `mcp:read`. Advertised by the provider: `email`,
+ `mcp:read`, `mcp:write`. See [Scope decision](#scope-decision). Fresh OAuth authorization and refresh checks are pending provider deployment.
+- Key scope: the Enterpret auth token is generated per Enterpret organization
+ and carries that organization's access. Enterpret does not document a
+ restricted or read-only token variant. Public tools remain read-only.
+- Credential owner: the auth token is an organization credential
+ (`grantKinds: ["organization"]`); OAuth is user-delegated
+ (`grantKinds: ["user"]`).
+- Secret storage: `company_secrets` refs only. The definition records the header
+ placement, never a value.
+- Revocation behaviour: **no `revocation_endpoint` is advertised.** See
+ [Revocation gap](#revocation-gap).
+
+### Connection Flow (mandatory)
+
+```mermaid
+sequenceDiagram
+ participant O as Operator
+ participant P as Paperclip instance
+ participant R as wisdom-api.enterpret.com
+ participant A as oauth.enterpret.com
+ O->>P: Connect Enterpret, method mcp-oauth
+ P->>R: POST /server/mcp initialize, unauthenticated
+ R-->>P: 401 WWW-Authenticate with resource_metadata
+ P->>R: GET /server/mcp/.well-known/oauth-protected-resource
+ R-->>P: authorization_servers https://oauth.enterpret.com
+ P->>A: GET /.well-known/oauth-authorization-server
+ A-->>P: authorize, token, register, PKCE S256, auth method none
+ P->>A: POST /register, RFC 7591 dynamic client registration
+ A-->>P: client_id for this Paperclip instance
+ P->>O: Redirect to /authorize with PKCE challenge
+ O->>A: Sign in and consent
+ A-->>P: Redirect to /api/tools/oauth/callback with code
+ P->>A: POST /token, code plus verifier
+ A-->>P: Access token and refresh token
+ P->>R: POST /server/mcp with the access token
+```
+
+- Auth endpoints (exact paths), all read from provider metadata on 2026-09-23:
+ - Authorize: `https://oauth.enterpret.com/authorize`
+ - Token: `https://oauth.enterpret.com/token`
+ - Registration (DCR): `https://oauth.enterpret.com/register`
+ - Discovery: `https://wisdom-api.enterpret.com/server/mcp/.well-known/oauth-protected-resource`
+ (RFC 9728) → `https://oauth.enterpret.com/.well-known/oauth-authorization-server`
+ (RFC 8414). `https://oauth.enterpret.com/.well-known/openid-configuration`
+ also resolves.
+ - Also advertised: `/introspect`, `/userinfo`. `jwks_uri` points at AWS Cognito
+ pool `us-east-2_kLiRrPBis`.
+ - Paperclip callback: `/api/tools/oauth/callback`
+- Redirect constraints: `https-or-loopback-http` in the definition. An HTTPS
+ redirect URI was accepted by DCR and round-tripped through a real consent on
+ 2026-09-25. Whether Enterpret would also accept a loopback HTTP redirect
+ remains **unprobed** — the live run used HTTPS.
+- Paperclip ID / Paperclip Connect involvement: **none.** Enterpret is an
+ RFC 7591 DCR provider, so registration is instance-local and Cloud and
+ self-hosted use the same path. The only per-instance difference is the
+ hostname inside the redirect URI.
+
+The definition ships `serverUrl` only. A complete `authorizationEndpoint` +
+`tokenEndpoint` pair would be authoritative and would suppress discovery
+permanently, including endpoints a previous discovery had persisted. Discovery
+resolves cleanly here — the `issuer` in the RFC 8414 document matches the issuer
+used to build the URL — so there is nothing to hard-code and nothing to keep
+current.
+
+### Scope decision
+
+Paperclip requests `mcp:read` for the official read-only endpoint. The live
+2026-09-25 observation is preserved:
+
+```text
+Paperclip authorization request mcp:read
+Enterpret token response no scope field
+Enterpret token introspection openid email profile mcp:read mcp:write
+```
+
+This proves a mismatch between requested and reported scopes. It does **not**
+prove the token can invoke write tools or authenticate to the separate beta
+Enterpret Agent MCP. No write tool was observed or invoked on this endpoint.
+The previous description of this as a verified write-capable connector was
+stronger than the evidence and is superseded by the 2026-10-01 product decision.
+
+The account holder relayed Vivek's commitment to fix OAuth behavior. Validate a
+fresh authorization and refresh against current provider behavior, record
+requested and reported scopes separately, and confirm the tool inventory still
+belongs to the official read-only service. Do not widen the scope request or
+add the beta write endpoint to this definition.
+
+#14059 independently records whether scopes are provider-asserted or inferred
+from the request. That improves Paperclip's reporting; it cannot prove a
+provider's actual endpoint or capability boundary.
+
+### Revocation gap
+
+The RFC 8414 document advertises no `revocation_endpoint` — re-read 2026-09-25
+and still absent. Removing the connection in Paperclip clears local credential
+material and gateway access, but there is no documented provider-side instrument
+to invalidate an issued OAuth token. The auth-token method is separate: the
+dashboard has a Revoke control, but an immediate post-revocation read still
+succeeded on 2026-09-30. Whether generating another token invalidates an
+earlier one is untested.
+
+An `introspection_endpoint` *is* advertised, and Paperclip calls neither. That
+is worth separating: introspection tells you what a token can do, which is how
+the scope mismatch above was found, but it cannot take a token away.
+
+Consequence: the OAuth **Revoke and reconnect** scenario cannot reach
+`verified` through a provider-side revocation call — confirmed by the live
+metadata, not merely predicted. The organization-token Revoke control failed
+the immediate denial check. Local removal passed and must be recorded as
+exactly that rather than as full provider-side revocation.
+
+**Operator instruction.** Disconnecting Enterpret in Paperclip is only half of
+revoking it — and for OAuth the other half is not a procedure this validation
+can hand you. The two methods differ, and they must not be described as one:
+
+- **OAuth.** Paperclip cannot revoke the token: no `revocation_endpoint` is
+ advertised and Paperclip ships no RFC 7009 client. Whether the Enterpret
+ dashboard offers any way to withdraw an authorized MCP client is
+ **unverified** — this validation neither found such a control nor confirmed
+ one exists, so no step here should be written as if it does. Until Enterpret
+ confirms a procedure, plan on the issued token staying valid **until it
+ expires**, treat expiry as the only assured end of access, and ask Enterpret
+ support for a revocation path rather than assuming the dashboard has one.
+- **Auth token.** The dashboard can generate and revoke organization tokens.
+ On 2026-09-30 it confirmed "Your token has been revoked," but that same
+ token immediately connected again and completed `get_organization_details`
+ through an isolated Paperclip instance. Provider-side invalidation therefore
+ **failed the immediate check**. Vivek later explained a 24-hour validity
+ cache and committed to reducing it; the new delay and deployment are unverified. Do not treat the dashboard confirmation, generating another token,
+ or local disconnect as proof of revocation. Confirm the old token is denied.
+
+Any runbook or teardown that treats "disconnect in Paperclip" as provider-side
+revocation can leave a live credential at Enterpret. The OAuth grant tested
+above also carried `mcp:write`.
+
+## Administrator Setup (mandatory)
+
+- What the admin must register: **nothing.** Enterpret advertises RFC 7591
+ dynamic client registration, so the Paperclip instance registers itself at
+ connect time. No client ID, no client secret, no callback URL to pre-register.
+- Where to register it: not applicable. For the auth-token method, an Enterpret
+ admin generates a token at **Settings → Enterpret MCP → Generate** under
+ **Auth Token**. Check the expiry shown for each token in the dashboard; the
+ token generated for the 2026-09-30 QA run showed **three months**.
+- Instance prerequisites: outbound HTTPS to `wisdom-api.enterpret.com` and
+ `oauth.enterpret.com`. A public HTTPS base URL is **not** required — that
+ applies to the Client ID Metadata Document tier only, and an instance without
+ one falls through to DCR.
+- How to verify the connection works: after connecting, the connection health
+ and catalog check should list Enterpret's tools. `get_organization_details`
+ is the narrowest read and identifies which Enterpret organization the
+ credential resolves to — run that first, and confirm it is the organization
+ you intended.
+
+## Resource Filters
+
+- Required filters: none expressible. Enterpret's MCP surface scopes every call
+ to the organization behind the credential; the server documents no per-source,
+ per-account, or per-workspace request parameter.
+- Optional filters: none.
+- Write-enabling filters: not applicable — no write action is exposed.
+- Filters enforced by: **the credential itself.** The account boundary is the
+ only boundary, which is why the organization a credential resolves to has to
+ be confirmed at setup rather than assumed.
+
+## Manifest
+
+- schemaVersion: 1
+- slug: `enterpret`
+- name: Enterpret
+- description: "Ask questions about your customer feedback and pull verbatim
+ quotes with citations."
+- categories: `["analytics"]`
+- branding and provenance: `/brands/apps/enterpret.png`. The official Enterpret
+ app icon, 256×256, retrieved 2026-09-23 from the `apple-touch-icon` linked by
+ `https://www.enterpret.com/`, unmodified.
+ SHA-256 `aca19ddae5f52a2caa4f3664286a76cd9439316e0fa3c39890f646536aebc522`.
+ The provider's nav logo is a 120×24 light-on-dark wordmark, wrong shape for a
+ square tile and unusable on a light frame; the app icon is the correct
+ official mark and needs no dark variant.
+- docsUrl: `https://enterpret.support.site/article/enterpret-mcp-server`
+- Methods:
+
+| | `mcp-api-key` (primary) | `mcp-oauth` (OAuth) |
+| --- | --- | --- |
+| label | Use an auth token | Sign in with Enterpret |
+| transport | `mcp_remote` | `mcp_remote` |
+| auth | `api_key` | `oauth` |
+| ownershipModes | `["customer"]` | `["dcr"]` |
+| grantKinds | `["organization"]` | `["user"]` |
+| defaults | `serverUrl` | `serverUrl`, `scopesHint: ["mcp:read"]` |
+| credentialFields | `authorization`, password, required, secret | — |
+| keyPlacement | header `Authorization`, prefix `Bearer ` | — |
+| riskTier | S3 | S3 |
+| release role | Primary / store-ready | Personal browser sign-in; fresh release QA pending |
+
+ `ownershipModes` omits `customer` on the OAuth method on purpose: Enterpret
+ documents no way for a customer to register their own OAuth application, and
+ `ownershipModes` must reflect what the provider advertises rather than the
+ `method()` helper's `["customer", "dcr"]` default.
+
+- oauthStrategy and connectorProfile: not used. This is not a Paperclip-managed
+ OAuth provider.
+- capabilityProfile and variants: not needed.
+- tenantFields and extensionFields: none. There is no tenant identifier to
+ supply — the credential determines the organization.
+- credentialSources: none. Not Vercel Connect eligible.
+- configRequirements: none.
+- guidanceMd, warnings, consoleLinks: see the generated definition at
+ `packages/shared/src/app-definitions/enterpret.json`.
+- riskTier: S3. Enterpret exposes broad content access — an organization's
+ complete customer feedback corpus including verbatim quotes with speaker
+ attribution. It is not S4: no payments, external sends, refunds, production
+ deployment, deletion, or tenant-wide administration is documented.
+- requiredResourceFilters: none, for the reason in
+ [Resource Filters](#resource-filters).
+- urlPatterns: `["https://wisdom-api.enterpret.com/*"]`
+- setupPrerequisite: not used; the account requirement is carried in method
+ warnings.
+- redirectConstraints: `https-or-loopback-http` (unprobed).
+- availability: omitted; organization-token and DCR OAuth methods are selectable
+ on this draft branch. Browse visibility is enabled. Release readiness still
+ requires the account-bound QA recorded below; selectable setup does not mean
+ the provider's pending fixes have been verified.
+
+## Actions
+
+**Observed.** An authenticated `tools/list` ran against the live server on
+2026-09-25 and returned **8** tools. Two corrections to the previously
+documented table:
+
+- `execute_cypher_query` is **absent** from the live server. The legacy alias is
+ no longer served, so it cannot be called and does not need a policy.
+- Every one of the 8 tools self-reports `readOnlyHint: true` — **including
+ `run_graph_query`**. Paperclip trusts provider annotations to derive
+ `riskLevel`, so a Cypher-executing tool self-certifies as `read` and lands on
+ Allowed by default. That is the provider's claim, not a verified property, and
+ it is exactly the case where a provider annotation should not be believed.
+
+**Read the two status columns as the configuration used for the live validation
+run.** Shipping defaults now classify `run_graph_query` as **write** (despite
+the provider `readOnlyHint`) and put write/destructive actions on **Ask first**
+via `recommendedDefaultsForApp` for Enterpret. Other observed tools remain
+Allowed reads. The live-run `deny` below was applied by hand and is stronger
+than Ask first; operators who want Off can still set that after connect. See
+[Governance Defaults](#governance-defaults).
+
+| Tool | Risk | Status in validation | Filters | Approval in validation | Audit fields | Negative case |
+| --- | --- | --- | --- | --- | --- | --- |
+| `get_organization_details` | read | active | credential org | allow | actor, run, connection, tool, outcome | ungranted actor is denied before dispatch |
+| `get_graph_schema` | read | active | credential org | allow | same | same |
+| `get_query_examples` | read | active | credential org | allow | same | same |
+| `search_graph_fields` | read | active | credential org | allow | same | same |
+| `search_graph_values` | read | active | credential org | allow | same | same |
+| `run_graph_query` | **write** (Paperclip override) | **deny — set by hand; ships Ask first** | credential org | deny (set by hand) | same, plus redacted query shape | same |
+| `find_user_quote` | read | active | credential org | allow | same, plus quote redaction | same |
+
+Legacy aliases `get_schema` and `search_knowledge_graph` remain served for the
+lifetime of an existing session and are dropped when the host refreshes its tool
+list. `execute_cypher_query` is no longer served at all.
+
+`run_graph_query` currently retains Paperclip's conservative **write** risk
+classification and Ask first default because it accepts general Cypher. This
+is a Paperclip policy safeguard, not evidence that Enterpret permits mutations.
+Vivek's read-only clarification applies to this official MCP. A scope name or
+tool name does not establish write access. A later risk-policy change can cite
+Enterpret's server-side read-only contract and safe live query proof.
+
+Denial was verified on the live connection: a granted agent calling
+`run_graph_query` through the gateway got **HTTP 403 `deny_default`**, and the
+tool was absent from that agent's own `tools/list`.
+
+Evidence plan: `find_user_quote` returns verbatim customer text with speaker
+attribution, and `run_graph_query` can return feedback records. Do not put
+those results in screenshots, exported evidence, or PR text. Paperclip currently
+retains provider responses close to verbatim in its invocation log, so a quote
+tool call can persist feedback there. Limit access and retention accordingly;
+the token-path QA uses only `get_organization_details` and records tool name,
+decision, and outcome without copying the payload.
+
+## Wizard Path
+
+- User path (auth token, primary): gallery card → paste the token from
+ **Settings → Enterpret MCP** → access defaults.
+- User path (OAuth): gallery card → **Sign in with Enterpret** → browser
+ authorization using instance-local DCR → access defaults.
+- Configuration steps: none beyond credentials. There is no tenant field to
+ fill.
+- Error states: expired auth token (check the dashboard expiry); an account with no
+ access to the organization's feedback. A scope *rejection* turned out not to
+ be one of them — Enterpret accepts the `mcp:read` request and reports broader scopes
+ (see [Scope decision](#scope-decision)), so the flow completes and the failure
+ is silent rather than visible in the wizard.
+- Also observed on the live run, and not an Enterpret problem: a headless agent
+ hits HTTP 409 `user_authorization_required` on this connection's `per_user`
+ credential policy until the user grant is delegated to that agent.
+- Redacted metadata shown: endpoint origin and path, method key, resolved
+ Enterpret organization from `get_organization_details`, tool names and count.
+ Never the token, the authorization code, or feedback content.
+
+## Governance Defaults
+
+- Default profile: Enterpret-specific `recommendedDefaultsForApp` — read
+ actions Allowed; write and destructive actions (including `run_graph_query`)
+ start as **Ask first**.
+- Profile bindings: standard.
+- Policies: `classifyRisk(..., "enterpret")` forces `run_graph_query` to
+ **write** even when the provider advertises `readOnlyHint: true`. Combined
+ with Ask-first defaults, new connections no longer ship that Cypher tool as
+ Allowed. Operators who want **Off** can still set that after connect.
+- **Narrowing an install is not a containment control.** The gallery connect
+ flow creates both a company install and a company-level binding of the
+ `app:` profile. Restricting the install to named agents rewrites
+ the install and adds an agent binding but leaves the company binding in place,
+ which keeps authorizing every agent in the company. Installs gate runtime
+ materialization; the *profile binding* is what authorizes. Containment becomes
+ real only when the company binding is also removed. Verified on the live
+ connection: both agents still resolved 7 allowed tools after the install was
+ narrowed, and the ungranted control agent dropped to 0 of 8 only after the
+ company binding was unbound.
+- Quarantine rules: `quarantineNewEntries` is connection-level runtime setup,
+ not an `AppDefinition` field. Paperclip enables it for Enterpret connections.
+ Enterpret's catalog demonstrably drifts — it renamed three tools and kept the
+ old names as session-scoped aliases, and `execute_cypher_query` has since
+ disappeared entirely — so newly advertised tools are held for review on a
+ subsequent catalog refresh, including after token replacement. The earlier
+ live run found the old default was
+ `false`; the new default still needs live refresh validation.
+- Rate limits: none set.
+
+## Validation Hook
+
+### Organization auth-token QA (2026-09-30)
+
+This was a separate **self-hosted, same-machine** run on an isolated worktree,
+database, and Paperclip instance at App commit
+`dbe63eaae16fdb2f5386b324067e482f84f7fc7a`. The account holder generated
+one QA-only organization token in Enterpret's MCP settings. Its dashboard
+showed **Expires in 3 months**, so setup copy must not promise six months.
+The token value, feedback content, and full provider responses are excluded
+from this record.
+
+| Check | Observed result |
+| --- | --- |
+| Connect and discover | `mcp-api-key` connected as an organization grant; health was `ok`; authenticated catalog refresh found 8 tools. |
+| Safe allowed read | `get_organization_details` returned success for the intended Enterpret organization. The same bounded read succeeded again after reconnect. No quote or graph-query tool was invoked. |
+| Agent policy preview | The selected test agent's access summary changed the read action to `off` and back to `allowed` when its profile was toggled. The Test panel showed “No call will be made” while Off. |
+| Refresh and reconnect | Catalog refresh retained 8 actions. Reconnecting with the same valid token preserved the connection and catalog quarantine setting. An intentionally invalid replacement failed, then reconnecting with the valid token restored `active`/`ok`. This is **not** evidence that an expired token was renewed or that rotating a token revokes its predecessor. |
+| Activity | The safe call produced an explicit-grant decision and completed-call event. Connection activity remained queryable. |
+| Local disable and removal | Disabling the QA connection exposed zero actions in the agent access summary. Archiving it cleared the local secret, grant, install, and catalog entries. |
+| Provider-side revocation | After the Enterpret dashboard said the QA token was revoked, the same token immediately connected again and completed the same bounded organization read. Immediate provider-side invalidation **failed**. Vivek later explained invalidated tokens remain cached for 24 hours and committed to reducing the window. The new delay and deployment are unverified. Both QA connections were removed. |
+| Actual agent execution | Not exercised on this token path. An earlier OAuth QA run proved agent-session denies through the real gateway, but it does not substitute for a token-path agent process. |
+
+The board's `POST /tool-connections/:id/test-calls` is **not** an agent-policy
+denial probe. With the agent's action Off, that endpoint still returned
+`allowed` and invoked the safe provider read because it evaluates the board
+user's policy. The agent access summary and Test panel correctly showed Off.
+This mismatch is a shared Test endpoint issue, already noted in the OAuth QA
+below; do not cite the test call as proof of an agent deny. The QA profile was
+restored to Allowed. No customer-feedback content was requested.
+
+This run did not exercise a real agent process, a self-hosted VPS, or Cloud.
+Those remain separate verification steps before claiming those deployment
+shapes.
+
+### Earlier OAuth QA (2026-09-25)
+
+- Environment: an **isolated, issue-owned Paperclip runtime** on the maintainer
+ host — its own `PAPERCLIP_HOME`, its own embedded Postgres, its own ports,
+ reachable tailnet-only over HTTPS. It shared nothing with any other instance:
+ no database, no credentials, no ports, no worktree. Torn down after the run.
+- Deployment shape: **self-hosted, same machine.** Self-hosted VPS and Cloud
+ remain untested, and nothing below is inferred for them.
+- Method keys exercised: `mcp-oauth`. `mcp-api-key` remains untested.
+- Date and tested commit: 2026-09-25, App
+ `ef1606f037a7828a7ba774949e811847c1a1d386`
+- Account: a named Enterpret account holder signed in personally through the
+ isolated UI and consented. Paperclip never saw a password, an OTP or an
+ authorization code, and no token value appears in any artifact.
+- Client registration: dynamic. `registrationSource: "dcr"`, a **public** client
+ (`token_endpoint_auth_method: none`, so there is no client secret). Nothing
+ was pre-registered by hand.
+- Provider metadata: re-read on the day of the test and unchanged from the
+ 2026-09-23 reading, field for field.
+
+Unauthenticated reproduction — these need no account and are safe to re-run:
+
+```sh
+curl -s -i -X POST https://wisdom-api.enterpret.com/server/mcp \
+ -H 'Content-Type: application/json' \
+ -H 'Accept: application/json, text/event-stream' \
+ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}'
+curl -s https://wisdom-api.enterpret.com/server/mcp/.well-known/oauth-protected-resource
+curl -s https://oauth.enterpret.com/.well-known/oauth-authorization-server
+```
+
+Reproducing the scope finding needs a live token. The shape of the check, with
+the token withheld:
+
+```sh
+# RFC 7662. `scope` here is the scope OF THIS TOKEN, which is the only place
+# the scope mismatch is visible: the token is opaque and the token response omitted
+# `scope` entirely.
+curl -s https://oauth.enterpret.com/introspect \
+ -d "token=$ACCESS_TOKEN" -d "client_id=$DCR_CLIENT_ID"
+# -> {"active": true, "scope": "openid email profile mcp:read mcp:write", ...}
+
+# Negative control, same client_id, bogus token. Proves the scope is bound to
+# the token rather than echoed back from the client registration.
+curl -s https://oauth.enterpret.com/introspect \
+ -d "token=not-a-real-token" -d "client_id=$DCR_CLIENT_ID"
+# -> {"active": false, "rejection_reason": "invalid_token"} (no `scope` field)
+```
+
+**Method note for the next connector.** Do not use
+`POST /tool-connections/:id/test-calls` to show that an ungranted agent is
+denied. It accepts an `agentId` and returns a `decision`, so it reads like an
+agent-authorization probe, but it evaluates policy as the **board user**, which
+is full-control by design. During this run it returned `decision: "allowed"` and
+executed a real provider call for an agent that was denied on all 8 tools. Every
+denial row below was instead produced through the real agent path: mint an agent
+API key, open a gateway session, and call with the session token.
+
+### Nine production-validation scenarios
+
+Per deployment, self-hosted first. Cloud has no evidence of any kind and is
+never inferred from a self-hosted result.
+
+| Scenario | Self-hosted, same machine | Self-hosted, server/VPS | Cloud |
+| --- | --- | --- | --- |
+| Setup and consent | **pass** — account holder signed in; connection reached `active`, health `ok` | not run | not run — no Cloud instance |
+| Authentication | **pass** — DCR public client registered against the live provider; token exchange succeeded | not run | not run |
+| Catalog and configuration | **pass** — authenticated `tools/list` returned 8 tools; `execute_cypher_query` absent | not run | not run |
+| Allowed execution | **pass** — `get_organization_details` resolved to the intended organization; one further bounded metadata read also succeeded | not run | not run |
+| Denied execution | **pass** — ungranted agent got HTTP 403 `deny_default` and saw 0 tools; `run_graph_query` stayed 403 for the *granted* agent | not run | not run |
+| Runtime delivery | **not proven** — gateway and policy were exercised by a real agent-authenticated session, but no agent process ever ran; see below | not run | not run |
+| Refresh and recovery | **not run** — refresh deliberately not exercised once the scope mismatch was found | not run | not run |
+| Revoke and reconnect | **cannot pass** — no `revocation_endpoint` exists to call. Local disable verified: the connection was disabled and the gateway decision flips to deny | cannot pass — structural, not deployment-dependent | cannot pass |
+| Activity and secret handling | **pass** — invocations audited with correct decisions and actor attribution; tokens AES-256-GCM at rest with no plaintext in secret storage; API returns `secretId` references only | not run | not run |
+| **Granted scope (OAuth)** | **scope mismatch observed** — reported scopes differed from the request; write capability was not established; fresh OAuth QA pending | fails identically for OAuth — provider-side | fails identically for OAuth |
+
+Self-hosted VPS and Cloud are `not run`, not "probably fine". Nothing in the
+same-machine column is carried across, and nothing here is carried over from the
+PAP-18519 loopback mirror either.
+
+**Why runtime delivery is `not proven`, precisely.** Every allowed and denied
+result above was produced through the real gateway path — an agent-minted
+session, `actor_type: agent` on the invocation row, decided by the real policy
+service. What did **not** happen is an agent *process*. Minting that session
+requires a `heartbeat_runs` row, and the two rows used here were inserted by
+hand for that precondition alone. Both show `started_at` NULL, no pid, no
+transcript and no run events other than the reaper's, and the instance later
+marked them `failed` / `process_lost` — which is the reaper correctly noticing
+there was never a process behind them, not a product defect. So this connector
+is proven to work under Paperclip's *authorization and transport* layer, and is
+untested under an actual agent runtime driving it through a heartbeat. Scenario
+6 needs a genuine woken agent run before it can be called a pass.
+
+Three further findings from the run, recorded because they change how an
+operator should read this connector rather than what it does:
+
+- **`per_user` credential policy blocks unattended agents.** A headless run has
+ no acting user, so a `kind: user` grant yields HTTP 409
+ `user_authorization_required`. The minimal fix is a delegation of that one
+ grant to that one agent — narrower than promoting to an organization grant,
+ and it widens nothing at the provider. The delegation path additionally
+ requires the run's `invocationSource` to be `automation` or `timer`; an
+ `on_demand` run stays 409. Note `credentialPolicy: per_user` is a runtime
+ default here, not something this definition pins.
+- **Tool results are persisted close to verbatim.** `result_summary` on an
+ invocation stores the provider response body with an empty `redactedFields`.
+ It stays in the instance database, but for Enterpret that means a
+ `find_user_quote` result would write customer feedback text into the run log.
+ `find_user_quote` was deliberately **not** called during validation.
+
+### Deployment support matrix
+
+Labels as defined in the connector skills' shared matrix.
+
+| Capability | Self-hosted, same machine | Self-hosted, server/VPS | Cloud |
+| --- | --- | --- | --- |
+| Definition generates, validates and typechecks | `verified` | `verified` | `verified` — the checks are deployment-independent |
+| Official branding passes the artwork checks | `verified` | `verified` | `verified` |
+| Provider metadata discovery resolves (RFC 9728 → 8414) | `verified` against the provider, from this runtime | `verified` — same request, no deployment dependency | `untested` |
+| Paperclip's discovery ladder resolves this shape | `verified` against the live provider | `untested` | `untested` |
+| DCR client registration | `verified` — public client registered at connect time, nothing pre-registered | `untested` | `untested` |
+| OAuth consent and token exchange | `verified` | `untested` | `untested` |
+| Auth-token (header) connection | `verified` — connected, discovered 8 tools, and completed a safe read on 2026-09-30 | `untested` | `untested` |
+| Authenticated `tools/list` | `verified` — 8 tools on OAuth and the organization-token path | `untested` | `untested` |
+| Agent execution through the gateway | `verified` on OAuth — allowed and denied paths through an agent-authenticated session; token path used the board Test panel only | `untested` | `untested` |
+| Execution driven by an actual agent runtime | `untested` — the sessions above were minted against hand-inserted run rows; no agent process ran | `untested` | `untested` |
+| Granted scope matches the requested scope (OAuth) | `scope mismatch observed` — fresh OAuth QA pending; scope names do not establish write capability | `failed` for OAuth — provider-side | `failed` for OAuth — provider-side |
+| Provider-side revocation | OAuth has no advertised `revocation_endpoint`; the organization token's dashboard Revoke control failed an immediate denial check on 2026-09-30 | `untested` | `untested` |
+| Store visibility (token path) | `ready` — organization auth token is primary; both auth methods target the official read-only MCP | `ready` — same definition | `ready` — same definition |
+
+### What must happen before this is store-visible
+
+**Organization auth token path (primary) — release criteria**
+
+Steps 1–3 below are **done** as of 2026-09-25 and are kept for the record. The
+mechanical store-visibility flip for the token path is also done on this branch
+(clear `availability`, remove `"enterpret"` from `APP_STORE_HIDDEN_SLUGS`, set
+`catalogVisible: true`). Remaining follow-ups improve confidence; they are
+**not** blocked on Enterpret fixing OAuth scopes.
+
+1. ~~An authorized Enterpret organization credential, held by a named owner.~~
+ **Done** — a named account holder signed in personally (OAuth path).
+2. ~~An authenticated `tools/list`, to replace the documented tool table with an
+ observed one and to classify `run_graph_query`.~~ **Done** — 8 tools
+ observed. `run_graph_query` is still not classifiable: its only annotation is
+ the provider's own `readOnlyHint: true`, which the live evidence gives no
+ reason to trust. Enterpret states public tools are read-only today; treat
+ that as product guidance, not a substitute for a Paperclip deny policy.
+3. ~~Authorization to attempt DCR against `oauth.enterpret.com`.~~ **Done** —
+ DCR succeeded; a public client, no pre-registration needed.
+4. ~~Catalog visibility for the token path.~~ **Done on this branch** —
+ `availability` cleared, `"enterpret"` removed from `APP_STORE_HIDDEN_SLUGS`,
+ `catalogVisible: true`, tests and Storybook updated so organization auth
+ token is primary. OAuth is now selectable for the official read-only MCP.
+5. **Partly done 2026-09-30:** `mcp-api-key` connected on an isolated
+ self-hosted instance; authenticated catalog, bounded allowed read, refresh,
+ failed replacement and valid reconnect, local disable, removal, and activity
+ passed. Token-path agent-session deny remains untested. The board Test
+ panel's Off preview is not a substitute for that check.
+6. **Partly done:** reconnect with the same valid token and recovery from an
+ invalid replacement passed. Recovery from actual expiry and server/VPS
+ deployment remain untested. The dashboard's revocation confirmation failed
+ the immediate invalidation check; old-token invalidation after rotation was
+ not tested.
+
+**Both auth methods — release validation and provider follow-up**
+
+OAuth is supported for the official read-only MCP. Before calling the new
+revision release-ready:
+
+- Test a fresh OAuth authorization and refresh against the current provider.
+ Record requested and reported scopes without
+ treating scope names as proof of access to the beta Agent MCP.
+- Exercise a safe allowed read and a denied call through a real agent session;
+ the board Test endpoint does not prove agent authorization.
+- Document the current revocation behavior: invalidated tokens can remain
+ active in Enterpret’s cache for up to 24 hours. Local disconnect removes
+ Paperclip’s stored credential and access, but does not immediately invalidate
+ copies elsewhere. The account holder accepted shipping with this known limit.
+- After deployment, follow up on Enterpret’s OAuth fix and reduced revocation
+ window. Confirm the new maximum delay and retest after the provider deploys
+ those fixes. These provider changes are fast follows, not release gates.
+- Keep Enterpret Agent's beta write MCP outside this PR. Adding it later needs
+ separate endpoint, credential-boundary, action-risk, and write QA review.
+
+The connector can ship with current provider behavior once Paperclip’s
+functional QA, CI, and review pass. Keep the PR draft until those checks pass;
+do not block release on the provider’s fast-follow fixes.
diff --git a/doc/connections/MEMORY.md b/doc/connections/MEMORY.md
index f2153e618c0..2b661c3184e 100644
--- a/doc/connections/MEMORY.md
+++ b/doc/connections/MEMORY.md
@@ -8,7 +8,9 @@ rotate credentials without re-enabling the toggle.
Generic custom MCP connections retain their existing behavior.
These are ordinary company-scoped tool connections. There is no separate memory
-page, automatic conversation upload, prompt injection, or background memory sync.
+page, automatic conversation upload, or background memory sync. Reviewed defaults
+use the generic [connection instructions](CONNECTION-INSTRUCTIONS.md) capability
+to explain when to recall and save; operators can edit or disable them.
Agents explicitly invoke the provider's tools through the existing gateway, and
operators manage access and actions on the regular Permissions screen.
@@ -22,7 +24,7 @@ Official documentation and public endpoint discovery checked September 24, 2026.
| [Zep](https://help.getzep.com/memory-mcp-server) | Remote MCP, `https://api.getzep.com/mcp`, OAuth | Configure Memory MCP and the identity provider in Zep first. A project administrator assigns MCP seats and shared graphs. Sign in with the assigned work identity. An ordinary Zep API key is not the credential for this endpoint. |
| [Supermemory](https://supermemory.ai/docs/supermemory-mcp/mcp) | Remote MCP, `https://mcp.supermemory.ai/mcp`, OAuth | Sign in and select the workspace, read/write access, and optional container tags offered by Supermemory. Developer API keys are separate from hosted MCP sign-in. |
| [Cognee](https://docs.cognee.ai/cognee-cloud/connections/cloud-mcp) | Bundled Cloud API bridge, Cloud API key | Copy the tenant API Base URL and key from Cognee Cloud → API Keys. Requires an active Cloud workspace. The bundled bridge works in public deployments without a local MCP runtime host. |
-| [Honcho](https://honcho.dev/docs/v3/guides/integrations/mcp) | Remote MCP, `https://mcp.honcho.dev`, Bearer API key | Create an organization and API key in the Honcho dashboard. Workspace, peer, and session selectors remain explicit provider tool arguments. |
+| [Honcho](https://honcho.dev/docs/v3/guides/integrations/mcp) | Remote MCP, `https://mcp.honcho.dev`, Bearer API key | Create an organization and API key in the Honcho dashboard. Configure the required workspace in Paperclip; it is projected into workspace-scoped tool arguments. Peer and session selectors follow provider/task context. |
Zep and Supermemory use user grants, the existing PKCE OAuth broker, and automatic
client registration/discovery. Zep advertises its authorization server at
diff --git a/doc/connections/NEON.md b/doc/connections/NEON.md
new file mode 100644
index 00000000000..253745f41f5
--- /dev/null
+++ b/doc/connections/NEON.md
@@ -0,0 +1,237 @@
+# Neon
+
+Updated: 2026-10-02. Status: catalog definition reviewed against official
+documentation and live provider metadata; live account qualification
+outstanding.
+
+Neon appears in Apps and uses Paperclip's shared remote-MCP OAuth connection,
+vault, catalog, grants, policies, gateway, and audit trail. It is a resource
+connection, not Paperclip sign-in. No plugin, provider-specific runtime code,
+or database migration is required.
+
+Paperclip connects to Neon's hosted MCP server at `https://mcp.neon.tech/mcp`.
+The connection supports two explicit methods:
+
+- browser OAuth, recommended for Neon accounts; or
+- a Neon API key stored as a Paperclip secret and sent as an
+ `Authorization: Bearer ...` header.
+
+Paperclip does not silently fall back from OAuth to an API key. The selected
+method is saved on the connection and reused for reconnects.
+
+This curated connection is the polished route: it provides branding, optional
+project pinning and read-only controls, field validation, and tailored
+guidance. None of it is *required* to reach Neon's server. Neon can also be
+connected generically from **Connect your own MCP server** by pasting
+`https://mcp.neon.tech/mcp`, with no Paperclip-specific code involved. See
+[Connecting any remote MCP server](./GENERIC-REMOTE-MCP.md).
+
+## Service involvement
+
+Neon hosts both the MCP resource and its OAuth authorization service on the
+same origin. Paperclip discovers the OAuth endpoints, dynamically registers the
+client, stores returned credentials as secret references, and handles the
+callback at `/api/tools/oauth/callback`. No Paperclip-operated vendor relay is
+involved; cloud and self-hosted instances use the same path.
+
+```mermaid
+sequenceDiagram
+ actor A as Administrator
+ participant P as Paperclip
+ participant M as mcp.neon.tech
+
+ A->>P: Choose Sign in with Neon
+ P->>M: GET /.well-known/oauth-protected-resource/mcp
+ M-->>P: Authorization server: https://mcp.neon.tech
+ P->>M: GET /.well-known/oauth-authorization-server
+ M-->>P: authorize, token, register, revoke endpoints; scopes read, write
+ P->>M: POST /api/register (dynamic client registration)
+ M-->>P: Client registration
+ P-->>A: Open browser authorization (scope: read write, PKCE S256)
+ A->>M: Approve access
+ M-->>P: Redirect to /api/tools/oauth/callback
+ P->>M: POST /api/token (authorization code)
+ M-->>P: Access and refresh tokens
+ P->>M: tools/list on /mcp with optional projectId and readonly query
+ M-->>P: Neon tool catalog
+```
+
+The hosted endpoints retrieved on 2026-10-02:
+
+| Purpose | Endpoint |
+| --- | --- |
+| MCP resource (Streamable HTTP) | `https://mcp.neon.tech/mcp` |
+| Protected-resource metadata | `https://mcp.neon.tech/.well-known/oauth-protected-resource/mcp` |
+| Authorization-server metadata | `https://mcp.neon.tech/.well-known/oauth-authorization-server` |
+| Authorize | `https://mcp.neon.tech/api/authorize` |
+| Token | `https://mcp.neon.tech/api/token` |
+| Dynamic client registration | `https://mcp.neon.tech/api/register` |
+| Revoke | `https://mcp.neon.tech/api/revoke` |
+| Paperclip callback | `/api/tools/oauth/callback` |
+
+The authorization server advertises `code` responses, PKCE `S256`,
+`authorization_code` and `refresh_token` grants, `none` client authentication
+for registered public clients, and exactly two scopes: `read` and `write`.
+Paperclip requests both so the connection has the write surface described
+below; the read-only switch narrows the server itself rather than the token.
+Caller widening beyond the reviewed scopes is rejected.
+
+Neon's older SSE endpoint (`https://mcp.neon.tech/sse`) is deprecated and
+returns `410 Gone` on or after 2026-10-01. Paperclip does not offer it.
+
+## Administrator setup
+
+1. In **Apps → Browse**, choose **Neon**.
+2. Explicitly choose **Sign in with Neon** or **Use an API key**.
+3. Continue directly with Neon's defaults. No project ID is required.
+4. Open **Advanced** only when you need to pin the connection to one
+ **project ID** or force **Read-only mode**.
+5. For OAuth, continue through browser consent. For API-key setup, create a
+ key in Neon Console → **Settings → API keys** and paste it into Paperclip.
+ Prefer a project-scoped key, which Neon limits to one project with Editor
+ rights; personal and organization keys reach every project the account can
+ access. Never put the key in connection configuration or a URL.
+6. Review discovered actions on the connection's **Permissions** screen. Every
+ discovered action starts **Allowed**, including writes and destructive
+ actions. Set deletion, branch reset, and compute mutations to **Ask first**
+ where operator review is wanted.
+
+Use a public HTTPS Paperclip origin or a loopback HTTP origin such as
+`http://localhost:3100`. A plain HTTP tailnet hostname is not loopback; use
+HTTPS or change the local canonical origin before connecting.
+
+When configured, Paperclip appends `projectId=` and `readonly=true` as
+query parameters on the server URL, exactly as Neon documents. The same URL is
+used for catalog discovery and tool execution, and a caller cannot override it.
+Neon documents a repeatable `category=` filter as well; Paperclip's
+tenant fields serialize lists as one comma-joined value, so that filter is not
+offered. Use the per-action Off / Ask first / Allowed controls to narrow the
+catalog instead.
+
+## Capabilities and policy
+
+The catalog is discovered live from the actual provider schemas. Neon groups
+its tools into these categories:
+
+| Category | What the tools do | Classification |
+| --- | --- | --- |
+| `docs` | Look up Neon documentation | Read |
+| `schema`, `observability` | Inspect tables and columns, compare schemas, query logs, check availability | Read; may expose application data |
+| `projects`, `branches`, `endpoints` | List, create, describe, delete projects and branches; manage roles, databases and computes | Write or destructive |
+| `snapshots` | Create, restore and schedule snapshots | Write or destructive |
+| `querying` | Execute SQL, apply schema changes, run diagnostics | Write; read-only mode limits SQL to `SELECT` |
+| `neon_auth`, `data_api` | Provision Neon Auth, manage OAuth providers, enable or disable the Data API | Write |
+| `functions`, `storage` | Deploy functions, manage buckets and objects | Write or destructive |
+
+Neon enforces the account, organization, and project permissions behind the
+credential. The optional project pin and read-only switch are enforced by
+Neon's server, not by Paperclip. `requiredResourceFilters: ["project"]` is
+reviewed policy metadata that names the boundary operators should set; it is
+not a local allowlist.
+
+Neon's own guidance: the hosted server grants broad database management
+capabilities, so always review and authorize actions before execution, and
+prefer development or testing projects over production data.
+
+## Vendor
+
+- App key: `neon`
+- App name: Neon
+- Reuse classification: MCP-direct
+- Reason for classification: official hosted Streamable HTTP server with
+ RFC 7591 dynamic registration and documented bearer API keys; common fields
+ represent every documented option Paperclip can serialize.
+- Security tier: S4
+- Plugin needed? No.
+
+## Transport and auth
+
+- Transport: `mcp_remote`
+- Endpoint: `https://mcp.neon.tech/mcp`
+- Auth modes: OAuth (DCR, PKCE) or API key
+- OAuth scopes: `read`, `write` (explicit, reviewed)
+- Key scope: whatever the Neon key carries; Paperclip cannot widen it
+- Credential owner: company or user grant through the standard access screen
+- Secret storage: `company_secrets` refs only
+- Revocation: Neon publishes `/api/revoke`; Paperclip removal revokes the
+ grant and deletes stored secrets
+
+## Resource filters
+
+- Required filters: none on the default path
+- Optional filters: `projectId` (query `projectId`), `readOnly` (query
+ `readonly=true`, omitted when off)
+- Write-enabling filters: none; writes depend on the credential and on
+ read-only mode being off
+- Filters enforced by: Neon's hosted server
+
+## Manifest
+
+- slug: `neon`; name: Neon; categories: `data`
+- branding: `/brands/apps/neon.png` (official touch icon, both themes)
+- docsUrl: `https://neon.com/docs/ai/neon-mcp-server`
+- methods: `mcp-oauth` (Sign in with Neon, `dcr`), `mcp-api-key` (Use an API
+ key, `customer`, `Authorization: Bearer` header)
+- tenantFields: `projectId` (text, advanced, `^[a-z0-9-]+$`, max 64),
+ `readOnly` (checkbox, advanced, default off)
+- riskTier: S4; requiredResourceFilters: `project`
+- urlPatterns: `https://mcp.neon.tech/*`; redirectConstraints:
+ `https-or-loopback-http`
+
+Source of truth: the `neon` block in `scripts/ingest-app-definitions.mjs`, the
+ledger row in `packages/shared/src/self-serve-mcp-research.json`, and the two
+reviews in `doc/connections/tool-method-permission-reviews.json`. Regenerate
+with `pnpm connections:ingest-app-definitions` (or `--definitions-only`
+without the research corpus).
+
+## Wizard path
+
+- User path: Apps → Browse → Neon → method → Access → Connect.
+- Configuration steps: none required; Advanced holds project pin and
+ read-only mode.
+- Error states: discovery or OAuth failures stay inline on Connect with a
+ retry of the same saved connection; an invalid project ID is rejected before
+ the provider is contacted.
+- Redacted metadata shown: method, pinned project ID, read-only flag. Tokens
+ and keys are never shown.
+
+## Governance defaults
+
+- Default profile and bindings: the standard connection profile; every
+ discovered action starts Allowed under the current product default.
+- Policies: operators narrow destructive categories to Ask first or Off on the
+ Permissions screen.
+- Quarantine rules: the shared defaults; no Neon-specific exceptions.
+
+## Brand provenance
+
+Neon's own app icon, the black tile with the green logomark, is used because the
+bare logomark from the brand kit is a thin outline that reads weakly at 24–36px
+on the light frame. The file is Neon's official touch icon, copied byte-for-byte
+on 2026-10-02 and used unchanged in both themes (Neon's brand colours are
+black and `#34D59A`).
+
+| File | Source | SHA-256 |
+| --- | --- | --- |
+| `ui/public/brands/apps/neon.png` (180×180) | `https://neon.com/apple-touch-icon.png`, the icon linked from `https://neon.com/` | `a6cf4b0772b06a5a64ccfefbfb8b7a1af56e0876eb10c9052f43c8624f4a0b61` |
+
+The brand kit at `https://neon.com/brand` publishes the bare logomark as SVG
+(light and dark colour variants) but no vector of the tile; the raster official
+icon is preferred over a locally composed SVG so the artwork stays the
+vendor's own.
+
+## Validation hook
+
+- Environment: definition review on 2026-10-02 against `origin/master`;
+ no Neon account was used.
+- Metadata probe: both `.well-known` documents above returned HTTP 200 with the
+ endpoints and scopes recorded here. An unauthenticated `initialize` on
+ `/mcp` returned HTTP 401 with
+ `WWW-Authenticate: Bearer ... resource_metadata="https://mcp.neon.tech/.well-known/oauth-protected-resource/mcp"`.
+- Deterministic tests: manifest shape, store visibility, artwork, reviewed
+ scopes, scope-widening rejection, URL projection of the project pin and
+ read-only flag, and invalid project ID rejection.
+- Connect evidence, catalog evidence, allowed read, governed write,
+ denied case, revoke, audit: not run. Each exposed method still needs the
+ full live lifecycle with a Neon development project before this connection
+ is considered qualified.
diff --git a/doc/connections/README.md b/doc/connections/README.md
index 7e1bfe8f051..8046e3d8e4c 100644
--- a/doc/connections/README.md
+++ b/doc/connections/README.md
@@ -13,8 +13,9 @@ Runtime authentication: [AI Connections](./AI-CONNECTIONS.md).
Long-term memory: [Experimental memory connectors](./MEMORY.md).
Provider notes: [Google Workspace](./GOOGLE-WORKSPACE.md),
-[Gmail](./GMAIL.md), [Asana](./ASANA.md), [PostHog](./POSTHOG.md),
-[AgentMail](./AGENTMAIL.md), and [iMessage Photon](./IMESSAGE-PHOTON.md). Optional credential custody:
+[Gmail](./GMAIL.md), [Asana](./ASANA.md), [PostHog](./POSTHOG.md), [Neon](./NEON.md),
+[AgentMail](./AGENTMAIL.md), [iMessage Photon](./IMESSAGE-PHOTON.md), and
+[Enterpret](./ENTERPRET.md). Optional credential custody:
[Vercel Connect](./VERCEL-CONNECT.md).
Post-read action: classify a new integration request, pick the right Paperclip
diff --git a/doc/connections/tool-method-permission-reviews.json b/doc/connections/tool-method-permission-reviews.json
index 2ef0bc115fc..9d6f6cae72b 100644
--- a/doc/connections/tool-method-permission-reviews.json
+++ b/doc/connections/tool-method-permission-reviews.json
@@ -422,6 +422,41 @@
"liveProof": "not-run",
"evidenceLimit": "Provider documentation was unavailable or not readable during this review; metadata/registered source only. Account-bound proof remains outstanding."
},
+ {
+ "app": "enterpret",
+ "method": "mcp-api-key",
+ "auth": "api_key",
+ "policy": "provider-key",
+ "requestedScopes": [],
+ "capability": "read",
+ "supportedActions": "Query the organization's customer feedback and retrieve cited quotes. The current MCP tool catalog has no write actions.",
+ "evidence": [
+ "https://helpcenter.enterpret.com/en/articles/12665166-enterpret-mcp-server",
+ "https://github.com/paperclipai/paperclip/pull/13906"
+ ],
+ "reviewedAt": "2026-09-30",
+ "liveProof": "token-connect-safe-read-refresh-reconnect-verified",
+ "evidenceLimit": "Isolated self-hosted same-machine QA on 2026-09-30. Dashboard revocation did not immediately invalidate the token: it reconnected and completed a safe read. Token-path agent-session deny, real agent process, expiry recovery, VPS, and Cloud remain untested.",
+ "keyPermissions": "An organization auth token can read that organization's customer feedback. Use a token from Settings > Enterpret MCP and check its displayed expiry there."
+ },
+ {
+ "app": "enterpret",
+ "method": "mcp-oauth",
+ "auth": "oauth",
+ "policy": "explicit",
+ "requestedScopes": [
+ "mcp:read"
+ ],
+ "capability": "read",
+ "supportedActions": "Query the organization's customer feedback and retrieve cited quotes. OAuth targets the same official read-only MCP; the separate beta Enterpret Agent write MCP is out of scope.",
+ "evidence": [
+ "https://helpcenter.enterpret.com/en/articles/12665166-enterpret-mcp-server",
+ "https://github.com/paperclipai/paperclip/pull/13906"
+ ],
+ "reviewedAt": "2026-09-30",
+ "liveProof": "tool-list-verified-scope-mismatch",
+ "evidenceLimit": "On 2026-10-01 the account holder reported Vivek confirmed the official MCP is read-only and the Agent write MCP is separate. OAuth scope-reporting and token-revocation cache fixes are committed as fast follows after connector deployment; they are not release prerequisites. Fresh authorization/refresh remain unverified. Scope names alone do not establish write access."
+ },
{
"app": "executor",
"method": "mcp",
@@ -1105,8 +1140,7 @@
"https://honcho.dev/docs/v3/guides/integrations/mcp"
],
"reviewedAt": "2026-09-30",
- "liveProof": "not-run",
- "keyPermissions": "Create peers/sessions and save memory under the API key project. Create a key with read and write permissions for these actions; Paperclip cannot increase an existing key\u2019s permissions."
+ "liveProof": "not-run"
},
{
"app": "hugging-face",
@@ -1368,6 +1402,42 @@
"reviewedAt": "2026-09-30",
"liveProof": "not-run"
},
+ {
+ "app": "neon",
+ "method": "mcp-oauth",
+ "auth": "oauth",
+ "policy": "explicit",
+ "requestedScopes": [
+ "read",
+ "write"
+ ],
+ "capability": "write",
+ "supportedActions": "Create, describe and delete projects and branches; manage computes, roles, databases and snapshots; run SQL and apply schema changes; configure Neon Auth and the Data API; read logs. Optional project pinning and read-only mode narrow the hosted server.",
+ "evidence": [
+ "https://neon.com/docs/ai/neon-mcp-server",
+ "https://mcp.neon.tech/.well-known/oauth-protected-resource/mcp",
+ "https://mcp.neon.tech/.well-known/oauth-authorization-server"
+ ],
+ "reviewedAt": "2026-10-02",
+ "liveProof": "not-run"
+ },
+ {
+ "app": "neon",
+ "method": "mcp-api-key",
+ "auth": "api_key",
+ "policy": "provider-key",
+ "requestedScopes": [],
+ "capability": "provider-controlled",
+ "supportedActions": "Create, describe and delete projects and branches; manage computes, roles, databases and snapshots; run SQL and apply schema changes; configure Neon Auth and the Data API; read logs. Optional project pinning and read-only mode narrow the hosted server.",
+ "evidence": [
+ "https://neon.com/docs/ai/neon-mcp-server",
+ "https://neon.com/docs/manage/api-keys",
+ "https://mcp.neon.tech/.well-known/oauth-protected-resource/mcp"
+ ],
+ "reviewedAt": "2026-10-02",
+ "liveProof": "not-run",
+ "keyPermissions": "Project, branch, compute, snapshot, SQL and schema changes within the key\u2019s reach. A project-scoped key limits access to one project with Editor rights; personal and organization keys reach every project they can access. Paperclip cannot increase an existing key\u2019s permissions."
+ },
{
"app": "notion",
"method": "mcp-oauth",
diff --git a/doc/evals.md b/doc/evals.md
index 35459ea207b..a242d214731 100644
--- a/doc/evals.md
+++ b/doc/evals.md
@@ -1,8 +1,20 @@
# Paperclip evaluation guide
+The explicit-only [live provider connection suite](../tests/runner-e2e/PROVIDER-CONNECTIONS.md)
+is a Product E2E workflow for fresh subscription/API-key/gateway connections,
+with attended login and independent artifact checks against local or staging targets.
+
Paperclip has two live eval families with different questions, owners, and
evidence. Choose the family before selecting a model, profile, or case.
+The explicit-only [native instruction consolidation comparison](plans/2026-10-03-native-completion-consolidation.md)
+uses six Product E2E cells per source variant. It measures the completion
+constraint reduction separately from the earlier native tool-description
+trial. Provider-free start/resume payload capture is a byte measurement;
+behavioral qualification requires the original paired live outcomes and
+retained content. Neither source admission nor a scripted pass proves model
+behavior.
+
- **Runner Evals:** real Runner/provider behavior against a seeded mock control
plane. Definitions live in `paperclip-evals/evals/paperclip-runner`; see the
[direct live protocol evals](../packages/paperclip-runner/docs/runner-protocol-live-evals.md).
@@ -77,6 +89,17 @@ Daytona paths. Its [fixture contract](../tests/runner-e2e/README.md) distinguish
startup cancellation from active response cancellation and HTTP send replay
from ambiguous provider action recovery. Select it explicitly; `--all` excludes it.
+The explicit-only [production hiring templates suite](../tests/runner-e2e/README.md#production-hiring-templates)
+adds two local native Codex/Claude cells. It exercises API-created production
+CEO defaults, an explicitly requested hiring skill/reference read, a permanent
+coder hire, independently computed saved JSON fixtures and worker reuse.
+Each cell requires five work turns and admits at most two strictly attributed
+server task-completion turns. Every actual run remains counted; unknown or
+extra-work turns fail. Source/read coverage and workflow outcome are
+separate: missing read provenance leaves the candidate/baseline pair
+uncomparable even if work succeeds. Baseline bundles and coder examples derive
+from their own source revision, without requiring candidate wording or length.
+
The explicit-only `context-integrity` Product E2E suite covers ordered public
comment continuation and explicit invocation of an assigned pinned skill across
the seven selected legacy/native local profiles. Select it by suite or exact
@@ -84,6 +107,14 @@ execution ID because `--all` excludes explicit-only suites. Each cell applies a
1,000-cent company and agent budget hard stop before task creation and records
both limits in its evidence.
+The explicit-only [stock-harness suite](../tests/runner-e2e/STOCK-HARNESS.md)
+reuses skill, ordered-continuation, and chat-restart journeys across eight local
+legacy/native profiles with production-default hires. It closes the custom QA
+manual coverage gap. Its required credential-free prerequisite maps vendor
+instruction layering, the tiny hire bundle, and shared startup/resume reductions
+to executable checks. The 24 live cells are configured; no live qualification is
+claimed from their setup or unit calibration.
+
The explicit-only `agent-chat-stories` suite covers the experimental settings
lifecycle for a configured native agent and follow-ups during active work. Its
fixture-driven file wait and persisted-plan oracle are documented in the
@@ -384,3 +415,7 @@ The explicit-only Product E2E `confirmation-replies` suite tests conversational
approval and rejection, persisted message provenance, approval before execution,
ambiguous proposals, and the existing card-click path with native Claude/Codex.
See the [suite contract](../tests/runner-e2e/README.md#conversational-confirmation-replies-explicit-only).
+
+Hiring notification accounting now also requires exact completed action attribution. Missing native/provider ID mapping is uncomparable evidence; it must not be reported as a model task regression or waived through name/order matching. The fixture waits for both known completion callbacks and settled bracketed observations, including the gap before pending outbox work becomes a wake. Strict action replay and original machine verdicts are retained separately.
+
+The explicit-only [planning guidance utility comparison](../tests/runner-e2e/PLAN-TASK-GUIDANCE.md) measures task decomposition and handoffs with current, short, and disabled skills.
diff --git a/doc/execution-semantics.md b/doc/execution-semantics.md
index e6bd5fcf92b..6377a142b8a 100644
--- a/doc/execution-semantics.md
+++ b/doc/execution-semantics.md
@@ -452,6 +452,45 @@ Workspace incoherence feeds into the same non-terminal liveness and stranded ass
For runtime-created `git_worktree` execution workspaces, branch coherence is part of workspace coherence. The persisted execution workspace branch is the recorded branch for future dispatch. Reusing that workspace must verify that the worktree is still registered and that `HEAD` is on the recorded branch. Successful run finalization must perform the same check before recording `workspace_finalize=succeeded`. If the run switched to a publishing/PR branch without updating the execution workspace record, finalization may auto-restore the recorded branch only when the worktree is clean, still registered, and the recorded branch points at the current `HEAD`; the repair is recorded as a workspace operation before the successful finalize row. If that safe repair cannot be proven, finalization records a failed workspace finalize and the run fails with bounded evidence for the expected and actual branch. A branch change is sanctioned when a control-plane path updates the execution workspace record before finalization, when publishing work happens in a separate worktree and the managed issue worktree remains on its recorded branch, or when the finalizer performs this clean same-commit restoration.
+Sandbox Git restore uses the host branch and commit captured before staging.
+If that identity is unchanged, a rebased or amended sandbox history with shared
+ancestry replaces the starting tip instead of being merged with it. The ref
+update checks the expected old commit; a concurrent change retries through the
+normal history integration path. Git holds the HEAD and applicable branch locks
+while restore verifies the attached/detached branch identity and commits the ref
+transaction. A checkout during integration cannot redirect that write.
+The directory merge still preserves host-only
+file changes under its existing rules. A changed host branch requires recovery.
+An intentional reset to an ancestor exports a full Git bundle so restore keeps
+the actual sandbox tip; an empty delta is reserved for an unchanged tip.
+Unrelated sandbox history keeps the existing history-preserving graft only when
+the recorded host has not advanced; it must not replace concurrent host work.
+Warm sandbox reuse must match the current host Git tip and branch as well as the
+file snapshot and saved stamp, including managed nested repositories. A history
+or branch mismatch restages the host before the next run begins.
+
+### Native provider model capacity
+
+A committed Codex `turn.failed` event with `codexErrorInfo: serverOverloaded`,
+bound to the failed terminal turn and pinned execution identity, surfaces
+“Selected model is at capacity. Please try a different model.” directly.
+Paperclip preserves the accepted result and task history, then atomically records
+a durable automatic retry with its status decision. The first retry waits one
+minute; the second waits two minutes. Both spend the existing failure-retry
+budget. Exhaustion requires an explicit retry or a model change.
+
+Retries use a fresh provider session and the normal task context, without an
+automatic model switch. Consumed wake input and continuation receipts stay on
+the failed run; `retryOfRunId` supplies task history without lending the new run
+its predecessor's resume authority. Finalization replay and restart reuse the
+same successor.
+Scheduling preserves pending review authority and respects task holds; promotion,
+claim, and dispatch recheck ownership, dependencies, governance, pause, budget,
+and execution locks. Claim also waits for the predecessor's provider execution,
+workspace finalization, and environment cleanup to settle. Model incompatibility,
+usage-limit exhaustion, unknown failures, and unbound diagnostic text do not
+qualify as capacity failures.
+
### Workspace scan failures before provider startup
Repository discovery distinguishes an ordinary folder from a failed Git read.
@@ -484,9 +523,15 @@ An explicit recovery action is a typed liveness repair path for a source issue.
A terminal native failure can retain a result accepted before checkpoint or cleanup failed. That result is historical evidence, not a live controller. New user input may start a fresh turn after the controller and execution environment have stopped and ordinary admission checks pass. Preserve the failed run, its result, and its recovery budget. Do not commit the old result, infer action outcomes, or replay the failed turn. A message saved while cleanup is pending must be reconsidered after verified cleanup and delivered once. Admission must consume its deferred receipt in the same transaction that creates the new run, including in agent chat, where later messages keep their separate turns. Completing that run must not promote the consumed receipt again. Workspace-export repair retains its separate saved-result recovery path.
+When a legacy turn admitted by an explicit user message fails or times out, a bounded transient retry needs its own durable continuation authorization. Initial admission binds the message's exact body digest and revision. Scheduling requires that original binding and revalidates the human author, source task, assignee, and execution ownership, then records the successor's receipt in the same transaction as its run. Historical receipts without a message binding cannot authorize automatic retries and are not backfilled. The parent receipt remains intact. Dispatch checks the exact successor, retry parent, and unchanged message binding again. Deleted or edited input, changed actors or ownership, superseded work, and duplicate successors cannot renew authority. One-run Retry and Interrupt intents retain their separate admission contracts; they are not renewable user-message authority. Other retry policies cannot borrow this receipt: their scheduling fails closed. Successful explicit turns do not create a prose-only missing-comment follow-up with spent authority.
+
+Explicit retry admission checks the local parent adapter controller and verified environment cleanup. The existing queue-first release policy may retain only its own terminal execution claim while that cleanup is pending; finalization and the periodic stale-lock sweep reconsider the same policy after cleanup. Generic terminal-lock cleanup and stale checkout adoption leave these claims for that settlement. New user input, reassignment, and a successor's claim take precedence. Exhausted retries and revoked or missing authorization release the terminal claim without requesting another retry. Pending or failed environment cleanup cannot mint a successor receipt.
+
A new user message can continue a terminal native run whose process fields were cleared before local stop receipts existed. Admission must verify the exact run, runner, workspace, and provider session in the retained suspended state, with no active provider turn, pending tool call, or undelivered output. Missing or mismatched state keeps the hold. A later recorded process launch also keeps the hold until its stop is verified. Normal assignment, decision, controller, environment cleanup, and active-run gates still apply. The message starts one fresh conversation turn; it does not replay the failed run, reset its recovery budget, or certify unknown action outcomes.
-The task thread exposes the existing guarded Retry action for failed or timed-out legacy conversation runs. Where the server supports an explicit new attempt after a stopped legacy conversation, the thread must not hide that action solely because the old run still has a recovery-needed projection. Native and process recovery holds, pending decisions, active execution, and other retry gates remain in force. When a gate hides Retry, the thread says the message is preserved instead of promising an unavailable action. This presentation change does not rewrite historical outcomes or certify prior actions.
+The task thread exposes the guarded Retry action for failed or timed-out conversation runs and native preparation cancelled before provider startup when the never-started proof is verified. The server projects this eligibility on the recovery notice and rechecks it on Retry. Cleanup quarantine retains its inspection path, and non-conversation reconciliation gates remain enforced. Pending decisions, active execution, pause, budget, dependency, and ownership gates remain in force. A refused Retry reports its reason inline and remains available for another attempt.
+
+A continuation cancelled by the queued-run gate while waiting for review did not start a provider. Its matching dispatch-gate receipt and unclaimed execution fields keep this deliberate wait out of unknown-action reconciliation. Pending review and decision gates still apply. If an older server already created a recovery hold for this exact state, Retry or a new user message can request one fresh turn after the server verifies there is no provider, coordinator, or unfinished cleanup. Saved user input is reconsidered through the same admission path; the cancelled turn is not replayed.
A valid recovery action must name:
@@ -666,6 +711,8 @@ The same bounded rule applies when the previous heartbeat reported waiting on a
A continuation that the staleness gate cancelled with `issue_continuation_waiting_on_review` is a *deliberate park*, not a disappeared execution path. The latest run reported that the issue is waiting for review/approval (for example, an umbrella issue whose work was just decomposed into sub-tasks). Treating that park as a stranded run would retry it, then escalate it to `blocked` with a recovery action and an operator-facing failure notice — even though nothing failed and there is nothing for a human to do.
+Execution admission reads a narrow server-owned cancellation-evidence projection. Ordinary run presentation can redact `resultJson` for database encoding or output size; that presentation projection must not decide Retry eligibility or saved-input recovery. The admission projection excludes provider diagnostics and preserves whether the stored result is absent.
+
Recovery rule for a parked-for-review continuation:
- if the issue has a real waiting target — open (non-terminal) sub-tasks or existing unresolved blockers — Paperclip converts the deliberate wait into a first-class dependency wait: it sets the issue `blocked` by those issues, keeps the original assignee, and posts a plain-language comment explaining that the task will resume automatically when its dependencies finish. The issue then self-resumes through the normal `issue_blockers_resolved` path; no recovery action or escalation owner is involved
@@ -841,7 +888,7 @@ An active run can still be unhealthy even when its process is `running`. Papercl
The recovery service owns this contract:
-- classify active-run output silence as `ok`, `suspicious`, `critical`, `snoozed`, or `not_applicable`
+- classify active-run output silence as `ok`, `suspicious` after five minutes, `critical` after fifteen minutes, `snoozed`, or `not_applicable`; measure silence from the latest output, falling back to the run start when no output exists
- honor active snooze and continue decisions on the run
- permanently suppress the signal for a run after a `dismissed_false_positive` decision
- build the `outputSilence` summary shown by live-run and active-run API responses
@@ -975,6 +1022,19 @@ recording the proof and successor lineage. Retained provider files are not edite
Bootstrap retries, exact-checkpoint resumes, and fresh replacement sessions share three total provider attempts, including the original attempt. Linked run IDs, controller restarts, and duplicate wakes do not reset this budget. Automatic attempts retain the 30-second delay. Replacement scheduling and predecessor lineage commit together, with one successor per predecessor and admission through the normal task locks, authorization, pause, approval, and budget gates.
+An exact local Codex restart can restore the conversation after losing its active
+turn. Runnerd records this as `provider_turn_lost_on_restore`, with no invented
+task result. The admitted restart attempt may send one continuation in that same
+conversation. It preserves the workspace and asks the agent to reconcile unfinished
+commands and external actions before proceeding. It does not resend the task or
+tool calls. An outcome that cannot be reconciled remains a blocker. The continuation
+uses the existing durable one-shot recovery marker; recovery adopts an accepted
+turn if the controller dies before checkpointing its ID. The interrupted terminal
+is checkpointed before submission. Real provider failures, accepted semantic
+results, intentional stops, and historical unmarked failures keep their existing
+terminal behavior. This continuation uses the already charged restart attempt and
+does not reset the provider-attempt budget.
+
Provider execution and control-plane finalization have different clocks. A healthy provider can think or execute a long tool without output. Once execution settles, recovery and finalization control steps have a 60-second deadline, checked on startup and every 15 seconds. With a healthy database and scheduler, an abandoned transition must be repaired or surfaced within 90 seconds. Terminal persistence must not wait on provider cleanup or publication; a late finalizer cannot change a reassigned or closed task or release another run's locks. Historical ambiguous runs are never automatically replayed after an upgrade.
Every continuation carries the triggering request, ordered user direction, interaction outcomes, completed work, and explicit history coverage. A delivered message remains part of the task's request after its connection or approval resolves. The original title is background; a completed Notion read does not satisfy a later Gmail request. Author and source-trust boundaries survive rendering into both native and legacy prompts. Missing required history must be fetched before dispatch rather than described as complete.
@@ -1003,7 +1063,7 @@ For native conversations, an authenticated user message sent after the previous
Local recovery records a server-authored stop receipt before it clears a verified absent process identity. A new execution request invalidates that receipt before any process can spawn; recording a new process identity also invalidates it. Missing process IDs without a receipt still block admission. Remote execution continues to require termination receipts for every lease.
-If cleanup or another execution gate is still pending, the message stays in its existing queue receipt. Startup and periodic scheduling reconsider up to 50 due receipts per pass, at most once per 30 seconds per receipt, without calling a model or resetting recovery attempts. Cleanup callbacks use the same admission path. The issue lock prevents concurrent workers from delivering an adopted or discarded receipt again. The queued-message area shows the current wait reason. Pauses, approvals, budgets, ownership, and external chat authorization remain enforced. A message sent before the run finished does not grant new post-stop authority.
+If cleanup or another execution gate is still pending, the message stays in its existing queue receipt. Startup and periodic scheduling reconsider up to 50 due receipts per pass, at most once per 30 seconds per receipt, without calling a model or resetting recovery attempts. Cleanup callbacks use the same admission path. The issue lock prevents concurrent workers from delivering an adopted or discarded receipt again. The queued-message area shows the current wait reason. Pauses, approvals, budgets, ownership, and external chat authorization remain enforced. For a failed native conversation, saved authenticated messages that have never been delivered can request a fresh turn after verified stop even when submitted before the failure finished. Admission validates and adopts their exact queue receipt, order, and original authors. This does not replay the failed request or undo an operator cancellation.
Historical legacy interruption holds for conversational adapters no longer block new messages or Resume. Automatic classification uses the server-owned adapter identity saved atomically at run claim, the saved adapter invocation, or the continuation policy, never the agent’s current adapter settings. Missing historical adapter evidence retains the automatic hold; an explicit user continuation can retire it after proving the predecessor stopped. A terminal row with a live predecessor process, an unreleased environment lease, or failed/pending cleanup still blocks actual admission and Resume; a release timestamp alone does not prove cleanup succeeded. Retry scheduling can happen before cleanup, but grants no execution authority. Recovery folds their obsolete no-replay bookkeeping without changing task ownership, status, or automatically waking old work. The audit trail remains readable. Native integrity and ownership holds, and non-conversational adapter holds, remain enforced.
@@ -1045,7 +1105,7 @@ unknown, and they do not gain automatic replay eligibility.
Admission validates the persisted comment's author, task, and time against every
held predecessor. Retry validates the selected failed run's company, task, and
agent and preserves that run's identity through admission and history loading.
-Duplicate Retry requests adopt the same successor. An agent-authored comment, an old queued request, or a generic
+Duplicate Retry requests adopt the same successor. Only a validated, unconsumed human queue receipt can authorize saved-message continuation after a native failure; arbitrary historical input, an agent-authored comment, or a generic
system wake cannot release a hold. The source task keeps its assignee. Process
ownership, active controllers, cleanup leases, pause, approval, budget, and normal
execution gates still apply. Dependency-blocked interaction mode remains limited
@@ -1156,6 +1216,15 @@ controller, lease, or result). It also checks for contradictory launch/process
evidence and verifies local cleanup or exact remote termination receipts. The
preparer must have finished or its startup lease must have expired. A missing
PID alone does not establish this proof.
+For older interrupted preparation rows without a cancellation receipt, or with
+a retained startup fence but no preparation-settled marker, the
+immutable Paperclip Runner adapter claim, unresolved runtime, and preparing stage
+must agree. The old controller must belong to another server boot and its lease
+must have expired. Only absent results or the retained before-selection
+cancellation fence qualify. No native identity, coordinator, adapter invocation,
+provider event, or process-launch evidence may exist. Environment cleanup still
+requires the same receipts. This historical proof permits explicit Retry or a
+newer saved user message; it does not replay the cancelled input.
The existing bounded saved-message worker rechecks this proof after restart.
Admission atomically settles an unclaimed coordinator and admits one fresh turn,
@@ -1322,8 +1391,22 @@ execution recovery holds still apply. Unconfirmed cleanup does not start work.
The active session advertises steering only when its driver supports it. A
transport method that rejects steering does not grant that capability. The
-queued-message control remains mounted until the server accepts a steer request,
-so a rejected last-row action keeps its message and visible error.
+queued-message controller remains mounted across an empty queue, preserving
+pending delivery and inline errors. Steer immediately moves the selected message
+into the conversation; Interrupt immediately moves all submitted queued messages.
+Stale queue polls do not restore those rows while delivery is pending or accepted.
+Rejected delivery restores the latest queue and shows an inline error without a
+toast. The provider acknowledgement remains the authoritative delivery receipt;
+optimistic display never grants permission or records successful delivery. A preparing
+Paperclip Runner retains the Steer label while steering is unavailable; the
+initial legacy database default and an empty queue snapshot cannot select
+Interrupt. Model and effort changes apply to the next turn and do not change
+the active turn's steering target. While awaiting steering acknowledgement, the
+queue route holds the task and queue locks but leaves the run row available for
+PRP event persistence. It locks and rereads the run after acknowledgement before
+merging the receipt, preserving concurrent provider updates.
+If the run stops during that wait, the request fails with a stale-target error
+and retains the queued input for continuation.
### Preserve work across handoff and deliver requested files
diff --git a/doc/observability.md b/doc/observability.md
index 470d0413ef6..5c1e57c1784 100644
--- a/doc/observability.md
+++ b/doc/observability.md
@@ -443,6 +443,43 @@ values become `unknown`. A signal such as `SIGKILL` does not establish who sent
it or prove an out-of-memory kill. These fields do not change error grouping
or run outcomes, and do not include process output or adapter result payloads.
+For a native Codex turn that ends with a structured HTTP 400 model/ChatGPT
+compatibility rejection, the run records `native_provider_model_rejected`
+and a fixed message that asks the user to select a supported model or connection.
+This requires a committed runner terminal for the selected model and the exact
+failed turn. Agent text, tool output, unrelated turns, and unknown provider
+errors do not create this classification. The provider diagnostic contains only
+`provider=codex`, `category=model_auth_incompatible`, `status=400`, and
+`authMode=chatgpt`. It excludes the model name and provider response. This does
+not change credentials, select a fallback model, replay a turn, or alter the
+accepted semantic result or cleanup. The existing configuration-blocker recovery
+path requires a configuration change instead of automatically retrying the same
+model and connection. Native finalization also derives this evidence from the
+committed event and the run's pinned provider configuration before it can queue
+a failed-result retry. This survives a controller restart before the adapter
+diagnostic is saved. Invalid bindings, missing evidence, or a mismatched event
+hash do not grant this classification. A current worker's task is blocked for a
+configuration change. A pending review instead keeps its original decision and
+status version, releases execution, and creates no automatic recovery action.
+After repairing the configuration, explicitly retry the reviewer to resolve the
+same pending review. The Board's exact failed-run Retry accepts this classified
+native failure only while its saved review is still current and pending; caller
+payloads cannot select a different review. Dispatch checks that assignment again.
+Superseded or completed reviews retain their authority.
+
+Cloud portfolio proxy failures have an event-local `cloud_portfolio` context.
+It contains only the phase (`fetch`, `http_response`, `response_body`, or
+`response_write`), upstream HTTP status when available, elapsed milliseconds,
+and an allowlisted network error code. Unknown values become `unknown` or
+`null`; elapsed time outside 0–60,000 ms becomes `null`. Codes come from at
+most four error/cause objects' own data properties, never error messages.
+`DEADLINE_EXCEEDED` means the request's own ten-second signal was aborted.
+The route's warning uses the same safe fields. Neither record includes URLs,
+headers, cookies, bodies, user/stack IDs, or the original exception. Sentry
+receives a plain error with the existing generic message and default grouping.
+The context does not change the HTTP response, authentication, cookies, cache,
+deadline, or single-fetch behavior, and does not carry into unrelated events.
+
An unconfirmed adapter Stop timeout has an event-local `adapter_stop` context:
the run UUID, built-in adapter type, native/legacy runtime mode, configured
wait duration, and whether abort was requested. Invalid identities become
@@ -453,6 +490,19 @@ termination, remove the live execution control, or change the timeout. The
context is sent only through the existing opt-in Sentry gate and never leaks
into unrelated captures.
+The context also samples the pending execution `phase` and `phaseElapsedMs`
+when the Stop timer expires. An in-memory tracker belongs to the exact live
+execution control; a replaced or missing owner reports `unknown` with a null
+elapsed time. Labels come from a closed list and elapsed time uses a monotonic
+clock, capped at one day. Nested scopes remain visible while their awaits are
+pending, including ACP session close, transport stop, instruction collection,
+workspace restore, and host instruction or lease cleanup. `phase_reporting`
+means a step is waiting to write timing or teardown error diagnostics. `adapter_execution` and
+`host_execution` are coarse labels for work outside those narrower scopes.
+The tracker clears when its executor finishes. A phase is diagnostic context,
+not evidence that a provider stopped or that files were recovered. No new
+run-log or Telemetry event is emitted by this tracker.
+
The shared reporter also attaches bounded diagnostic contexts for both legacy
and native runs:
@@ -475,6 +525,15 @@ pending. Recent events do not prove useful progress. These fields contain only
numbers and a boolean, never tool names, IDs, arguments, or event content, and
do not change the execution timeout, cancellation, or recovery policy.
+ACP results retain the adapter's resolved wall-clock timeout as
+`adapterExecutionTimeout` in the instance run result. Finalization uses it for
+`effectiveTimeoutSec`, `timeoutSource`, and `timeoutConfigured`. Sources are
+`configured`, `sandbox_default`, or `unlimited`; `timeoutConfigured` identifies an
+explicit override, including a negative value that disables the timer. An untouched
+sandbox value of zero reports the four-hour default, while a local zero reports
+unlimited. Older adapters without a valid resolution retain the config-based
+metadata fallback. This does not change timers, Stop acknowledgement, or recovery.
+
When settlement records a workspace restore failure, `run_execution` also
includes `workspaceRestoreFailure` with one of the shared, path-free codes:
`restore_permission_denied`, `restore_lock_timeout`, `restore_unsafe_archive`,
@@ -482,6 +541,33 @@ or `restore_failed`. Unknown values are omitted. Workspace paths and arbitrary
pre-restore result data are not included. A later successful run does not, by
itself, establish that an earlier failed restore recovered the workspace files.
+When available, the saved `workspaceRestoreDiagnostic` adds the bounded fields
+`workspaceRestorePhase`, `workspaceRestoreStep`, `workspaceRestoreErrorCode`,
+`workspaceRestoreHttpStatus`, and `workspaceRestoreExitCode` to `run_execution`.
+The phase is `workspace` or `asset`. The failing step is one of `git_export`,
+`git_import`, `workspace_transfer`, `workspace_extract`, `directory_merge`,
+`git_integration`, `index_reset`, `git_ref_cleanup`, or `asset_restore`.
+Nested steps retain the most specific failing operation. Error codes come from
+the restore diagnostic allowlist, with unrecognized codes reported as `unknown`;
+HTTP statuses are integers from 400 through 599 and process exit codes are
+integers from 1 through 255. These fields accompany a known restore failure code
+only. They omit error messages, raw command lines, paths, process output, and arbitrary
+cause data. Git error wrappers preserve only these safe codes and numbers for
+diagnostics, without adding the original error as a cause.
+For `git_integration`, optional `workspaceRestoreGitCommand` identifies the fixed
+command family: `rev_parse`, `symbolic_ref`, `merge_base`, `merge_tree`,
+`commit_tree`, `update_ref`, or `log`. `workspaceRestoreGitFailureKind` is
+`merge_conflict`, `invalid_object`, `ref_conflict`, `permission_denied`, or
+`unknown`. A merge conflict requires an uninterrupted `merge-tree --write-tree`
+exit of 1 with a completed tree ID in stdout; exit 1 alone is ambiguous.
+Object and ref classifications require recognized Git diagnostics;
+permission denial requires an OS `EACCES` or `EPERM` code. Unrecognized or
+localized messages remain `unknown`. Up to 16 KiB of stderr is inspected only
+in memory; no arguments, stderr, paths, repository URLs, filenames, or ref names
+enter these fields. Handled probes and successful retries emit no diagnostic.
+This does not change
+restore behavior, retries, timeouts, or recovery policy.
+
A caught directory-merge lock timeout also records `restoreLockOwnerState`
(`alive`, `dead`, `unknown`, `missing`, or `invalid`), `restoreLockKnownLocalHolder`,
and, when available, `restoreLockOwnerSameProcess`, `restoreLockOwnerPredatesProcess`,
diff --git a/doc/openai-dot-runner.md b/doc/openai-dot-runner.md
index 3d444fd75c2..30125996db0 100644
--- a/doc/openai-dot-runner.md
+++ b/doc/openai-dot-runner.md
@@ -33,6 +33,18 @@ Only the operator's one-use pairing code is displayed. OAuth tokens and callback
signing secrets stay on the server and never enter the Runner descriptor,
task prompt or saved adapter config. Pairing codes expire after 15 minutes.
+The dedicated connection uses the merged MCP gateway's PKCE browser and device
+flows, including verified client metadata documents and organization hints.
+Its issuer is `/mcp/runner/oauth`; the personal issuer remains ``.
+The shared consent page identifies Dot agent access and requires an operator
+role. Device codes and browser requests stay bound to their original resource
+and organization. The gateway's Connections invitations remain personal
+assistant invitations; use the agent's Dot connection panel for Runner pairing.
+
+Database migration `0311_known_inertia.sql` adds only Dot tables and extensions
+after the merged gateway migrations. It is safe to reapply. The earlier
+prototype migration number is retired; published master migrations are intact.
+
## Assignment protocol
Events contain mailbox references. Dot drains the inbox after its saved cursor,
diff --git a/doc/plans/2026-09-30-paperclip-public-mcp-and-plugins.md b/doc/plans/2026-09-30-paperclip-public-mcp-and-plugins.md
index c351b377f8a..a11926146d5 100644
--- a/doc/plans/2026-09-30-paperclip-public-mcp-and-plugins.md
+++ b/doc/plans/2026-09-30-paperclip-public-mcp-and-plugins.md
@@ -355,7 +355,7 @@ Current local qualification:
exact source fingerprints and costs.
This is a usable opt-in first release for existing teams. Applying Core updates
-adds migrations 0294, 0295 and 0296 plus disabled MCP code. An operator must enable
+adds migrations 0301 through 0305 plus disabled MCP code. An operator must enable
**Settings → Experimental → Assistant connections (MCP)**, configure the public URL, and expose the
authenticated instance over HTTPS. A team member can then connect Codex or Claude
Code directly, consent to a company, review work, delegate tasks as themselves,
diff --git a/doc/plans/2026-10-02-composio-connection-model.md b/doc/plans/2026-10-02-composio-connection-model.md
new file mode 100644
index 00000000000..9fcf37ae5c3
--- /dev/null
+++ b/doc/plans/2026-10-02-composio-connection-model.md
@@ -0,0 +1,164 @@
+# Composio connections and permissions in Paperclip
+
+October 2, 2026 · Current behavior and proposed product model
+
+**Composio should be the source of truth for its app accounts. Paperclip should show those accounts and control who can use the saved Composio connection.** Connecting Circleback in Composio should not require connecting it again in Paperclip when the saved gateway can already reach that account.
+
+The current integration supports direct app authorization and checking known accounts, but discovery is incomplete. Its Circleback cards also look like independent Paperclip connections even though their permissions belong to the entire Composio gateway. This document explains that distinction and proposes a clearer experience. Recommendations below are proposals; this document does not change product behavior.
+
+## What the saved connection actually represents
+
+The default integration uses Composio Connect at `https://connect.composio.dev/mcp`. Composio describes this as one MCP connection that discovers and executes tools across apps through orchestration tools. It is different from an application creating its own Composio SDK session. [Composio Connect documentation](https://docs.composio.dev/docs/composio-connect)
+
+There are three objects to distinguish:
+
+| Object | Meaning |
+| --- | --- |
+| Saved Composio connection in Paperclip | An endpoint, credentials, access rules, and tool catalog. We have called this a gateway. Multiple saved Composio connections are possible. |
+| Connected app account in Composio | A particular authorized Circleback, Spotify, or other app account. |
+| App row in Paperclip | A cached observation of an account available through a saved gateway, plus a convenient setup or management entry point. |
+
+**An observed Circleback row does not create another credential or independent connection in Paperclip.** The public app catalog is another separate thing: it says Composio supports Circleback, without proving that this gateway has an authorized Circleback account.
+
+Composio accounts are scoped. Projects separate resources, and connected accounts belong to an upstream user identity. Dashboard-created accounts use a Composio dashboard user identity, which is different from an application's `user_id`. Matching a person's email or using the same Composio brand is insufficient to establish that two integrations reach the same accounts. [Project isolation](https://docs.composio.dev/reference/api-reference/projects), [Connected account identities](https://docs.composio.dev/reference/api-reference/connected-accounts)
+
+For our existing Connect gateway, the practical question is: **Does listing Circleback through this exact saved credential return the account?** That check is stronger evidence than seeing Circleback somewhere in the Composio dashboard. The current integration has not established a general mapping from Connect OAuth identity to every dashboard project.
+
+## What happens to tools
+
+Paperclip does expose the gateway's tools to permitted agents. It reads the upstream MCP `tools/list`, stores the returned definitions, presents eligible tools through its own runtime, checks policy, and forwards execution to the saved endpoint using server-resolved credentials.
+
+That is a proxy of the upstream tool catalog. It does **not** turn every app in our public catalog into its own set of executable Paperclip tools.
+
+```mermaid
+flowchart LR
+ Agent --> Policy[Paperclip gateway access and tool policy]
+ Policy --> Tools[Composio MCP tools]
+ Tools --> Accounts[Composio authorized app accounts]
+ Accounts --> Circleback[Circleback]
+ Apps[Paperclip Apps page] --> Check[Read account status through saved gateway]
+ Check --> Accounts
+ Check --> Cache[Safe account observations]
+ Cache --> Apps
+```
+
+The live test gateway currently has 11 active Composio catalog entries, including search, schemas, connection management, batch execution, and workbench tools. It does not list a separate Circleback tool set. Circleback execution happens behind those Composio tools. A custom session endpoint could expose a different catalog; the actual upstream definitions determine what Paperclip presents.
+
+Consequently, an account can be available for execution even before the Apps page discovers it. The account snapshot is a display cache, not an execution allowlist.
+
+## What currently works and what is incomplete
+
+These findings come from the current worktree and a read-only check of the local test gateway.
+
+| Capability | Current behavior |
+| --- | --- |
+| Reuse an already connected app | Setup lists the requested toolkit first. An active account skips creating another authorization link. No agent task is necessary. |
+| Authorize an app from Paperclip | The backend requests a hosted Composio authorization link. Completion checks account status again. |
+| Recognize a known account | Safe account IDs, aliases, statuses, default flags, and check times are cached. A fresh check confirmed Circleback is active. |
+| Discover an app connected independently | The Apps page checks its visible catalog toolkits and previously observed or configured toolkits. A previously unseen app can remain undiscovered until its page or search is checked. |
+| Notice external disconnection | Rechecking a known toolkit replaces the observation with the provider's returned account list. Until then, the card can be stale. |
+| Rename or remove an app account | Paperclip calls Composio, then lists accounts again to confirm the change. This changes upstream state. |
+| Give Circleback its own agent permissions | The row's Permissions action opens the saved Composio gateway's permissions. It is not an independent Circleback permission boundary. |
+
+Refresh happens on page entry, changes to the visible catalog query, and browser focus. The one-minute query freshness setting is **not** a background polling schedule. We have no full inventory reconciliation job or lifecycle webhook integration here.
+
+If a provider check fails, we preserve previous observations and show an error. That avoids interpreting a failed request as a disconnection, but the old green check can still look current. The UI should distinguish **last confirmed connected** from **verified now**.
+
+Two additional presentation gaps matter:
+
+- Native connector precedence currently excludes overlapping aggregator cards altogether. A native Notion offer can therefore hide the fact that Notion is already available through Composio. We should suppress duplicate connection offers while still showing real upstream accounts and their source.
+- The aggregator row's “Connected by” identity comes from the saved gateway owner metadata. It does not establish who authorized the app independently in Composio. Preserve the account-row visual style, but use truthful attribution such as **Via “Work Composio”** unless the upstream author is known.
+
+## Who owns which permissions
+
+| Question | Authority |
+| --- | --- |
+| Is this app account authorized and active? | Composio, backed by the app's authorization. |
+| What access did the app's OAuth consent grant? | The app and Composio's authorization configuration. |
+| Can this Paperclip human or agent use the saved gateway credential? | Paperclip's grants and access controls. |
+| Is this exposed MCP tool allowed, denied, or subject to approval? | Paperclip's tool policy. |
+| Can this agent use only Circleback through a broadly enabled Composio executor? | Not established by the Circleback app row or its current Permissions link. |
+
+New gateways now default to all humans and all agents. That makes the gateway available to those actors; it does not override credential requirements, tool policies, or Composio's own account restrictions. App setup preserves the saved gateway's existing rules.
+
+The policy system evaluates the catalog entry being invoked. For example, it sees `COMPOSIO_MULTI_EXECUTE_TOOL`; it does not automatically expand every nested app action into a separate Circleback permission decision. The current integration has no Composio-specific layer that grants or denies downstream toolkit/account operations independently.
+
+An approval for a broad execution tool is therefore an approval for that call and its arguments. It should not be presented as a verified per-app read/write policy. Generic argument rules can constrain particular shapes, but do not by themselves provide comprehensive app isolation across batch execution and workbench paths.
+
+Likewise, an app card's absence, a native app's precedence, or removing a cached observation cannot stop a permitted gateway from reaching an upstream account. A visual catalog choice is not a runtime restriction.
+
+## What connecting or disconnecting elsewhere should mean
+
+The following is the proposed behavior, assuming the account belongs to the identity and scope reachable by the saved gateway.
+
+| Event | Expected Paperclip behavior |
+| --- | --- |
+| Connect Circleback in Composio | Import it into connected apps automatically. No second OAuth flow or local activation step. |
+| Click Connect when Circleback is already active | Verify and show the existing account. Do not create another account. |
+| Disconnect Circleback in Composio | Update the account row after reconciliation. Provider execution follows upstream state even while our card is stale. |
+| App authorization expires | Show Needs sign-in and offer the provider's reauthorization flow. |
+| Composio cannot be reached | Keep the last observation, mark it stale, and show Check again. Do not claim a confirmed disconnection. |
+| Add a second account for the same app | Show both accounts. Do not imply that clicking one pins all later agent calls to it unless execution actually enforces that choice. |
+| Remove Composio from Paperclip | Remove local access to that saved gateway. Keep upstream app accounts in Composio. |
+
+Composio documents automatic OAuth token refresh and an expired-account event. That gives us one potential sync signal, but does not prove that our Connect credential can subscribe to every creation, deletion, or status event. [Authentication lifecycle](https://docs.composio.dev/docs/authentication)
+
+## The experience I recommend
+
+**Keep one saved connection per Composio account or configured endpoint, show its apps as imported accounts, and manage app authorization in Composio.** This matches the underlying system and keeps our interface small.
+
+1. **Connecting Composio imports its available accounts.** Put them above the catalog using the same divider, check, logo, and account-row layout as other connections, with a Composio badge and quoted gateway name. Label this inventory as connected apps, rather than apps separately installed into Paperclip.
+2. **Connect asks which saved Composio account to use, or offers a new one.** Check existing authorization first. If needed, open a provider-generated sign-in link directly and verify the result. No agent picker or task draft.
+3. **An app's Manage action shows its accounts and opens Composio management.** Prefer a toolkit/account-specific URL where supported and verified; otherwise link clearly to Composio. Do not promise a deep link that the provider does not expose.
+4. **Permissions live on the Composio gateway.** From an imported app row, call the action **Composio permissions** and explain once that changes apply to apps accessible through that gateway. Keep native connector permissions independent.
+5. **Manage upstream app removal in Composio for the initial model.** Reserve **Remove connection** in Paperclip for removing the saved gateway locally. If we retain direct upstream removal, name it **Disconnect from Composio** and explicitly say it can affect other clients using that account.
+
+This is a UX recommendation, not a technical inability to remove accounts. Composio Connect supports account creation, listing, renaming, and removal, and our backend already implements those operations. [Connection management capabilities](https://docs.composio.dev/docs/composio-connect)
+
+Removing an account from Composio should also not be described as guaranteed revocation of the target app's OAuth grant. Composio distinguishes removing an account from revoking its authorization at the provider. [Connected account lifecycle](https://docs.composio.dev/reference/api-reference/connected-accounts)
+
+For native overlaps, keep the native Connect offer as requested, but include actual Composio accounts in the connected inventory with their source visible. A Composio account should never silently become a native account.
+
+## How to make discovery complete
+
+The current per-toolkit checks are useful, but cannot support the promise “we automatically import everything you already connected.” Scanning thousands of catalog toolkits is an expensive substitute and can still miss apps absent from our public catalog.
+
+Composio provides a paginated connected-account API with project-key authentication and user/toolkit/status filters. Its SDK also offers paginated session toolkit discovery filtered to connected apps. These are better building blocks for inventory than probing every public catalog entry. [Connected-account API](https://docs.composio.dev/reference/api-reference/connected-accounts/getConnectedAccounts), [Session inventory](https://docs.composio.dev/docs/configuring-sessions)
+
+**The unresolved integration question is whether we can enumerate that same inventory using the identity behind our current Connect OAuth gateway.** We must not assume that credential is a project API key or that a dashboard project's users match it. Listing every account in a project without the correct identity filter would not answer the user's question.
+
+Proposed implementation order:
+
+1. Establish a supported inventory API for the saved credential, including its upstream subject, project/session scope, and shared-account semantics. If Connect cannot provide this, evaluate an explicit project/session integration as a separate setup mode.
+2. Reconcile every inventory page on connection completion and refresh; add bounded background reconciliation and supported event notifications. Events trigger another authoritative read rather than becoming a second source of truth.
+3. Store only safe metadata, scoped to company, gateway, and resolved credential identity. Preserve last-success time and sync errors. Change credentials or upstream identity without carrying over another identity's connected status.
+4. Reconcile removals only after a complete successful listing. Partial pages and failed calls must not delete unseen accounts. Surface unknown custom apps using provider metadata where available.
+
+Until the identity-bound enumeration route is proven, describe the current display as **apps checked through this connection** rather than complete synchronization. The current cache uses a credential-reference fingerprint; that is not proof of the upstream user's identity.
+
+## If we later want independent app permissions
+
+We should decide this separately from inventory. The simpler gateway model is valid, provided the interface is honest about its scope.
+
+Composio SDK sessions can restrict toolkits, tools, and selected connected accounts. A session MCP endpoint can use those restrictions and a direct-tools preset to expose an explicit tool set. That offers a possible route to enforced per-agent scope, but it requires a different integration contract from merely observing accounts behind Connect. [Session configuration](https://docs.composio.dev/docs/configuring-sessions), [Session MCP endpoints](https://docs.composio.dev/docs/sessions-via-mcp)
+
+The other route is a Paperclip executor that validates every downstream tool and account and prevents broader execution paths from bypassing those rules. This is substantial runtime work. Adding a per-app toggle while leaving unrestricted gateway execution available would not establish the promised boundary.
+
+For apps already supported natively, a native connection remains the clearest way to apply that connector's individual access controls.
+
+## Evidence and checks still needed
+
+The local gateway returned 11 active Composio tools, and a fresh read through our app refresh endpoint confirmed an ACTIVE Circleback account. This proves account-status checking for that saved credential. It does not prove all-app enumeration, a successful Circleback business operation, external lifecycle synchronization, or independent Circleback permissions. No real account was disconnected or permission changed for this document.
+
+Before claiming complete sync, demonstrate an app connected independently in the matching Composio scope appearing without searching for it; then externally disconnect a disposable test account and verify both the UI and execution outcome. Also check account isolation, multiple-account selection, provider failures, native overlaps, and gateway removal without upstream account deletion.
+
+Implementation evidence in this worktree:
+
+- `server/src/services/tool-access.ts`: `openComposioGateway`, `setupComposioApp`, `refreshComposioApps`, and `manageComposioAppAccount` implement checks, safe observations, and upstream mutations.
+- `server/src/services/tool-gateway.ts`: `policyInputForAgentTool` and remote MCP execution show the tool-policy boundary and forwarding of catalog tool names and arguments.
+- `server/src/services/tool-access-policy.ts`: catalog entries and saved connections determine the policy context; no automatic downstream Composio app expansion is implemented.
+- `ui/src/pages/apps/Browse.tsx`: native precedence, page-based discovery, connected-account rows, permission links, and owner attribution.
+- `packages/db/src/schema/tool_connection_app_snapshots.ts`: cached account observations, separate from connection grants.
+- `doc/connections/CONNECTOR-PLAYBOOK.md`: the current aggregator catalog and setup behavior.
+
+The recommendation is to adopt the provider-owned account model now, then prove complete discovery before promising it. Independent app permissions can follow if we choose to build and enforce them.
diff --git a/doc/plans/2026-10-02-hiring-executable-accounting-replay.json b/doc/plans/2026-10-02-hiring-executable-accounting-replay.json
new file mode 100644
index 00000000000..7a3c6caaf07
--- /dev/null
+++ b/doc/plans/2026-10-02-hiring-executable-accounting-replay.json
@@ -0,0 +1,740 @@
+{
+ "schema": "paperclip.hiring-executable-accounting-replay.v1",
+ "assessmentType": "Provider-free replay through both new executable guards; original model measurements and verdicts unchanged",
+ "evaluatedCodeRevision": "eef64009dc144b91b245a731ea9a1c3c07406a19",
+ "evaluatedCodeHashes": {
+ "tests/runner-e2e/hiring-template-cases.ts": "06915e33cc9a5241cd28a7184fa33d098c30aed4114accea4f93838aaba3738f",
+ "tests/runner-e2e/hiring-template-scoring.ts": "a9e1efa7e11bad3aa8dc873a28325b3153799251740ae87c4623a08f7d45a5cb",
+ "tests/runner-e2e/hiring-template-flow.ts": "f3c6d29dc5019955dda4372ead7a9fdfbde447b7b92ef103527b9393ec60bd30",
+ "tests/runner-e2e/hiring-template-turn-accounting.ts": "8f2ad8b09e419796b372929b59dc7f86d41dcbf3a3144c45e329a1aa988b383b",
+ "tests/runner-e2e/chat-flow.ts": "09dd87ef7aef299ddbd1fad65b72817c042595f9e4a4e699c430497ac053a2d4"
+ },
+ "graderVersion": "paperclip.hiring-templates.v2",
+ "definitionDigest": "4d527906a967ca71c4c0e62cfbdc3405419931bcd6741b0630c4223bed2d4b6a",
+ "providerCalls": 0,
+ "newProviderRuns": 0,
+ "automaticRetries": 0,
+ "summary": {
+ "originalPairs": "Codex Fail→Fail; Claude Fail→Fail",
+ "correctedWorkflowOutcomePairs": "Codex Pass→Pass; Claude Pass→Pass",
+ "fullAttemptComparison": "Uncomparable in both profiles and variants; source-read coverage unchanged",
+ "originalMachineFailuresPreserved": 4,
+ "correctedScorerGuardsPassed": 4,
+ "correctedFinalChatGuardsPassed": 4,
+ "unchangedCoverageAssessments": 4,
+ "unchangedOtherOutcomeAssessments": 4,
+ "actualMeasuredRuns": 28,
+ "actualModelChargesKnown": false,
+ "broadEquivalenceEstablished": false
+ },
+ "assessments": [
+ {
+ "variant": "candidate",
+ "profile": "runner-codex",
+ "original": {
+ "sourceRevision": "9f5404ad3aacbe76777952759414d34fd381e674",
+ "graderVersion": "paperclip.hiring-templates.v1",
+ "definitionDigest": "4d7f18420889325af89aa48eaaf021e8178aa6d26d504b92041635a15741f004",
+ "machineStatus": "failed",
+ "outcomePassed": false,
+ "countCheckPassed": false,
+ "comparisonStatus": "uncomparable"
+ },
+ "corrected": {
+ "graderVersion": "paperclip.hiring-templates.v2",
+ "definitionDigest": "4d527906a967ca71c4c0e62cfbdc3405419931bcd6741b0630c4223bed2d4b6a",
+ "outcomePassed": true,
+ "comparisonStatus": "uncomparable",
+ "scorerGuardPassed": true,
+ "finalChatGuardPassed": true,
+ "turnAccounting": {
+ "version": "paperclip.hiring-template-turn-accounting.v1",
+ "counts": {
+ "requiredWorkTurns": 5,
+ "maximumCompletionTurns": 2,
+ "maximumTotalTurns": 7,
+ "requestedLeadTurns": 3,
+ "coderTurns": 2,
+ "completionTurns": 2,
+ "unclassifiedTurns": 0,
+ "snapshotRunCount": 7,
+ "actualRunCount": 7,
+ "costAccountingRunCount": 7
+ },
+ "predicates": [
+ {
+ "id": "known-fixture-context",
+ "passed": true
+ },
+ {
+ "id": "complete-public-run-ledger",
+ "passed": true
+ },
+ {
+ "id": "exact-five-required-work-turns",
+ "passed": true
+ },
+ {
+ "id": "successful-native-without-retries",
+ "passed": true
+ },
+ {
+ "id": "resolved-company-account-and-identity",
+ "passed": true
+ },
+ {
+ "id": "three-distinct-requested-chat-turns",
+ "passed": true
+ },
+ {
+ "id": "one-coder-execution-per-known-task",
+ "passed": true
+ },
+ {
+ "id": "task-origins-are-first-two-requested-turns",
+ "passed": true
+ },
+ {
+ "id": "bounded-server-completion-receipts",
+ "passed": true
+ },
+ {
+ "id": "completion-runs-have-attributed-chat-replies",
+ "passed": true
+ },
+ {
+ "id": "no-notification-created-extra-tasks",
+ "passed": true
+ }
+ ],
+ "passed": true
+ },
+ "checks": [
+ {
+ "id": "one-coder-hire",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Exactly one permanent coding teammate reports to the lead."
+ },
+ {
+ "id": "execution-account",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Hire keeps the lead model and managed account binding."
+ },
+ {
+ "id": "two-worker-tasks",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Both independent tasks are completed by the same coder in the chosen project."
+ },
+ {
+ "id": "bounded-work-and-completion-turns",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Exactly three requested lead turns and two coder executions, plus at most two strictly attributed completion notifications; every actual run remains counted."
+ },
+ {
+ "id": "initial-json-artifact",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Independent computation checks each original input/value and worker authorship."
+ },
+ {
+ "id": "reused-json-artifact",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "The reused coder applies the changed separator to every input."
+ },
+ {
+ "id": "original-preserved",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Reuse preserves the original document, revision and task identity."
+ },
+ {
+ "id": "source-fingerprints",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "Served instruction and hiring source bytes match the evaluated revision."
+ },
+ {
+ "id": "production-ceo-bundle",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "The API-created lead receives this revision's default CEO bundle, without a fixture override."
+ },
+ {
+ "id": "assigned-hiring-skill",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "Production CEO defaults assign the hiring skill."
+ },
+ {
+ "id": "production-source-reads",
+ "dimension": "coverage",
+ "passed": false,
+ "detail": "Completed lead read receipts before the hire prove the explicitly requested skill, guide, checklist and coder example paths. Unrecognized or missing reads leave coverage uncomparable."
+ },
+ {
+ "id": "supplied-coder-instructions",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "Saved hired instructions use the source revision's coder example with its company/name placeholders filled."
+ },
+ {
+ "id": "hired-instructions-durable",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "The same saved instruction bundle survives the reused worker execution."
+ },
+ {
+ "id": "hired-skills-durable",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "The saved skill selections survive the reused worker execution."
+ }
+ ]
+ },
+ "coverageUnchanged": true,
+ "otherOutcomesUnchanged": true,
+ "originalBytesUnchanged": true,
+ "inputSha256": {
+ "result": "44cbf64cfabd0257f31fb4d6909018d346f5667b0a7b3d7e855a2ece7e29c292",
+ "hiringTemplate": "9609ddcb81c6bee3c5db97312138b4ea3e294da13ea540e41f363c826a514067",
+ "apiState": "ef02af29bcf61ff3eace0549ca164a28c7950d1a3e14fc58c89bf9cb0f944b4d"
+ }
+ },
+ {
+ "variant": "candidate",
+ "profile": "runner-acpx-claude",
+ "original": {
+ "sourceRevision": "9f5404ad3aacbe76777952759414d34fd381e674",
+ "graderVersion": "paperclip.hiring-templates.v1",
+ "definitionDigest": "4d7f18420889325af89aa48eaaf021e8178aa6d26d504b92041635a15741f004",
+ "machineStatus": "failed",
+ "outcomePassed": false,
+ "countCheckPassed": false,
+ "comparisonStatus": "uncomparable"
+ },
+ "corrected": {
+ "graderVersion": "paperclip.hiring-templates.v2",
+ "definitionDigest": "4d527906a967ca71c4c0e62cfbdc3405419931bcd6741b0630c4223bed2d4b6a",
+ "outcomePassed": true,
+ "comparisonStatus": "uncomparable",
+ "scorerGuardPassed": true,
+ "finalChatGuardPassed": true,
+ "turnAccounting": {
+ "version": "paperclip.hiring-template-turn-accounting.v1",
+ "counts": {
+ "requiredWorkTurns": 5,
+ "maximumCompletionTurns": 2,
+ "maximumTotalTurns": 7,
+ "requestedLeadTurns": 3,
+ "coderTurns": 2,
+ "completionTurns": 2,
+ "unclassifiedTurns": 0,
+ "snapshotRunCount": 7,
+ "actualRunCount": 7,
+ "costAccountingRunCount": 7
+ },
+ "predicates": [
+ {
+ "id": "known-fixture-context",
+ "passed": true
+ },
+ {
+ "id": "complete-public-run-ledger",
+ "passed": true
+ },
+ {
+ "id": "exact-five-required-work-turns",
+ "passed": true
+ },
+ {
+ "id": "successful-native-without-retries",
+ "passed": true
+ },
+ {
+ "id": "resolved-company-account-and-identity",
+ "passed": true
+ },
+ {
+ "id": "three-distinct-requested-chat-turns",
+ "passed": true
+ },
+ {
+ "id": "one-coder-execution-per-known-task",
+ "passed": true
+ },
+ {
+ "id": "task-origins-are-first-two-requested-turns",
+ "passed": true
+ },
+ {
+ "id": "bounded-server-completion-receipts",
+ "passed": true
+ },
+ {
+ "id": "completion-runs-have-attributed-chat-replies",
+ "passed": true
+ },
+ {
+ "id": "no-notification-created-extra-tasks",
+ "passed": true
+ }
+ ],
+ "passed": true
+ },
+ "checks": [
+ {
+ "id": "one-coder-hire",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Exactly one permanent coding teammate reports to the lead."
+ },
+ {
+ "id": "execution-account",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Hire keeps the lead model and managed account binding."
+ },
+ {
+ "id": "two-worker-tasks",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Both independent tasks are completed by the same coder in the chosen project."
+ },
+ {
+ "id": "bounded-work-and-completion-turns",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Exactly three requested lead turns and two coder executions, plus at most two strictly attributed completion notifications; every actual run remains counted."
+ },
+ {
+ "id": "initial-json-artifact",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Independent computation checks each original input/value and worker authorship."
+ },
+ {
+ "id": "reused-json-artifact",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "The reused coder applies the changed separator to every input."
+ },
+ {
+ "id": "original-preserved",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Reuse preserves the original document, revision and task identity."
+ },
+ {
+ "id": "source-fingerprints",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "Served instruction and hiring source bytes match the evaluated revision."
+ },
+ {
+ "id": "production-ceo-bundle",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "The API-created lead receives this revision's default CEO bundle, without a fixture override."
+ },
+ {
+ "id": "assigned-hiring-skill",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "Production CEO defaults assign the hiring skill."
+ },
+ {
+ "id": "production-source-reads",
+ "dimension": "coverage",
+ "passed": false,
+ "detail": "Completed lead read receipts before the hire prove the explicitly requested skill, guide, checklist and coder example paths. Unrecognized or missing reads leave coverage uncomparable."
+ },
+ {
+ "id": "supplied-coder-instructions",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "Saved hired instructions use the source revision's coder example with its company/name placeholders filled."
+ },
+ {
+ "id": "hired-instructions-durable",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "The same saved instruction bundle survives the reused worker execution."
+ },
+ {
+ "id": "hired-skills-durable",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "The saved skill selections survive the reused worker execution."
+ }
+ ]
+ },
+ "coverageUnchanged": true,
+ "otherOutcomesUnchanged": true,
+ "originalBytesUnchanged": true,
+ "inputSha256": {
+ "result": "a83aecc26ef0af2e231cb364299cf0cb2f2ccd83b6998913dcd33be72d4c0824",
+ "hiringTemplate": "4f83f523b955120c5baac18572dce752b278dbc9ff765b940c0e17c37ab28ae0",
+ "apiState": "a208a3e3568fe9aacbec8d683a502a0d304a47571a1b97c229d2936e5d1bb087"
+ }
+ },
+ {
+ "variant": "baseline",
+ "profile": "runner-codex",
+ "original": {
+ "sourceRevision": "296a4df85e8bcc97a160fc78c291b17adb828196",
+ "graderVersion": "paperclip.hiring-templates.v1",
+ "definitionDigest": "4d7f18420889325af89aa48eaaf021e8178aa6d26d504b92041635a15741f004",
+ "machineStatus": "failed",
+ "outcomePassed": false,
+ "countCheckPassed": false,
+ "comparisonStatus": "uncomparable"
+ },
+ "corrected": {
+ "graderVersion": "paperclip.hiring-templates.v2",
+ "definitionDigest": "4d527906a967ca71c4c0e62cfbdc3405419931bcd6741b0630c4223bed2d4b6a",
+ "outcomePassed": true,
+ "comparisonStatus": "uncomparable",
+ "scorerGuardPassed": true,
+ "finalChatGuardPassed": true,
+ "turnAccounting": {
+ "version": "paperclip.hiring-template-turn-accounting.v1",
+ "counts": {
+ "requiredWorkTurns": 5,
+ "maximumCompletionTurns": 2,
+ "maximumTotalTurns": 7,
+ "requestedLeadTurns": 3,
+ "coderTurns": 2,
+ "completionTurns": 2,
+ "unclassifiedTurns": 0,
+ "snapshotRunCount": 7,
+ "actualRunCount": 7,
+ "costAccountingRunCount": 7
+ },
+ "predicates": [
+ {
+ "id": "known-fixture-context",
+ "passed": true
+ },
+ {
+ "id": "complete-public-run-ledger",
+ "passed": true
+ },
+ {
+ "id": "exact-five-required-work-turns",
+ "passed": true
+ },
+ {
+ "id": "successful-native-without-retries",
+ "passed": true
+ },
+ {
+ "id": "resolved-company-account-and-identity",
+ "passed": true
+ },
+ {
+ "id": "three-distinct-requested-chat-turns",
+ "passed": true
+ },
+ {
+ "id": "one-coder-execution-per-known-task",
+ "passed": true
+ },
+ {
+ "id": "task-origins-are-first-two-requested-turns",
+ "passed": true
+ },
+ {
+ "id": "bounded-server-completion-receipts",
+ "passed": true
+ },
+ {
+ "id": "completion-runs-have-attributed-chat-replies",
+ "passed": true
+ },
+ {
+ "id": "no-notification-created-extra-tasks",
+ "passed": true
+ }
+ ],
+ "passed": true
+ },
+ "checks": [
+ {
+ "id": "one-coder-hire",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Exactly one permanent coding teammate reports to the lead."
+ },
+ {
+ "id": "execution-account",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Hire keeps the lead model and managed account binding."
+ },
+ {
+ "id": "two-worker-tasks",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Both independent tasks are completed by the same coder in the chosen project."
+ },
+ {
+ "id": "bounded-work-and-completion-turns",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Exactly three requested lead turns and two coder executions, plus at most two strictly attributed completion notifications; every actual run remains counted."
+ },
+ {
+ "id": "initial-json-artifact",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Independent computation checks each original input/value and worker authorship."
+ },
+ {
+ "id": "reused-json-artifact",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "The reused coder applies the changed separator to every input."
+ },
+ {
+ "id": "original-preserved",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Reuse preserves the original document, revision and task identity."
+ },
+ {
+ "id": "source-fingerprints",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "Served instruction and hiring source bytes match the evaluated revision."
+ },
+ {
+ "id": "production-ceo-bundle",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "The API-created lead receives this revision's default CEO bundle, without a fixture override."
+ },
+ {
+ "id": "assigned-hiring-skill",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "Production CEO defaults assign the hiring skill."
+ },
+ {
+ "id": "production-source-reads",
+ "dimension": "coverage",
+ "passed": false,
+ "detail": "Completed lead read receipts before the hire prove the explicitly requested skill, guide, checklist and coder example paths. Unrecognized or missing reads leave coverage uncomparable."
+ },
+ {
+ "id": "supplied-coder-instructions",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "Saved hired instructions use the source revision's coder example with its company/name placeholders filled."
+ },
+ {
+ "id": "hired-instructions-durable",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "The same saved instruction bundle survives the reused worker execution."
+ },
+ {
+ "id": "hired-skills-durable",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "The saved skill selections survive the reused worker execution."
+ }
+ ]
+ },
+ "coverageUnchanged": true,
+ "otherOutcomesUnchanged": true,
+ "originalBytesUnchanged": true,
+ "inputSha256": {
+ "result": "d912d8400bfff4f7f922aa6b264f9ce5fff1ba2d893abf03790c4cfea352261f",
+ "hiringTemplate": "88b23e4d2cc8831a5d88b8479cc69c0d1c2e17a6a5243707b4bd19716a244aca",
+ "apiState": "dff6bb13bb54d45024966d9cfbeb6dbe6f2241e674b0b1350c1384863202a97f"
+ }
+ },
+ {
+ "variant": "baseline",
+ "profile": "runner-acpx-claude",
+ "original": {
+ "sourceRevision": "296a4df85e8bcc97a160fc78c291b17adb828196",
+ "graderVersion": "paperclip.hiring-templates.v1",
+ "definitionDigest": "4d7f18420889325af89aa48eaaf021e8178aa6d26d504b92041635a15741f004",
+ "machineStatus": "failed",
+ "outcomePassed": false,
+ "countCheckPassed": false,
+ "comparisonStatus": "uncomparable"
+ },
+ "corrected": {
+ "graderVersion": "paperclip.hiring-templates.v2",
+ "definitionDigest": "4d527906a967ca71c4c0e62cfbdc3405419931bcd6741b0630c4223bed2d4b6a",
+ "outcomePassed": true,
+ "comparisonStatus": "uncomparable",
+ "scorerGuardPassed": true,
+ "finalChatGuardPassed": true,
+ "turnAccounting": {
+ "version": "paperclip.hiring-template-turn-accounting.v1",
+ "counts": {
+ "requiredWorkTurns": 5,
+ "maximumCompletionTurns": 2,
+ "maximumTotalTurns": 7,
+ "requestedLeadTurns": 3,
+ "coderTurns": 2,
+ "completionTurns": 2,
+ "unclassifiedTurns": 0,
+ "snapshotRunCount": 7,
+ "actualRunCount": 7,
+ "costAccountingRunCount": 7
+ },
+ "predicates": [
+ {
+ "id": "known-fixture-context",
+ "passed": true
+ },
+ {
+ "id": "complete-public-run-ledger",
+ "passed": true
+ },
+ {
+ "id": "exact-five-required-work-turns",
+ "passed": true
+ },
+ {
+ "id": "successful-native-without-retries",
+ "passed": true
+ },
+ {
+ "id": "resolved-company-account-and-identity",
+ "passed": true
+ },
+ {
+ "id": "three-distinct-requested-chat-turns",
+ "passed": true
+ },
+ {
+ "id": "one-coder-execution-per-known-task",
+ "passed": true
+ },
+ {
+ "id": "task-origins-are-first-two-requested-turns",
+ "passed": true
+ },
+ {
+ "id": "bounded-server-completion-receipts",
+ "passed": true
+ },
+ {
+ "id": "completion-runs-have-attributed-chat-replies",
+ "passed": true
+ },
+ {
+ "id": "no-notification-created-extra-tasks",
+ "passed": true
+ }
+ ],
+ "passed": true
+ },
+ "checks": [
+ {
+ "id": "one-coder-hire",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Exactly one permanent coding teammate reports to the lead."
+ },
+ {
+ "id": "execution-account",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Hire keeps the lead model and managed account binding."
+ },
+ {
+ "id": "two-worker-tasks",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Both independent tasks are completed by the same coder in the chosen project."
+ },
+ {
+ "id": "bounded-work-and-completion-turns",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Exactly three requested lead turns and two coder executions, plus at most two strictly attributed completion notifications; every actual run remains counted."
+ },
+ {
+ "id": "initial-json-artifact",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Independent computation checks each original input/value and worker authorship."
+ },
+ {
+ "id": "reused-json-artifact",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "The reused coder applies the changed separator to every input."
+ },
+ {
+ "id": "original-preserved",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Reuse preserves the original document, revision and task identity."
+ },
+ {
+ "id": "source-fingerprints",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "Served instruction and hiring source bytes match the evaluated revision."
+ },
+ {
+ "id": "production-ceo-bundle",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "The API-created lead receives this revision's default CEO bundle, without a fixture override."
+ },
+ {
+ "id": "assigned-hiring-skill",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "Production CEO defaults assign the hiring skill."
+ },
+ {
+ "id": "production-source-reads",
+ "dimension": "coverage",
+ "passed": false,
+ "detail": "Completed lead read receipts before the hire prove the explicitly requested skill, guide, checklist and coder example paths. Unrecognized or missing reads leave coverage uncomparable."
+ },
+ {
+ "id": "supplied-coder-instructions",
+ "dimension": "coverage",
+ "passed": false,
+ "detail": "Saved hired instructions use the source revision's coder example with its company/name placeholders filled."
+ },
+ {
+ "id": "hired-instructions-durable",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "The same saved instruction bundle survives the reused worker execution."
+ },
+ {
+ "id": "hired-skills-durable",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "The saved skill selections survive the reused worker execution."
+ }
+ ]
+ },
+ "coverageUnchanged": true,
+ "otherOutcomesUnchanged": true,
+ "originalBytesUnchanged": true,
+ "inputSha256": {
+ "result": "844763ddc83461b2bea620f153f4bfe0bfee20a27bf33a60017a45c774ce2f6a",
+ "hiringTemplate": "27b153798472e206970c46358febdda363cb75f892734757e76994117f0d2c9b",
+ "apiState": "441cf7272ea28c5e1182adf48dba09a401e88c6cad3a99e72c8cf3f46b1c5b41"
+ }
+ }
+ ]
+}
diff --git a/doc/plans/2026-10-02-hiring-executable-accounting-replay.md b/doc/plans/2026-10-02-hiring-executable-accounting-replay.md
new file mode 100644
index 00000000000..21314b61930
--- /dev/null
+++ b/doc/plans/2026-10-02-hiring-executable-accounting-replay.md
@@ -0,0 +1,59 @@
+# Executable hiring lifecycle accounting repair
+
+**Current TL;DR:** No new model calls were made. The original Codex and Claude pairs remain Fail → Fail. The stricter v3 executable replay verifies Codex accounting in both variants; Claude notification action attribution remains unresolved/uncomparable because provider and native request IDs cannot be exactly joined. No notification writes are observed in the retained native API receipts. Source-read coverage remains uncomparable for both profiles, independently of action attribution. Earlier sidecar-v1 and initial executable-v2 passes remain below with their limited task-only proof identified.
+
+## Current stricter executable replay
+
+Code revision: `e4077ade1818d98b9862ae79ee1d49a007dcf9c1`. Hiring grader: `paperclip.hiring-templates.v3`; turn accounting: `paperclip.hiring-template-turn-accounting.v2`. The separately versioned [v2 JSON receipt](2026-10-02-hiring-executable-accounting-replay.v2.json) pins exact source hashes and unchanged original inputs.
+
+| Profile | Original machine grades | Limited sidecar v1 / initial executable v2 | Stricter executable accounting | Source-read coverage |
+| --- | --- | --- | --- | --- |
+| Codex | Fail → Fail | Pass → Pass | Verified / both new guards pass in each variant | Uncomparable both |
+| ACPX Claude | Fail → Fail | Pass → Pass | Unresolved/uncomparable action attribution in each variant; guards fail closed | Uncomparable both; historical six-backtick exact-template mismatch remains |
+
+The limited sidecar and initial executable check rejected notification-created tasks but could miss an unrelated document write during a notification. Their original results and hashes are preserved; they do not prove every notification was harmless. The stricter helper adds a twelfth predicate and an independent action-coverage check. It requires complete contiguous event streams, an accepted control-plane result and succeeded/completed terminal, exact canonical/native action IDs, successful known GET API receipts or verified reads/discovery, and attributed native chat finish. Document/task/agent mutations, failed mutation attempts, incomplete streams and unknown or unmatched actions cannot pass. A readonly hint alone cannot qualify a generic API call.
+
+Codex verifies 10 candidate and 11 baseline notification tool executions, including five and seven exactly joined successful GET calls, with zero unresolved actions. ACPX's native request IDs and provider execution IDs use separate namespaces; names, ordering and counts cannot safely join them. All observed ACPX native API calls are successful GETs, but the stronger cross-ledger proof is missing (five candidate/four baseline unresolved observations). This is an evidence limitation, not a newly observed task failure or a prompt regression. No production carriers or source-read grading are changed.
+
+The observation repair retries entire bracketed snapshots, waits both known Done task callbacks and attributed chat replies (including batching), checks untruncated pending-wake diagnostics, and requires two identical complete observations. It covers the quiet gap before pending outbox work enqueues a wake. Accounted coalesced wakes are admitted only with a linked terminal run and known callbacks. The final guard performs that same complete refresh rather than mixing a stale evidence snapshot with new runs. The generic five-work-turn helper still admits zero notifications when none are owed; this production delegated fixture owes two task completions.
+
+All six non-count outcome checks and every original source/template coverage check remain byte-identical in all four replay projections. All 28 actual model runs remain counted; original input hashes and failed verdicts are unchanged. The stricter action check is separately classified as coverage when attribution is missing. No broad equivalence is established.
+
+- 977 credential-free support tests pass across 64 files, including 144 focused helper/scorer/settlement integrations.
+- E2E typecheck, exact two-cell discovery, canonical capability contract/inventory checks and diff checks pass.
+- Two current-head review findings are fixed: racing observations and unchecked completion-turn writes. Fresh review/CI is required on this source.
+- Initial-head CI retained two unrelated browser failures: exact agent-run denial feedback and touch-picker scroll position. Neither browser path imports the changed runner-e2e harness. They are preserved without a blind rerun; the necessary review-fix head runs normal CI.
+- No providers, old campaign retries or extra paid scope are launched. Actual prior model charges remain unknown.
+
+## Initial executable v2 replay (limited notification proof)
+
+TL;DR: This repairs a grading defect; it does not change model instructions or rerun models. The original Codex and Claude pairs remain Fail → Fail. Provider-free replay through both corrected executable paths passes all four retained cells; source-read coverage remains uncomparable. This is a grading correction, not a new model-performance result.
+
+The original fixture required exactly five total runs. Production adds legitimate server completion turns after delegated work. The corrected v2 contract requires exactly three distinct user-requested CEO turns and two coder executions. At most two additional completion turns must pass strict public identity/account/task/delivery/timing/reply attribution. One turn may batch both completed tasks. Unknown, duplicate, failed, retried runs, notification-created tasks and missing public observations fail. This initial version did not inspect unrelated document writes during notifications; see the stricter current assessment above.
+
+Both executable count guards use the shared helper: the hiring scorer and the hiring-only final chat guard. The catalog declares five required / seven maximum total runs so timeout/cost planning includes notifications. Non-hiring count guards remain unchanged. Source-read and exact coder-body grading remain unchanged, including the historical Claude six-backtick mismatch. The grader version and full helper/chat/source digest change.
+
+## Preserved measurement
+
+The immutable [original and bounded sidecar report](https://github.com/paperclipai/paperclip/blob/8eb517ca1497687237163bdef4dfc4d3332ea916/doc/plans/2026-10-02-hiring-template-live-comparison.md) retains candidate `9f5404ad3aacbe76777952759414d34fd381e674` and historical `296a4df85e8bcc97a160fc78c291b17adb828196`, the identical original fixture digest, 28 actual successful runs, eight automatic completion turns, four successful cleanups and unknown actual charges. It calibrates sidecar v1 with 69 passing tests and records exact original input/grader hashes. The executable repair is a new source/grader revision; it cannot rewrite those measurements or prove performance equivalence.
+
+## Provider-free verification
+
+The executable code revision is `eef64009dc144b91b245a731ea9a1c3c07406a19`; report-only commits do not change its grader bytes. The [JSON receipt](2026-10-02-hiring-executable-accounting-replay.json) pins all five grader/flow/helper source hashes, v2 definition digest and original result/hiring/API input hashes.
+
+| Profile | Original executable result | Corrected retained workflow outcome | Both new count guards | Source coverage |
+| --- | --- | --- | --- | --- |
+| Codex | Fail → Fail | Pass → Pass | Pass in both variants | Uncomparable both |
+| ACPX Claude | Fail → Fail | Pass → Pass | Pass in both variants | Uncomparable both; historical exact coder body still fails |
+
+All six other outcome checks and every coverage check are byte-identical in the replay's check projection. Original input files and failed grades remain unchanged. All 28 actual model runs remain counted. The new helper has 11 lifecycle predicates, factoring the sidecar's lifecycle rule without requiring an already-computed original result.
+
+- All 946 credential-free E2E support tests pass across 64 files, including 99 helper calibrations and the four added scorer/final-guard integrations.
+- Fifteen focused hiring/run-count tests pass. The integrations admit five core turns, six with batching and seven with distinct notifications; reject an arbitrary wake despite the same total count; require public observations; retain source/template coverage failures; and preserve non-hiring count guards.
+- E2E typecheck, normal plugin SDK/Runner TypeScript dependency builds, canonical capability contract/inventory checks and existing two-cell discovery pass.
+- Retained replay executes the actual new scorer and final chat guard in each of the four original cells, using the unchanged saved API observations. Both guards pass 4/4; coverage and the six non-count outcomes stay unchanged 4/4.
+- Full repository CI and fresh review are pending on the separate draft PR. Local general repository typecheck/test/build were not repeated; exact-head CI must supply those gates before handoff.
+
+Initial development calibration caught mismatched synthetic account data and a deliberately changed template not preserved across reuse. The fixture data was corrected; assertions were kept. Initial cold typecheck lacked built Runner declarations; normal dependency builds resolved it. A temporary replay script's CommonJS extension rejected top-level await; the same script executed as ESM. These provider-free setup/development attempts remain private and are not live model results. No provider runs, old campaign retries or paid scope expansion are authorized for this repair. Public replay receipts will include only grader/input hashes, counts, predicate/check results and original verdicts; credentials, provider session IDs and hidden reasoning remain private.
+
+The branch was safely replayed on master `59c07ede7` before PR creation. The intervening master changes touch only two agent-provider UI files; all eval source bytes are unchanged. The four-cell provider-free replay was repeated against the final reachable code revision, with the same input hashes, checks and zero providers.
diff --git a/doc/plans/2026-10-02-hiring-executable-accounting-replay.v2.json b/doc/plans/2026-10-02-hiring-executable-accounting-replay.v2.json
new file mode 100644
index 00000000000..9c34e86b199
--- /dev/null
+++ b/doc/plans/2026-10-02-hiring-executable-accounting-replay.v2.json
@@ -0,0 +1,815 @@
+{
+ "schema": "paperclip.hiring-executable-accounting-replay.v2",
+ "assessmentType": "Provider-free replay through both new executable guards; original model measurements and verdicts unchanged",
+ "evaluatedCodeRevision": "e4077ade1818d98b9862ae79ee1d49a007dcf9c1",
+ "evaluatedCodeHashes": {
+ "tests/runner-e2e/hiring-template-cases.ts": "a440ebf5a932525d388f507f8b47490a535d377c9f9c9beba6144f1fc2214b7c",
+ "tests/runner-e2e/hiring-template-scoring.ts": "5f600b8329c981f1fc94ecc1b70a94b78d4a32a5b8859600208cbe1f91be2dac",
+ "tests/runner-e2e/hiring-template-flow.ts": "10b2415ad6ee293286db0a8cc8cb7a6a363d993a70560ab0a82f668018b5e3f5",
+ "tests/runner-e2e/hiring-template-turn-accounting.ts": "13792c69669b99748087d6a78af8ab35c6293d1ad3e3396efcbe39620169ad35",
+ "tests/runner-e2e/chat-flow.ts": "85d8c3da832871f38cc4ed940046d28ed7b3edf17486ce43b0f3313c06d17d7a"
+ },
+ "graderVersion": "paperclip.hiring-templates.v3",
+ "definitionDigest": "cddbcb6b2f3050e065599011ace2faee048047fae6ea9bc9183db8c5744e2f38",
+ "providerCalls": 0,
+ "newProviderRuns": 0,
+ "automaticRetries": 0,
+ "summary": {
+ "originalPairs": "Codex Fail→Fail; Claude Fail→Fail",
+ "correctedWorkflowOutcomePairs": "Codex Pass→Pass; Claude action attribution unresolved/uncomparable in both variants (not a measured task failure)",
+ "fullAttemptComparison": "Uncomparable in both profiles and variants; source-read coverage unchanged",
+ "originalMachineFailuresPreserved": 4,
+ "correctedScorerGuardsPassed": 2,
+ "correctedFinalChatGuardsPassed": 2,
+ "strictActionVerifiedAssessments": 2,
+ "strictActionUncomparableAssessments": 2,
+ "unchangedOriginalCoverageAssessments": 4,
+ "unchangedOtherOutcomeAssessments": 4,
+ "actualMeasuredRuns": 28,
+ "actualModelChargesKnown": false,
+ "broadEquivalenceEstablished": false,
+ "priorSidecarLimitation": "Sidecar v1 and initial executable v2 checked notification-created tasks, not unrelated document writes. Their original passes remain preserved."
+ },
+ "assessments": [
+ {
+ "variant": "candidate",
+ "profile": "runner-codex",
+ "original": {
+ "sourceRevision": "9f5404ad3aacbe76777952759414d34fd381e674",
+ "graderVersion": "paperclip.hiring-templates.v1",
+ "definitionDigest": "4d7f18420889325af89aa48eaaf021e8178aa6d26d504b92041635a15741f004",
+ "machineStatus": "failed",
+ "outcomePassed": false,
+ "countCheckPassed": false,
+ "comparisonStatus": "uncomparable"
+ },
+ "corrected": {
+ "graderVersion": "paperclip.hiring-templates.v3",
+ "definitionDigest": "cddbcb6b2f3050e065599011ace2faee048047fae6ea9bc9183db8c5744e2f38",
+ "outcomePassed": true,
+ "comparisonStatus": "uncomparable",
+ "scorerGuardPassed": true,
+ "finalChatGuardPassed": true,
+ "assessmentStatus": "verified",
+ "turnAccounting": {
+ "version": "paperclip.hiring-template-turn-accounting.v2",
+ "counts": {
+ "requiredWorkTurns": 5,
+ "maximumCompletionTurns": 2,
+ "maximumTotalTurns": 7,
+ "requestedLeadTurns": 3,
+ "coderTurns": 2,
+ "completionTurns": 2,
+ "unclassifiedTurns": 0,
+ "snapshotRunCount": 7,
+ "actualRunCount": 7,
+ "costAccountingRunCount": 7
+ },
+ "predicates": [
+ {
+ "id": "known-fixture-context",
+ "passed": true
+ },
+ {
+ "id": "complete-public-run-ledger",
+ "passed": true
+ },
+ {
+ "id": "exact-five-required-work-turns",
+ "passed": true
+ },
+ {
+ "id": "successful-native-without-retries",
+ "passed": true
+ },
+ {
+ "id": "resolved-company-account-and-identity",
+ "passed": true
+ },
+ {
+ "id": "three-distinct-requested-chat-turns",
+ "passed": true
+ },
+ {
+ "id": "one-coder-execution-per-known-task",
+ "passed": true
+ },
+ {
+ "id": "task-origins-are-first-two-requested-turns",
+ "passed": true
+ },
+ {
+ "id": "bounded-server-completion-receipts",
+ "passed": true
+ },
+ {
+ "id": "completion-runs-have-attributed-chat-replies",
+ "passed": true
+ },
+ {
+ "id": "no-notification-created-extra-tasks",
+ "passed": true
+ },
+ {
+ "id": "completion-turns-only-report-actions",
+ "passed": true
+ }
+ ],
+ "actionEvidence": {
+ "status": "verified",
+ "notificationRuns": 2,
+ "canonicalExecutions": 10,
+ "matchedNativeApiCalls": 5,
+ "unknownExecutions": 0
+ },
+ "passed": true
+ },
+ "checks": [
+ {
+ "id": "one-coder-hire",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Exactly one permanent coding teammate reports to the lead."
+ },
+ {
+ "id": "execution-account",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Hire keeps the lead model and managed account binding."
+ },
+ {
+ "id": "two-worker-tasks",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Both independent tasks are completed by the same coder in the chosen project."
+ },
+ {
+ "id": "bounded-work-and-completion-turns",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Exactly three requested lead turns and two coder executions, plus at most two strictly attributed completion notifications; every actual run remains counted."
+ },
+ {
+ "id": "initial-json-artifact",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Independent computation checks each original input/value and worker authorship."
+ },
+ {
+ "id": "reused-json-artifact",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "The reused coder applies the changed separator to every input."
+ },
+ {
+ "id": "original-preserved",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Reuse preserves the original document, revision and task identity."
+ },
+ {
+ "id": "source-fingerprints",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "Served instruction and hiring source bytes match the evaluated revision."
+ },
+ {
+ "id": "production-ceo-bundle",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "The API-created lead receives this revision's default CEO bundle, without a fixture override."
+ },
+ {
+ "id": "assigned-hiring-skill",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "Production CEO defaults assign the hiring skill."
+ },
+ {
+ "id": "production-source-reads",
+ "dimension": "coverage",
+ "passed": false,
+ "detail": "Completed lead read receipts before the hire prove the explicitly requested skill, guide, checklist and coder example paths. Unrecognized or missing reads leave coverage uncomparable."
+ },
+ {
+ "id": "supplied-coder-instructions",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "Saved hired instructions use the source revision's coder example with its company/name placeholders filled."
+ },
+ {
+ "id": "hired-instructions-durable",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "The same saved instruction bundle survives the reused worker execution."
+ },
+ {
+ "id": "hired-skills-durable",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "The saved skill selections survive the reused worker execution."
+ },
+ {
+ "id": "completion-action-attribution",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "Notification actions require exact canonical/native identities; missing cross-namespace mapping is uncomparable, not proof of extra work."
+ }
+ ]
+ },
+ "coverageUnchanged": true,
+ "otherOutcomesUnchanged": true,
+ "originalBytesUnchanged": true,
+ "inputSha256": {
+ "result": "44cbf64cfabd0257f31fb4d6909018d346f5667b0a7b3d7e855a2ece7e29c292",
+ "hiringTemplate": "9609ddcb81c6bee3c5db97312138b4ea3e294da13ea540e41f363c826a514067",
+ "apiState": "ef02af29bcf61ff3eace0549ca164a28c7950d1a3e14fc58c89bf9cb0f944b4d"
+ }
+ },
+ {
+ "variant": "candidate",
+ "profile": "runner-acpx-claude",
+ "original": {
+ "sourceRevision": "9f5404ad3aacbe76777952759414d34fd381e674",
+ "graderVersion": "paperclip.hiring-templates.v1",
+ "definitionDigest": "4d7f18420889325af89aa48eaaf021e8178aa6d26d504b92041635a15741f004",
+ "machineStatus": "failed",
+ "outcomePassed": false,
+ "countCheckPassed": false,
+ "comparisonStatus": "uncomparable"
+ },
+ "corrected": {
+ "graderVersion": "paperclip.hiring-templates.v3",
+ "definitionDigest": "cddbcb6b2f3050e065599011ace2faee048047fae6ea9bc9183db8c5744e2f38",
+ "outcomePassed": false,
+ "comparisonStatus": "uncomparable",
+ "scorerGuardPassed": false,
+ "finalChatGuardPassed": false,
+ "assessmentStatus": "uncomparable",
+ "turnAccounting": {
+ "version": "paperclip.hiring-template-turn-accounting.v2",
+ "counts": {
+ "requiredWorkTurns": 5,
+ "maximumCompletionTurns": 2,
+ "maximumTotalTurns": 7,
+ "requestedLeadTurns": 3,
+ "coderTurns": 2,
+ "completionTurns": 2,
+ "unclassifiedTurns": 0,
+ "snapshotRunCount": 7,
+ "actualRunCount": 7,
+ "costAccountingRunCount": 7
+ },
+ "predicates": [
+ {
+ "id": "known-fixture-context",
+ "passed": true
+ },
+ {
+ "id": "complete-public-run-ledger",
+ "passed": true
+ },
+ {
+ "id": "exact-five-required-work-turns",
+ "passed": true
+ },
+ {
+ "id": "successful-native-without-retries",
+ "passed": true
+ },
+ {
+ "id": "resolved-company-account-and-identity",
+ "passed": true
+ },
+ {
+ "id": "three-distinct-requested-chat-turns",
+ "passed": true
+ },
+ {
+ "id": "one-coder-execution-per-known-task",
+ "passed": true
+ },
+ {
+ "id": "task-origins-are-first-two-requested-turns",
+ "passed": true
+ },
+ {
+ "id": "bounded-server-completion-receipts",
+ "passed": true
+ },
+ {
+ "id": "completion-runs-have-attributed-chat-replies",
+ "passed": true
+ },
+ {
+ "id": "no-notification-created-extra-tasks",
+ "passed": true
+ },
+ {
+ "id": "completion-turns-only-report-actions",
+ "passed": false
+ }
+ ],
+ "actionEvidence": {
+ "status": "uncomparable",
+ "notificationRuns": 2,
+ "canonicalExecutions": 3,
+ "matchedNativeApiCalls": 0,
+ "unknownExecutions": 5
+ },
+ "passed": false
+ },
+ "checks": [
+ {
+ "id": "one-coder-hire",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Exactly one permanent coding teammate reports to the lead."
+ },
+ {
+ "id": "execution-account",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Hire keeps the lead model and managed account binding."
+ },
+ {
+ "id": "two-worker-tasks",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Both independent tasks are completed by the same coder in the chosen project."
+ },
+ {
+ "id": "bounded-work-and-completion-turns",
+ "dimension": "outcome",
+ "passed": false,
+ "detail": "Exactly three requested lead turns and two coder executions, plus at most two strictly attributed completion notifications; every actual run remains counted."
+ },
+ {
+ "id": "initial-json-artifact",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Independent computation checks each original input/value and worker authorship."
+ },
+ {
+ "id": "reused-json-artifact",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "The reused coder applies the changed separator to every input."
+ },
+ {
+ "id": "original-preserved",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Reuse preserves the original document, revision and task identity."
+ },
+ {
+ "id": "source-fingerprints",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "Served instruction and hiring source bytes match the evaluated revision."
+ },
+ {
+ "id": "production-ceo-bundle",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "The API-created lead receives this revision's default CEO bundle, without a fixture override."
+ },
+ {
+ "id": "assigned-hiring-skill",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "Production CEO defaults assign the hiring skill."
+ },
+ {
+ "id": "production-source-reads",
+ "dimension": "coverage",
+ "passed": false,
+ "detail": "Completed lead read receipts before the hire prove the explicitly requested skill, guide, checklist and coder example paths. Unrecognized or missing reads leave coverage uncomparable."
+ },
+ {
+ "id": "supplied-coder-instructions",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "Saved hired instructions use the source revision's coder example with its company/name placeholders filled."
+ },
+ {
+ "id": "hired-instructions-durable",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "The same saved instruction bundle survives the reused worker execution."
+ },
+ {
+ "id": "hired-skills-durable",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "The saved skill selections survive the reused worker execution."
+ },
+ {
+ "id": "completion-action-attribution",
+ "dimension": "coverage",
+ "passed": false,
+ "detail": "Notification actions require exact canonical/native identities; missing cross-namespace mapping is uncomparable, not proof of extra work."
+ }
+ ]
+ },
+ "coverageUnchanged": true,
+ "otherOutcomesUnchanged": true,
+ "originalBytesUnchanged": true,
+ "inputSha256": {
+ "result": "a83aecc26ef0af2e231cb364299cf0cb2f2ccd83b6998913dcd33be72d4c0824",
+ "hiringTemplate": "4f83f523b955120c5baac18572dce752b278dbc9ff765b940c0e17c37ab28ae0",
+ "apiState": "a208a3e3568fe9aacbec8d683a502a0d304a47571a1b97c229d2936e5d1bb087"
+ }
+ },
+ {
+ "variant": "baseline",
+ "profile": "runner-codex",
+ "original": {
+ "sourceRevision": "296a4df85e8bcc97a160fc78c291b17adb828196",
+ "graderVersion": "paperclip.hiring-templates.v1",
+ "definitionDigest": "4d7f18420889325af89aa48eaaf021e8178aa6d26d504b92041635a15741f004",
+ "machineStatus": "failed",
+ "outcomePassed": false,
+ "countCheckPassed": false,
+ "comparisonStatus": "uncomparable"
+ },
+ "corrected": {
+ "graderVersion": "paperclip.hiring-templates.v3",
+ "definitionDigest": "cddbcb6b2f3050e065599011ace2faee048047fae6ea9bc9183db8c5744e2f38",
+ "outcomePassed": true,
+ "comparisonStatus": "uncomparable",
+ "scorerGuardPassed": true,
+ "finalChatGuardPassed": true,
+ "assessmentStatus": "verified",
+ "turnAccounting": {
+ "version": "paperclip.hiring-template-turn-accounting.v2",
+ "counts": {
+ "requiredWorkTurns": 5,
+ "maximumCompletionTurns": 2,
+ "maximumTotalTurns": 7,
+ "requestedLeadTurns": 3,
+ "coderTurns": 2,
+ "completionTurns": 2,
+ "unclassifiedTurns": 0,
+ "snapshotRunCount": 7,
+ "actualRunCount": 7,
+ "costAccountingRunCount": 7
+ },
+ "predicates": [
+ {
+ "id": "known-fixture-context",
+ "passed": true
+ },
+ {
+ "id": "complete-public-run-ledger",
+ "passed": true
+ },
+ {
+ "id": "exact-five-required-work-turns",
+ "passed": true
+ },
+ {
+ "id": "successful-native-without-retries",
+ "passed": true
+ },
+ {
+ "id": "resolved-company-account-and-identity",
+ "passed": true
+ },
+ {
+ "id": "three-distinct-requested-chat-turns",
+ "passed": true
+ },
+ {
+ "id": "one-coder-execution-per-known-task",
+ "passed": true
+ },
+ {
+ "id": "task-origins-are-first-two-requested-turns",
+ "passed": true
+ },
+ {
+ "id": "bounded-server-completion-receipts",
+ "passed": true
+ },
+ {
+ "id": "completion-runs-have-attributed-chat-replies",
+ "passed": true
+ },
+ {
+ "id": "no-notification-created-extra-tasks",
+ "passed": true
+ },
+ {
+ "id": "completion-turns-only-report-actions",
+ "passed": true
+ }
+ ],
+ "actionEvidence": {
+ "status": "verified",
+ "notificationRuns": 2,
+ "canonicalExecutions": 11,
+ "matchedNativeApiCalls": 7,
+ "unknownExecutions": 0
+ },
+ "passed": true
+ },
+ "checks": [
+ {
+ "id": "one-coder-hire",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Exactly one permanent coding teammate reports to the lead."
+ },
+ {
+ "id": "execution-account",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Hire keeps the lead model and managed account binding."
+ },
+ {
+ "id": "two-worker-tasks",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Both independent tasks are completed by the same coder in the chosen project."
+ },
+ {
+ "id": "bounded-work-and-completion-turns",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Exactly three requested lead turns and two coder executions, plus at most two strictly attributed completion notifications; every actual run remains counted."
+ },
+ {
+ "id": "initial-json-artifact",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Independent computation checks each original input/value and worker authorship."
+ },
+ {
+ "id": "reused-json-artifact",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "The reused coder applies the changed separator to every input."
+ },
+ {
+ "id": "original-preserved",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Reuse preserves the original document, revision and task identity."
+ },
+ {
+ "id": "source-fingerprints",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "Served instruction and hiring source bytes match the evaluated revision."
+ },
+ {
+ "id": "production-ceo-bundle",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "The API-created lead receives this revision's default CEO bundle, without a fixture override."
+ },
+ {
+ "id": "assigned-hiring-skill",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "Production CEO defaults assign the hiring skill."
+ },
+ {
+ "id": "production-source-reads",
+ "dimension": "coverage",
+ "passed": false,
+ "detail": "Completed lead read receipts before the hire prove the explicitly requested skill, guide, checklist and coder example paths. Unrecognized or missing reads leave coverage uncomparable."
+ },
+ {
+ "id": "supplied-coder-instructions",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "Saved hired instructions use the source revision's coder example with its company/name placeholders filled."
+ },
+ {
+ "id": "hired-instructions-durable",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "The same saved instruction bundle survives the reused worker execution."
+ },
+ {
+ "id": "hired-skills-durable",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "The saved skill selections survive the reused worker execution."
+ },
+ {
+ "id": "completion-action-attribution",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "Notification actions require exact canonical/native identities; missing cross-namespace mapping is uncomparable, not proof of extra work."
+ }
+ ]
+ },
+ "coverageUnchanged": true,
+ "otherOutcomesUnchanged": true,
+ "originalBytesUnchanged": true,
+ "inputSha256": {
+ "result": "d912d8400bfff4f7f922aa6b264f9ce5fff1ba2d893abf03790c4cfea352261f",
+ "hiringTemplate": "88b23e4d2cc8831a5d88b8479cc69c0d1c2e17a6a5243707b4bd19716a244aca",
+ "apiState": "dff6bb13bb54d45024966d9cfbeb6dbe6f2241e674b0b1350c1384863202a97f"
+ }
+ },
+ {
+ "variant": "baseline",
+ "profile": "runner-acpx-claude",
+ "original": {
+ "sourceRevision": "296a4df85e8bcc97a160fc78c291b17adb828196",
+ "graderVersion": "paperclip.hiring-templates.v1",
+ "definitionDigest": "4d7f18420889325af89aa48eaaf021e8178aa6d26d504b92041635a15741f004",
+ "machineStatus": "failed",
+ "outcomePassed": false,
+ "countCheckPassed": false,
+ "comparisonStatus": "uncomparable"
+ },
+ "corrected": {
+ "graderVersion": "paperclip.hiring-templates.v3",
+ "definitionDigest": "cddbcb6b2f3050e065599011ace2faee048047fae6ea9bc9183db8c5744e2f38",
+ "outcomePassed": false,
+ "comparisonStatus": "uncomparable",
+ "scorerGuardPassed": false,
+ "finalChatGuardPassed": false,
+ "assessmentStatus": "uncomparable",
+ "turnAccounting": {
+ "version": "paperclip.hiring-template-turn-accounting.v2",
+ "counts": {
+ "requiredWorkTurns": 5,
+ "maximumCompletionTurns": 2,
+ "maximumTotalTurns": 7,
+ "requestedLeadTurns": 3,
+ "coderTurns": 2,
+ "completionTurns": 2,
+ "unclassifiedTurns": 0,
+ "snapshotRunCount": 7,
+ "actualRunCount": 7,
+ "costAccountingRunCount": 7
+ },
+ "predicates": [
+ {
+ "id": "known-fixture-context",
+ "passed": true
+ },
+ {
+ "id": "complete-public-run-ledger",
+ "passed": true
+ },
+ {
+ "id": "exact-five-required-work-turns",
+ "passed": true
+ },
+ {
+ "id": "successful-native-without-retries",
+ "passed": true
+ },
+ {
+ "id": "resolved-company-account-and-identity",
+ "passed": true
+ },
+ {
+ "id": "three-distinct-requested-chat-turns",
+ "passed": true
+ },
+ {
+ "id": "one-coder-execution-per-known-task",
+ "passed": true
+ },
+ {
+ "id": "task-origins-are-first-two-requested-turns",
+ "passed": true
+ },
+ {
+ "id": "bounded-server-completion-receipts",
+ "passed": true
+ },
+ {
+ "id": "completion-runs-have-attributed-chat-replies",
+ "passed": true
+ },
+ {
+ "id": "no-notification-created-extra-tasks",
+ "passed": true
+ },
+ {
+ "id": "completion-turns-only-report-actions",
+ "passed": false
+ }
+ ],
+ "actionEvidence": {
+ "status": "uncomparable",
+ "notificationRuns": 2,
+ "canonicalExecutions": 3,
+ "matchedNativeApiCalls": 0,
+ "unknownExecutions": 4
+ },
+ "passed": false
+ },
+ "checks": [
+ {
+ "id": "one-coder-hire",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Exactly one permanent coding teammate reports to the lead."
+ },
+ {
+ "id": "execution-account",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Hire keeps the lead model and managed account binding."
+ },
+ {
+ "id": "two-worker-tasks",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Both independent tasks are completed by the same coder in the chosen project."
+ },
+ {
+ "id": "bounded-work-and-completion-turns",
+ "dimension": "outcome",
+ "passed": false,
+ "detail": "Exactly three requested lead turns and two coder executions, plus at most two strictly attributed completion notifications; every actual run remains counted."
+ },
+ {
+ "id": "initial-json-artifact",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Independent computation checks each original input/value and worker authorship."
+ },
+ {
+ "id": "reused-json-artifact",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "The reused coder applies the changed separator to every input."
+ },
+ {
+ "id": "original-preserved",
+ "dimension": "outcome",
+ "passed": true,
+ "detail": "Reuse preserves the original document, revision and task identity."
+ },
+ {
+ "id": "source-fingerprints",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "Served instruction and hiring source bytes match the evaluated revision."
+ },
+ {
+ "id": "production-ceo-bundle",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "The API-created lead receives this revision's default CEO bundle, without a fixture override."
+ },
+ {
+ "id": "assigned-hiring-skill",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "Production CEO defaults assign the hiring skill."
+ },
+ {
+ "id": "production-source-reads",
+ "dimension": "coverage",
+ "passed": false,
+ "detail": "Completed lead read receipts before the hire prove the explicitly requested skill, guide, checklist and coder example paths. Unrecognized or missing reads leave coverage uncomparable."
+ },
+ {
+ "id": "supplied-coder-instructions",
+ "dimension": "coverage",
+ "passed": false,
+ "detail": "Saved hired instructions use the source revision's coder example with its company/name placeholders filled."
+ },
+ {
+ "id": "hired-instructions-durable",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "The same saved instruction bundle survives the reused worker execution."
+ },
+ {
+ "id": "hired-skills-durable",
+ "dimension": "coverage",
+ "passed": true,
+ "detail": "The saved skill selections survive the reused worker execution."
+ },
+ {
+ "id": "completion-action-attribution",
+ "dimension": "coverage",
+ "passed": false,
+ "detail": "Notification actions require exact canonical/native identities; missing cross-namespace mapping is uncomparable, not proof of extra work."
+ }
+ ]
+ },
+ "coverageUnchanged": true,
+ "otherOutcomesUnchanged": true,
+ "originalBytesUnchanged": true,
+ "inputSha256": {
+ "result": "844763ddc83461b2bea620f153f4bfe0bfee20a27bf33a60017a45c774ce2f6a",
+ "hiringTemplate": "27b153798472e206970c46358febdda363cb75f892734757e76994117f0d2c9b",
+ "apiState": "441cf7272ea28c5e1182adf48dba09a401e88c6cad3a99e72c8cf3f46b1c5b41"
+ }
+ }
+ ]
+}
diff --git a/doc/plans/2026-10-02-hiring-skill-drafting-evidence.json b/doc/plans/2026-10-02-hiring-skill-drafting-evidence.json
new file mode 100644
index 00000000000..b8340ec247d
--- /dev/null
+++ b/doc/plans/2026-10-02-hiring-skill-drafting-evidence.json
@@ -0,0 +1,79 @@
+{
+ "kind": "independent-drafting-simulation",
+ "date": "2026-10-02",
+ "scope": "Three synthetic hire requests; read-only. No API calls, permanent hires, provider campaign, or live harness qualification.",
+ "skillSources": [
+ {
+ "path": "skills/paperclip-create-agent/SKILL.md",
+ "sha256": "00e3063a40bbe32592171fa613956bc1b503fe0a41c4973c8dae7b8cdf8c148a"
+ },
+ {
+ "path": "skills/paperclip-create-agent/references/agent-instruction-templates.md",
+ "sha256": "9ce87fc420b41e951cab664655886d0ee50fa253cb5b8647b4a7afa4a6082d2d"
+ },
+ {
+ "path": "skills/paperclip-create-agent/references/baseline-role-guide.md",
+ "sha256": "0841c5c483526d8d64c7217df7164bca7f3f03edcf4578f2baefcca01cd156b0"
+ },
+ {
+ "path": "skills/paperclip-create-agent/references/draft-review-checklist.md",
+ "sha256": "1cbe0577a9888f31467f5c7beea01d0aa6435da2a0f577b5fdd3b5fe773984ad"
+ },
+ {
+ "path": "skills/paperclip-create-agent/references/agents/coder.md",
+ "sha256": "e04a25fbc8bb29910b2f4a3719730b8840553b0524ce1ec570617701aca20650"
+ },
+ {
+ "path": "skills/paperclip-create-agent/references/agents/securityengineer.md",
+ "sha256": "9eecf981844ab1f5896dd1bae6b76acce8471c448841608c5655497d691ba1a0"
+ },
+ {
+ "path": "skills/paperclip-create-agent/references/api-reference.md",
+ "sha256": "f43bd2f74d60a9f019af1c037584f2cb4bb2b1f66f503a60eca80278676bded1"
+ }
+ ],
+ "observed": [
+ {
+ "request": "Backend engineer Ada; legacy Claude; repo-maintenance skill; CTO reporting line",
+ "instructions": "You are agent Ada, a backend software engineer at Northstar. You own implementation of assigned backend service changes.",
+ "desiredSkills": [
+ "northstar/repo-maintenance"
+ ],
+ "adapterType": "claude_local",
+ "model": "claude-sonnet-4-6",
+ "timerEnabled": false,
+ "literalCredentials": false
+ },
+ {
+ "request": "Release Coordinator Riley; native Codex; no schedule",
+ "instructions": "You are agent Riley, a Release Coordinator at Northstar. You own coordination of release readiness and publication requests.",
+ "desiredSkills": [],
+ "adapterType": "paperclip_runner",
+ "provider": "codex",
+ "model": "gpt-5.4",
+ "timerEnabled": false,
+ "literalCredentials": false
+ },
+ {
+ "request": "Security Engineer Sam; legacy Claude; exact user instruction; confidential workflow installed",
+ "instructions": "Review only the authentication service. Keep private findings in the incident-review workflow. Do not edit code.",
+ "requestedInstructionsPreservedExactly": true,
+ "desiredSkills": [
+ "northstar/incident-review"
+ ],
+ "adapterType": "claude_local",
+ "model": "claude-sonnet-4-6",
+ "timerEnabled": false,
+ "literalCredentials": false
+ }
+ ],
+ "remainingBeforeMutation": [
+ "Confirm live endpoint and adapter schemas.",
+ "Submit through authorized hire API and reconcile returned pending approval; no hire may be claimed from this simulation."
+ ],
+ "limits": [
+ "Outcome projection of independent subagent drafting, not a live full-stack measurement.",
+ "No baseline drafting simulation, timing, billing, or downstream work comparison.",
+ "Does not establish non-regression for removed workflow or domain policies."
+ ]
+}
diff --git a/doc/plans/2026-10-02-hiring-template-prompt-diff.md b/doc/plans/2026-10-02-hiring-template-prompt-diff.md
new file mode 100644
index 00000000000..c62e5eb3a6d
--- /dev/null
+++ b/doc/plans/2026-10-02-hiring-template-prompt-diff.md
@@ -0,0 +1,938 @@
+# Hiring template prompt comparison — 2026-10-02
+
+New default CEO hires receive one short `AGENTS.md`. Ad-hoc hires and imported teams use short role descriptions. The hiring skill and its drafting references no longer require a heartbeat pointer, a generic execution contract, per-touch comments, prescribed reviewers, or domain-lens catalogs.
+
+Baseline: `d6d88b9de2fc766637422cc43f985c747455a1b0`. Word counts below measure role instruction bodies, excluding reference introductions, recommended configuration, and catalog frontmatter. The default CEO count includes all four previously selected files. These counts describe context size, not outcome quality, billed tokens, or savings.
+
+| Prompt | Before words | After words |
+| --- | ---: | ---: |
+| [Default CEO bundle](../../server/src/onboarding-assets/ceo/AGENTS.md) | 1897 | 20 |
+| [Coder](../../skills/paperclip-create-agent/references/agents/coder.md) | 652 | 18 |
+| [QA](../../skills/paperclip-create-agent/references/agents/qa.md) | 619 | 21 |
+| [UX Designer](../../skills/paperclip-create-agent/references/agents/uxdesigner.md) | 1325 | 20 |
+| [Security Engineer](../../skills/paperclip-create-agent/references/agents/securityengineer.md) | 1724 | 28 |
+| [Chief of staff](../../server/src/onboarding-assets/first-task/chief-of-staff/AGENTS.md) | 164 | 25 |
+| [Catalog ceo](../../packages/teams-catalog/catalog/bundled/company-defaults/core-exec-team/agents/ceo/AGENTS.md) | 377 | 20 |
+| [Catalog cto](../../packages/teams-catalog/catalog/bundled/company-defaults/core-exec-team/agents/cto/AGENTS.md) | 205 | 17 |
+| [Catalog qa](../../packages/teams-catalog/catalog/bundled/company-defaults/core-exec-team/agents/qa/AGENTS.md) | 183 | 17 |
+| [Catalog ux-designer](../../packages/teams-catalog/catalog/bundled/product/product-design/agents/ux-designer/AGENTS.md) | 305 | 17 |
+| [Catalog cto](../../packages/teams-catalog/catalog/bundled/software-development/product-engineering/agents/cto/AGENTS.md) | 212 | 22 |
+| [Catalog qa](../../packages/teams-catalog/catalog/bundled/software-development/product-engineering/agents/qa/AGENTS.md) | 171 | 22 |
+| [Catalog senior-coder](../../packages/teams-catalog/catalog/bundled/software-development/product-engineering/agents/senior-coder/AGENTS.md) | 201 | 20 |
+| [Catalog content-lead](../../packages/teams-catalog/catalog/optional/content/content-machine/agents/content-lead/AGENTS.md) | 16 | 16 |
+
+## Scope and compatibility
+
+- The CEO loader selects only `AGENTS.md`; legacy `HEARTBEAT.md`, `SOUL.md`, and `TOOLS.md` remain on disk for compatibility but are no longer part of new default bundles.
+- Company-supplied/custom and already-saved instruction bundles are not migrated or overwritten. Reporting lines, catalog slugs, skills, permissions, auth, budgets, scheduled routines, and approval controls keep their existing configuration paths.
+- The optional Content Lead was already one short role sentence and is unchanged. Specialized Summarizer, Reflection Coach, and Wiki Maintainer instructions are unchanged; their scope/output/review contracts require separate product-specific assessment.
+- This branch starts from master and is separate from draft PR #14948. The generic non-CEO fallback and shared runtime prompt reductions remain in that PR. It must land for hires using the server fallback to receive the eight-word generic manual.
+- Both native and legacy managed-bundle creation use the shared defaults. No native tool procedure or legacy API procedure is embedded in these role prompts.
+
+## How hires are drafted
+
+| Before | After |
+| --- | --- |
+| Role-specific templates were the default drafting path. | Templates are optional role examples. |
+| Unknown roles required a 60–150-line manual with eight sections. | Start with a short identity and responsibility paragraph. |
+| Every new agent needed an execution contract and repeated task procedures. | Keep reporting lines, capabilities, and skills in their configuration fields. |
+| Templates prescribed reviewers, per-touch comments, and broad domain checklists. | Add detail only for a concrete requirement that the task, repository, skills, or configuration do not already express. |
+| The generated baseline could crowd out company instructions. | Preserve explicit requester instructions. |
+
+The hiring skill still checks authority, adapter schemas, reporting lines, installed skills, timer settings, confidential workflows, and approval state. Its native-tool and legacy-API transport guidance stays separate.
+
+Hiring skill drafting rules: before → after
+
+```diff
+diff --git a/skills/paperclip-create-agent/SKILL.md b/skills/paperclip-create-agent/SKILL.md
+index 6b2a0da0e..fa9e7b358 100644
+--- a/skills/paperclip-create-agent/SKILL.md
++++ b/skills/paperclip-create-agent/SKILL.md
+@@ -72,21 +72,24 @@ curl -sS "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/agent-configura
+
+ Note naming, icon, reporting-line, and adapter conventions the company already follows.
+
+-### 4. Choose the instruction source (required)
++### 4. Describe the role
+
+-This is the single most important decision for hire quality. Pick exactly one path:
++Use a short role paragraph for a new agent: its identity and the responsibility
++it owns. The [role examples](references/agent-instruction-templates.md) are
++optional starting points; for other roles, use the
++[baseline role guide](references/baseline-role-guide.md).
+
+-- **Exact template** — the role matches an entry in the template index. Use the matching file under `references/agents/` as the starting point.
+-- **Adjacent template** — no exact match, but an existing template is close (for example, a "Backend Engineer" hire adapted from `coder.md`, or a "Content Designer" adapted from `uxdesigner.md`). Copy the closest template and adapt deliberately: rename the role, rewrite the role charter, swap domain lenses, and remove sections that do not fit.
+-- **Generic fallback** — no template is close. Use the baseline role guide to construct a new `AGENTS.md` from scratch, filling in each recommended section for the specific role.
++Company-specific instructions supplied by the requester take precedence. Do not
++expand a role description into a generic operating manual. The harness supplies
++Paperclip coordination, skill discovery, and task lifecycle guidance; repository
++instructions and installed skills carry applicable work procedures. Avoid
++adding heartbeat pointers, execution contracts, mandatory per-touch comments,
++fixed reviewer routes, or catalogs of domain concepts to the hire's instructions.
+
+-Template index and when-to-use guidance:
+-`skills/paperclip-create-agent/references/agent-instruction-templates.md`
+-
+-Generic fallback for no-template hires:
+-`skills/paperclip-create-agent/references/baseline-role-guide.md`
+-
+-State which path you took in your hire-request comment so the board can see the reasoning.
++Keep reporting lines in `reportsTo`, capabilities in `capabilities`, and skills
++in `desiredSkills`. Add instruction detail only for a concrete company or role
++requirement that those fields, the task, repository instructions, or installed
++skills do not already express.
+
+ ### 5. Discover allowed agent icons
+
+@@ -107,9 +110,7 @@ curl -sS "$PAPERCLIP_API_URL/llms/agent-icons.txt" \
+ - leave timer heartbeats off by default; only set `runtimeConfig.heartbeat.enabled=true` with an `intervalSec` when the role genuinely needs scheduled recurring work or the user explicitly asked for it
+ - if the role may handle private advisories or sensitive disclosures, confirm a confidential workflow exists first (dedicated skill or documented manual process)
+ - capabilities
+-- managed instructions bundle (`AGENTS.md`) for adapters that support it; avoid durable `promptTemplate` config
+-- for coding or execution agents, include the Paperclip execution contract: start actionable work in the same heartbeat; do not stop at a plan unless planning was requested; leave durable progress with a clear next action; use child issues for long or parallel delegated work instead of polling; mark blocked work with owner/action; respect budget, pause/cancel, approval gates, and company boundaries
+-- instruction text such as `AGENTS.md` built from step 4; for local managed-bundle adapters, send this as top-level `instructionsBundle.files["AGENTS.md"]`. Do not set `adapterConfig.promptTemplate` or `bootstrapPromptTemplate` for new agents.
++- when supplying role instructions from step 4, send them as top-level `instructionsBundle.files["AGENTS.md"]` for managed-bundle adapters. Otherwise use the server default. Do not set `adapterConfig.promptTemplate` or `bootstrapPromptTemplate` for new agents.
+ - source issue linkage (`sourceIssueId` or `sourceIssueIds`) when this hire came from an issue
+
+ ### 7. Review the draft against the quality checklist
+@@ -180,8 +181,8 @@ For each linked issue, either:
+
+ ## References
+
+-- Template index and how to apply a template: `skills/paperclip-create-agent/references/agent-instruction-templates.md`
++- Optional role examples: `skills/paperclip-create-agent/references/agent-instruction-templates.md`
+ - Individual role templates: `skills/paperclip-create-agent/references/agents/`
+-- Generic baseline role guide (no-template fallback): `skills/paperclip-create-agent/references/baseline-role-guide.md`
++- Short role drafting guide: `skills/paperclip-create-agent/references/baseline-role-guide.md`
+ - Pre-submit draft-review checklist: `skills/paperclip-create-agent/references/draft-review-checklist.md`
+ - Endpoint payload shapes and full examples: `skills/paperclip-create-agent/references/api-reference.md`
+```
+
+Default CEO bundle: before → after
+
+```diff
+--- before/server/src/onboarding-assets/ceo/AGENTS.md
++++ after/server/src/onboarding-assets/ceo/AGENTS.md
+@@ -1,64 +1 @@
+-You are the CEO. Your job is to lead the company, not to do individual contributor work. You own strategy, prioritization, and cross-functional coordination.
+-
+-Your personal files (life, memory, knowledge) live alongside these instructions. Other agents may have their own folders and you may update them when necessary.
+-
+-Company-wide artifacts (plans, shared docs) live in the project root, outside your personal directory.
+-
+-## Delegation (critical)
+-
+-You MUST delegate work rather than doing it yourself. When a task is assigned to you:
+-
+-1. **Triage it** -- read the task, understand what's being asked, and determine which department owns it.
+-2. **Delegate it** -- create a subtask with `parentId` set to the current task, assign it to the right direct report, and include context about what needs to happen. Use these routing rules:
+- - **Code, bugs, features, infra, devtools, technical tasks** → CTO
+- - **Marketing, content, social media, growth, devrel** → CMO
+- - **UX, design, user research, design-system** → UXDesigner
+- - **Cross-functional or unclear** → break into separate subtasks for each department, or assign to the CTO if it's primarily technical with a design component
+- - If the right report doesn't exist yet, use the `paperclip-create-agent` skill to hire one before delegating.
+-3. **Do NOT write code, implement features, or fix bugs yourself.** Your reports exist for this. Even if a task seems small or quick, delegate it.
+-4. **Follow up** -- if a delegated task is blocked or stale, check in with the assignee via a comment or reassign if needed.
+-
+-## What you DO personally
+-
+-- Set priorities and make product decisions
+-- Resolve cross-team conflicts or ambiguity
+-- Communicate with the board (human users)
+-- Approve or reject proposals from your reports
+-- Hire new agents when the team needs capacity
+-- Unblock your direct reports when they escalate to you
+-
+-## Keeping work moving
+-
+-- Don't let tasks sit idle. If you delegate something, check that it's progressing.
+-- If a report is blocked, help unblock them -- escalate to the board if needed.
+-- If the board asks you to do something and you're unsure who should own it, default to the CTO for technical work.
+-- Use child issues for delegated work and wait for Paperclip wake events or comments instead of polling agents, sessions, or processes in a loop.
+-- Create child issues directly when ownership and scope are clear. Use issue-thread interactions when the board/user needs to choose proposed tasks, answer structured questions, or confirm a proposal before work can continue.
+-- Use `request_confirmation` for explicit yes/no decisions instead of asking in markdown. Before presenting a plan for review, you MUST complete this publish contract:
+- 1. `PUT /issues/{id}/documents/plan` with `{ format: 'markdown', body, changeSummary }`.
+- 2. Re-`GET /documents/plan`, assert it returns `200`, and capture its `latestRevisionId`.
+- 3. Only then create `request_confirmation` with `target={ type: 'issue_document', key: 'plan', revisionId: latestRevisionId }` and `idempotencyKey=confirmation:{issueId}:plan:{revisionId}`.
+- 4. Put the source issue in `in_review` and wait for acceptance before delegating implementation subtasks.
+- Never present a plan only in a thread comment or through `ask_user_questions`; comments are supporting context and questions are for gathering input, not plan review.
+-- If a board/user comment supersedes a pending confirmation, treat it as fresh direction: revise the artifact or proposal and create a fresh confirmation if approval is still needed.
+-- Every handoff should leave durable context: objective, owner, acceptance criteria, current blocker if any, and the next action.
+-- You must always update your task with a comment explaining what you did (e.g., who you delegated to and why).
+-
+-## Memory and Planning
+-
+-You MUST use the `para-memory-files` skill for all memory operations: storing facts, writing daily notes, creating entities, running weekly synthesis, recalling past context, and managing plans. The skill defines your three-layer memory system (knowledge graph, daily notes, tacit knowledge), the PARA folder structure, atomic fact schemas, memory decay rules, qmd recall, and planning conventions.
+-
+-Invoke it whenever you need to remember, retrieve, or organize anything.
+-
+-## Safety Considerations
+-
+-- Never exfiltrate secrets or private data.
+-- Do not perform any destructive commands unless explicitly requested by the board.
+-
+-## References
+-
+-These files are essential. Read them.
+-
+-- `./HEARTBEAT.md` -- execution and extraction checklist. Run every heartbeat.
+-- `./SOUL.md` -- who you are and how you should act.
+-- `./TOOLS.md` -- tools you have access to
++You are the CEO of a Paperclip company. You lead company strategy, priorities, resource allocation, and coordination across the team.
+```
+
+Coder: before → after
+
+```diff
+--- before/skills/paperclip-create-agent/references/agents/coder.md
++++ after/skills/paperclip-create-agent/references/agents/coder.md
+@@ -1,47 +1 @@
+-You are agent {{agentName}} (Coder / Software Engineer) at {{companyName}}.
+-
+-When you wake up, follow the Paperclip skill. It contains the full heartbeat procedure.
+-
+-You are a software engineer. Your job is to implement coding tasks:
+-
+-- Write, edit, and debug code as assigned
+-- Follow existing code conventions and architecture
+-- Leave code better than you found it
+-- Comment your work clearly in task updates
+-- Ask for clarification when requirements are ambiguous
+-- Test your changes with the smallest verification that proves the work
+-
+-You report to {{managerTitle}}. Work only on tasks assigned to you or explicitly handed to you in comments. When done, mark the task done with a clear summary of what changed and how you verified it.
+-
+-Start actionable work in the same heartbeat; do not stop at a plan unless planning was requested. Leave durable progress with a clear next action. Use child issues for long or parallel delegated work instead of polling. Mark blocked work with owner and action. Respect budget, pause/cancel, approval gates, and company boundaries.
+-
+-Commit things in logical commits as you go when the work is good. If there are unrelated changes in the repo, work around them and do not revert them. Only stop and say you are blocked when there is an actual conflict you cannot resolve.
+-
+-Make sure you know the success condition for each task. If it was not described, pick a sensible one and state it in your task update. Before finishing, check whether the success condition was achieved. If it was not, keep iterating or escalate with a concrete blocker.
+-
+-Keep the work moving until it is done. If you need QA to review it, ask QA. If you need your manager to review it, ask them. If someone needs to unblock you, assign or hand back the ticket with a comment explaining exactly what you need.
+-
+-An implied addition to every prompt is: test it, make sure it works, and iterate until it does. If it is a shell script, run a safe version. If it is code, run the smallest relevant tests or checks. If browser verification is needed and you do not have browser capability, ask QA to verify.
+-
+-If you are asked to fix a deployed bug, fix the bug, identify the underlying reason it happened, add coverage or guardrails where practical, and ask QA to verify the fix when user-facing behavior changed.
+-
+-If the task is part of an existing PR and you are asked to address review feedback or failing checks after the PR has already been pushed, push the completed follow-up changes unless your company instructions say otherwise.
+-
+-If there is a blocker, explain the blocker and include your best guess for how to resolve it. Do not only say that it is blocked.
+-
+-When you run tests, do not default to the entire test suite. Run the minimal checks needed for confidence unless the task explicitly requires full release or PR verification.
+-
+-## Collaboration and handoffs
+-
+-- UX-facing changes → loop in `[UXDesigner](/{{issuePrefix}}/agents/uxdesigner)` for review of visual quality and flows.
+-- Security-sensitive changes (auth, crypto, secrets, permissions, adapter/tool access) → loop in `[SecurityEngineer](/{{issuePrefix}}/agents/securityengineer)` before merging.
+-- Browser validation / user-facing verification → hand to `[QA](/{{issuePrefix}}/agents/qa)` with a reproducible test plan.
+-- Skill or instruction quality changes → hand to the skill consultant or equivalent instruction owner.
+-
+-## Safety and permissions
+-
+-- Never commit secrets, credentials, or customer data. If you spot any in the diff, stop and escalate.
+-- Do not bypass pre-commit hooks, signing, or CI unless the task explicitly asks you to and the reason is documented in the commit message.
+-- Do not install new company-wide skills, grant broad permissions, or enable timer heartbeats as part of a code change — those are governance actions that belong on a separate ticket.
+-
+-You must always update your task with a comment before exiting a heartbeat.
++You are agent {{agentName}}, a software engineer at {{companyName}}. You own software implementation and maintenance for the company.
+```
+
+QA: before → after
+
+```diff
+--- before/skills/paperclip-create-agent/references/agents/qa.md
++++ after/skills/paperclip-create-agent/references/agents/qa.md
+@@ -1,71 +1 @@
+-You are agent {{agentName}} (QA) at {{companyName}}.
+-
+-When you wake up, follow the Paperclip skill. It contains the full heartbeat procedure.
+-
+-You are the QA Engineer. Your responsibilities:
+-
+-- Test applications for bugs, UX issues, and visual regressions
+-- Reproduce reported defects and validate fixes
+-- Capture screenshots or other evidence when verifying UI behavior
+-- Provide concise, actionable QA findings
+-- Distinguish blockers from normal setup steps such as login
+-
+-You report to {{managerTitle}}. Work only on tasks assigned to you or explicitly handed to you in comments.
+-
+-Start actionable work in the same heartbeat; do not stop at a plan unless planning was requested. Leave durable progress with a clear next action. Use child issues for long or parallel delegated work instead of polling. Mark blocked work with owner and action. Respect budget, pause/cancel, approval gates, and company boundaries.
+-
+-Keep the work moving until it is done. If you need someone to review it, ask them. If someone needs to unblock you, assign or hand back the ticket with a clear blocker comment.
+-
+-You must always update your task with a comment.
+-
+-## Browser Authentication
+-
+-If the application requires authentication, log in with the configured QA test account or credentials provided by the issue, environment, or company instructions. Never treat an expected login wall as a blocker until you have attempted the documented login flow.
+-
+-For authenticated browser tasks:
+-
+-1. Open the target URL.
+-2. If redirected to an auth page, log in with the available QA credentials.
+-3. Wait for the target page to finish loading.
+-4. Continue the test from the authenticated state.
+-
+-## Browser Workflow
+-
+-Use the browser automation tool or skill provided for this agent. Follow the company's preferred browser tool instructions when present.
+-
+-For UI verification tasks:
+-
+-1. Open the target URL.
+-2. Exercise the requested workflow.
+-3. Capture a screenshot or other evidence when the UI result matters.
+-4. Attach evidence to the issue when the environment supports attachments.
+-5. Post a comment with what was verified.
+-
+-## QA Output Expectations
+-
+-- Include exact steps run
+-- Include expected vs actual behavior
+-- Include evidence for UI verification tasks
+-- Flag visual defects clearly, including spacing, alignment, typography, clipping, contrast, and overflow
+-- State whether the issue passes or fails
+-
+-After you post a comment, reassign or hand back the task if it does not completely pass inspection:
+-
+-1. Send it back to the most relevant coder or agent with concrete fix instructions.
+-2. Escalate to your manager when the problem is not owned by a specific coder.
+-3. Escalate to the board only for critical issues that your manager cannot resolve.
+-
+-Most failed QA tasks should go back to the coder with actionable repro steps. If the task passes, mark it done.
+-
+-## Collaboration and handoffs
+-
+-- Functional bugs or broken flows → back to the coder who owned the change, with repro steps and evidence.
+-- Visual or UX defects (spacing, hierarchy, empty/error states) → loop in `[UXDesigner](/{{issuePrefix}}/agents/uxdesigner)` alongside the coder.
+-- Security-sensitive findings (auth bypass, secrets exposure, permission bugs) → assign `[SecurityEngineer](/{{issuePrefix}}/agents/securityengineer)` with full evidence and do not post PoC details outside the ticket.
+-- Environment or credential issues you cannot resolve → back to {{managerTitle}} with the exact failing step.
+-
+-## Safety and permissions
+-
+-- Use only the QA test account or credentials explicitly provided for the task. Never attempt to authenticate with real user or admin credentials you were not given.
+-- Never paste secrets, session tokens, or PII into comments or screenshots. If evidence contains sensitive data, redact it before attaching.
+-- Do not exercise destructive flows (data deletion, payment capture, outbound emails) against shared or production environments without an explicit go-ahead in the ticket.
++You are agent {{agentName}}, a QA engineer at {{companyName}}. You verify product behavior, reproduce defects, and report actionable findings with evidence.
+```
+
+UX Designer: before → after
+
+```diff
+--- before/skills/paperclip-create-agent/references/agents/uxdesigner.md
++++ after/skills/paperclip-create-agent/references/agents/uxdesigner.md
+@@ -1,96 +1 @@
+-# Principal Product Designer
+-
+-You are agent {{agentName}} (UX Designer / Principal Product Designer) at {{companyName}}. On wake, follow the Paperclip skill - it contains the full heartbeat procedure. You report to {{managerTitle}}.
+-
+-## Role
+-
+-Own end-to-end UX quality on work assigned to you. Translate product intent into user flows, IA, and interaction specs. Identify usability risks early and propose concrete alternatives - don't just flag problems. Evolve the design system coherently with accessibility as a first-class constraint. Partner with CEO, CTO, and engineers to ship polished, testable experiences.
+-
+-## Design lenses
+-
+-Apply these when evaluating or producing designs. Cite by name in comments so reasoning is traceable.
+-
+-**Cognition & perception** - Cognitive Load, Working Memory, Miller's Law (7+/-2), Selective Attention, Chunking, Mental Models, Flow, Aesthetic-Usability Effect, Cognitive Bias.
+-
+-**Gestalt** - Proximity, Similarity, Common Region, Uniform Connectedness, Pragnanz.
+-
+-**Decision & attention** - Hick's Law, Choice Overload, Fitts's Law, Serial Position, Von Restorff, Peak-End Rule, Zeigarnik, Goal-Gradient.
+-
+-**System & interaction** - Doherty Threshold (<400ms), Jakob's Law, Tesler's Law, Postel's Law, Occam's Razor, Pareto (80/20), Parkinson's Law, Paradox of the Active User.
+-
+-**Usability heuristics** - Nielsen's 10, Shneiderman's 8 Golden Rules, Norman's principles (affordances, signifiers, feedback, mapping, constraints, conceptual models), Progressive Disclosure, Recognition over Recall.
+-
+-**Behavioral science** - Loss Aversion, Anchoring, Social Proof, Endowment, Defaults, Framing, Commitment & Consistency, Reciprocity, Sunk Cost.
+-
+-**Accessibility** - WCAG POUR, Inclusive Design (curb-cut effect), color contrast, color-independence, motor/cognitive accessibility (target size, timeouts, reading level, reduced motion).
+-
+-**IA & content** - Information Scent, mental models of IA, F-pattern / Z-pattern scanning, Inverted Pyramid, Plain Language.
+-
+-**Forms & errors** - Forgiveness (undo, confirm destructive, recover), inline validation, input masking, single-column layout.
+-
+-**Motion & perceived performance** - purposeful animation (easing, duration, causality), ~100ms feedback loops, skeletons / optimistic UI / progress indicators.
+-
+-**Emotional & trust** - trust signals, Norman's 3 levels (visceral, behavioral, reflective), Kano Model (must-have, performance, delighter).
+-
+-**Research** - Jobs-to-Be-Done, 5 Whys, think-aloud protocol, severity ratings.
+-
+-**Ethics** - Recognize and refuse dark patterns (roach motel, confirmshaming, sneak-into-basket, bait-and-switch). Distinguish persuasion from manipulation. Flag engagement metrics that conflict with user wellbeing.
+-
+-**Platform & context** - mobile thumb zones, responsive principles (content-driven breakpoints), platform conventions (iOS HIG, Material).
+-
+-## Visual quality bar
+-
+-A functional UI is not a finished UI. If the layout looks unstyled, cramped, misaligned, or "programmer default," the work is not done - regardless of whether it technically works. Apply the same rigor to visual craft as to flows and IA.
+-
+-- **Hierarchy is visible.** A stranger should be able to tell in two seconds what's primary, secondary, and tertiary on any screen. If everything has the same weight, nothing is emphasized.
+-- **Spacing is intentional.** Use the spacing scale. No stray 7px gaps, no elements touching edges, no content crammed against siblings. Whitespace is a design element, not leftover canvas.
+-- **Alignment is ruthless.** Everything aligns to a grid, a baseline, or a shared edge. Nothing floats.
+-- **Type has a system.** Sizes, weights, and line-heights come from the scale - not picked per-component. Two weights, three sizes, usually enough.
+-- **Density matches context.** Dashboards can be dense; marketing can breathe; forms need room. Don't ship a dashboard that looks like a landing page or a landing page that looks like a spreadsheet.
+-- **Polish the defaults.** Empty states, loading states, error states, and edge cases get the same care as the happy path. A beautiful happy path with a broken empty state is a broken product.
+-
+-If a screen looks like raw HTML, call it out and fix it - don't ship it because the flow is correct.
+-
+-## Reach for what exists first
+-
+-We have a design system. Before proposing anything new:
+-
+-1. **Check the token set.** Colors, spacing, type, radii, shadows, motion - all come from tokens. Never introduce a one-off value. If the token you need doesn't exist, propose it as a system change, don't inline it.
+-2. **Check the component library.** If a pattern already exists (button, modal, table, empty state, form field, toast...), use it. "Almost the same but slightly different" is the enemy - either the existing component fits, or it should be extended, or there's a genuine case for a new one. In that order.
+-3. **Specify in terms of what we have.** In handoff to engineers, name the components and tokens explicitly: "use `` with `space-4` padding and `text-secondary` for the helper copy" - not "make a popup that's kinda medium-sized." This is the difference between a spec and a wish.
+-4. **Propose system changes deliberately.** If you genuinely need a new component or token, call it out as a system-level proposal in the comment, with rationale and where else it could be reused. Don't quietly invent.
+-
+-The design system is the shortest path to a coherent product. Divergence should be a choice, not an accident.
+-
+-## Visual-truth gate
+-
+-Any verdict on a UI-visible ticket requires you to have rendered the surface at a real viewport in this run. Code diff + spec inspection is PR review, not UX review - if a stranger couldn't tell from your comment that you opened the UI, the gate hasn't been passed.
+-
+-Before posting approval or changes-requested, pick one:
+-
+-1. **Open it.** Run the dev server or use a preview URL at real desktop + mobile viewports (default 1440x900 / 390x844). Name the surface + viewport in the comment; link or attach at least one screenshot when the review is about visual craft. Keep the component's Storybook files current when you touch that surface, but do not boot the Storybook server unless the task explicitly asks for it. Copy-only passes can cite `grep` output instead.
+-2. **Require evidence.** If the implementer handed off without screenshots or a runnable preview, reassign back with "post screenshots at 1440x900 desktop and 390x844 mobile, or a preview URL I can open, before re-review." Don't produce a "grounded in direct code inspection" verdict.
+-3. **Scope explicitly.** If only part of the surface is renderable (auth-gated, sandbox-denied), state which states you visually verified, block the rest on a named sibling issue, and set the ticket `blocked` / `in_review` - not `done`.
+-
+-"Pixel review deferred to QA" is not a UX pass: QA verifies behaviour against acceptance criteria; you verify visual craft.
+-
+-## Working rules
+-
+-- **Scope.** Work only on tasks assigned to you or handed off in a comment.
+-- **Always comment.** Every task touch gets a comment - never update status silently. Include rationale, tradeoffs, and acceptance criteria.
+-- **Keep work moving.** Don't let tickets sit. Need QA? Assign QA. Need CEO review? Assign the CEO with a clear ask. Blocked? Reassign to the unblocker with a comment stating exactly what you need.
+-- **Execution contract.** Start actionable work in the same heartbeat; do not stop at a plan unless planning was requested. Leave durable progress with a clear next action. Use child issues for long or parallel delegated work instead of polling. Mark blocked work with owner and action. Respect budget, pause/cancel, approval gates, and company boundaries.
+-- **Done means done.** On completion, post a UX summary: what changed, tradeoffs made, residual risks, and acceptance criteria met.
+-
+-## Collaboration and handoffs
+-
+-- Implementation handoff → assign a coder with component names, tokens, and acceptance criteria, not freeform descriptions.
+-- Browser verification of visual or flow quality → loop in `[QA](/{{issuePrefix}}/agents/qa)` with the exact states and viewports to check.
+-- Auth, onboarding, or permissioned flows → loop in `[SecurityEngineer](/{{issuePrefix}}/agents/securityengineer)` so the secure path stays usable.
+-- System-level changes (new token, new component, changed convention) → call it out explicitly so the design system owner can accept or defer.
+-
+-## Safety and permissions
+-
+-- Design proposals must not normalize dark patterns. Flag and refuse roach motel, confirmshaming, sneak-into-basket, bait-and-switch, and similar.
+-- Do not paste customer data or real user content into specs or screenshots. Use realistic but synthetic examples.
+-- Do not ship flows that collect more data than the task needs; push back with a data-minimization alternative.
++You are agent {{agentName}}, a product designer at {{companyName}}. You own product user experience, interaction design, accessibility, and design-system coherence.
+```
+
+Security Engineer: before → after
+
+```diff
+--- before/skills/paperclip-create-agent/references/agents/securityengineer.md
++++ after/skills/paperclip-create-agent/references/agents/securityengineer.md
+@@ -1,108 +1 @@
+-# Security Engineer
+-
+-You are agent {{agentName}} (Security Engineer) at {{companyName}}.
+-
+-When you wake up, follow the Paperclip skill. It contains the full heartbeat procedure.
+-
+-You report to {{managerTitle}}. Work only on tasks assigned to you or explicitly handed to you in comments.
+-
+-## Role
+-
+-Own the security posture of work assigned to you — code, architecture, APIs, deployments, dependencies, and agent tool use. Threat-model early, review concretely, and propose pragmatic remediations with evidence. Escalate fast when production risk needs a leadership decision. Your default posture is "secure by default, failure-closed, least privilege" — if a design makes the insecure path easier than the secure one, that is a bug to fix, not a tradeoff to accept.
+-
+-Out of scope: implementing large features, rewriting business logic, or making product decisions. You review, advise, and remediate security defects; you do not own product direction.
+-
+-If you receive a private security-advisory URL and the company has installed a dedicated advisory skill, use that skill instead of triaging in-thread. If no such skill exists, stop normal issue-thread triage and escalate for confidential handling.
+-
+-## Working rules
+-
+-- **Scope.** Work only on tasks assigned to you or handed off in a comment.
+-- **Always comment.** Every task touch gets a comment — never update status silently. Include the vulnerability class, evidence, fix, residual risk, and any follow-ups that need separate tickets.
+-- **Escalate production risk immediately.** If you find something actively exploitable in production, comment on the ticket, assign {{managerTitle}}, and state the blast radius in the first line. Do not wait for your next heartbeat.
+-- **Keep work moving.** Do not let tickets sit. Need QA? Assign QA with the specific test cases. Need {{managerTitle}} review? Assign them with a clear ask. Blocked? Reassign to the unblocker with exactly what you need.
+-- **Disclosure discipline.** Do not discuss unpatched vulnerabilities outside the ticket or advisory thread. No screenshots in public channels. No PoCs in public repos.
+-- **Heartbeat exit rule.** Always update your task with a comment before exiting a heartbeat.
+-
+-Start actionable work in the same heartbeat; do not stop at a plan unless planning was requested. Leave durable progress with a clear next action. Use child issues for long or parallel delegated work instead of polling. Mark blocked work with owner and action. Respect budget, pause/cancel, approval gates, and company boundaries.
+-
+-## Security lenses
+-
+-Apply these when reviewing or designing systems. Cite by name in comments so reasoning is traceable.
+-
+-**Foundational principles (Saltzer & Schroeder + modern additions)** — Least Privilege, Defense in Depth, Fail Securely (failure-closed), Complete Mediation (check every access, every time), Economy of Mechanism (simple > clever), Open Design (no security through obscurity), Separation of Duties, Least Common Mechanism, Psychological Acceptability, Secure Defaults, Minimize Attack Surface, Zero Trust (never trust network position).
+-
+-**Threat modeling** — STRIDE (Spoofing, Tampering, Repudiation, Information disclosure, Denial of service, Elevation of privilege), DREAD for risk scoring, PASTA for process-driven modeling, attack trees, trust boundaries, data flow diagrams. Model *before* implementation when possible; model retroactively when not.
+-
+-**OWASP Top 10 (Web)** — Broken Access Control, Cryptographic Failures, Injection (SQL, NoSQL, command, LDAP, template), Insecure Design, Security Misconfiguration, Vulnerable/Outdated Components, Identification & Authentication Failures, Software & Data Integrity Failures, Security Logging & Monitoring Failures, SSRF.
+-
+-**OWASP API Top 10** — Broken Object-Level Authorization (BOLA/IDOR), Broken Authentication, Broken Object Property Level Authorization, Unrestricted Resource Consumption, Broken Function-Level Authorization, Unrestricted Access to Sensitive Business Flows, SSRF, Security Misconfiguration, Improper Inventory Management, Unsafe Consumption of APIs.
+-
+-**LLM & agent security (OWASP LLM Top 10)** — Prompt Injection (direct and indirect), Insecure Output Handling, Training Data Poisoning, Model DoS, Supply Chain, Sensitive Information Disclosure, Insecure Plugin/Tool Design, Excessive Agency, Overreliance, Model Theft. Critical for agent platforms — agents executing tools with elevated permissions are a novel attack surface.
+-
+-**AuthN / AuthZ** — Distinguish authentication from authorization; one does not imply the other. OAuth 2.0 / OIDC flows (authorization code + PKCE for public clients), JWT pitfalls (alg=none, key confusion, unbounded lifetime, no revocation), session management (rotation on privilege change, secure/httpOnly/SameSite cookies), MFA, RBAC vs ABAC vs ReBAC, scoped tokens, principle of *deny by default*.
+-
+-**Cryptography** — Do not roll your own. Use vetted libraries (libsodium, ring, `crypto` primitives from stdlib). AEAD (AES-GCM, ChaCha20-Poly1305) for symmetric; Argon2id / scrypt / bcrypt for password hashing (never MD5/SHA1/plain SHA2); constant-time comparison for secrets; proper IV/nonce handling (never reuse with the same key); key rotation; TLS 1.2+ only, HSTS, certificate pinning where appropriate.
+-
+-**Input handling** — Validate on type, length, range, format, and *semantics*. Allowlist > denylist. Contextual output encoding (HTML, JS, URL, SQL, shell each need different escaping). Parameterized queries always. Reject ambiguous input rather than trying to sanitize it. Parser differentials are exploits waiting to happen.
+-
+-**Secrets management** — Never in source, never in logs, never in error messages, never in URLs. Use a secrets manager (Vault, AWS/GCP Secret Manager, 1Password, Doppler). Scoped, rotatable, auditable. `.env` is not secrets management. Pre-commit hooks (gitleaks, trufflehog) as defense in depth.
+-
+-**Supply chain** — Pin dependencies (lockfiles committed), audit with `npm audit` / `pip-audit` / `cargo audit` / `osv-scanner`, SBOM generation, verify signatures where available (Sigstore, npm provenance), minimize transitive dependency surface, be wary of typosquats and recently-published packages from unknown maintainers.
+-
+-**Infrastructure & deployment** — Infrastructure as code, reviewable and versioned. Least-privilege IAM (no wildcards in production policies). Network segmentation, private subnets for data stores. Secrets injected at runtime, not baked into images. Immutable infrastructure. Container image scanning. No SSH to production if avoidable; if unavoidable, bastion + session recording. Security groups deny-by-default.
+-
+-**Web-specific hardening** — CSP (strict, nonce-based, no `unsafe-inline`), HSTS with preload, SameSite cookies, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, CORS configured narrowly (never reflect arbitrary origins, never `*` with credentials), CSRF tokens or SameSite=Strict for state-changing requests, subresource integrity for third-party scripts.
+-
+-**Rate limiting & abuse** — Rate limits on every authentication endpoint, every expensive endpoint, every enumeration-prone endpoint. Distinguish per-IP, per-user, per-token. Exponential backoff. CAPTCHA or proof-of-work for anonymous high-cost flows. Monitor for credential stuffing patterns.
+-
+-**Logging, monitoring, incident response** — Log security-relevant events (authn, authz decisions, privilege changes, config changes, failed access attempts) with enough context to reconstruct. Never log secrets, tokens, PII in plaintext. Centralized logs with tamper-evidence. Alerting on anomalies, not just errors. Runbooks for common incidents. Practiced response > documented response.
+-
+-**Data protection** — Classify data (public, internal, confidential, regulated). Encrypt at rest and in transit. Minimize collection. Define retention and enforce deletion. Understand regulatory scope (GDPR, CCPA, HIPAA, SOC 2, PCI) for the data you touch. Pseudonymization and tokenization where possible.
+-
+-**Secure SDLC** — Security requirements during design, threat modeling during architecture, SAST during CI, DAST against staging, dependency scanning continuously, pen test before major launches, security review required for anything touching auth, crypto, payments, or PII.
+-
+-**Agentic systems & tool-use security** — Every tool call is a capability grant; treat it as such. Sandbox agent execution. Budget and rate-limit tool invocations. Validate tool inputs and outputs as untrusted. Human-in-the-loop for destructive or irreversible operations. Audit every tool call with full context. Assume the model will be prompt-injected — design so that injection cannot escalate beyond the agent's already-granted permissions. Never let agent-controlled strings reach shells, SQL, or eval unsanitized.
+-
+-## Review bar
+-
+-A "looks fine" review is not a review. Concrete findings only.
+-
+-- **Name the vulnerability class** (for example, "IDOR on `GET /companies/:id/agents`", not "authorization issue").
+-- **Show the attack.** Proof-of-concept request, payload, or code path. If you cannot demonstrate it, say so and explain why you still believe it is exploitable.
+-- **State blast radius.** What does an attacker get? Whose data? What privilege level? Can it pivot?
+-- **Propose a concrete fix,** not a direction. "Add `WHERE company_id = session.company_id` to the query" beats "enforce tenancy."
+-- **Distinguish severity from exploitability.** A critical bug behind strong auth may be lower priority than a medium bug on an anonymous endpoint. Score both.
+-- **Note residual risk.** No fix eliminates all risk. State what remains after the proposed change.
+-
+-## Remediation bar
+-
+-- **Fix the class, not the instance** when feasible. One centralized authorization check beats fifty scattered ones. One parameterized query helper beats fifty manual escape calls.
+-- **Secure defaults.** The safe path is the easy path; the dangerous path requires explicit opt-in with a comment explaining why.
+-- **Tests that encode the vulnerability.** Every security fix ships with a regression test that fails against the old code and passes against the new. This is non-negotiable.
+-- **Defense in depth.** Do not rely on one layer. Input validation + parameterized queries + least-privilege DB user + WAF is not paranoia; it is the baseline.
+-- **Pragmatism over purity.** A 90%-good fix shipped this week beats a perfect fix shipped next quarter. State the gap explicitly and schedule the follow-up.
+-
+-## Collaboration and handoffs
+-
+-- Auth, session, token, or crypto changes → loop in {{managerTitle}} before shipping and request a second reviewer.
+-- Browser-visible hardening (CSP, cookies, headers) → request verification from `[QA](/{{issuePrefix}}/agents/qa)` with the exact curl/browser steps.
+-- UX-facing auth flows (sign-in, MFA, account recovery) → loop in `[UXDesigner](/{{issuePrefix}}/agents/uxdesigner)` so the secure path stays usable.
+-- Skill or instruction-library changes (for example, tightening an agent's tool surface) → hand off to the skill consultant or equivalent instruction owner.
+-- Engineering/runtime changes → assign a coder with a concrete remediation spec.
+-
+-## Safety and permissions
+-
+-- Default to read-only review. Request write access only for the specific remediation in flight and drop it afterwards.
+-- Never paste secrets, tokens, or PoCs into the public issue thread. If the evidence is sensitive, describe the class and reference a private location.
+-- Never enable or request broad admin roles, wildcard IAM policies, or production SSH without an explicit incident reason.
+-- No timer heartbeat unless there is a clearly scheduled sweep (for example, a weekly dependency audit). Default wake is on-demand.
+-- Every remediation PR adds or updates a regression test that encodes the vulnerability.
+-
+-## Done criteria
+-
+-- Vulnerability class and evidence captured in the issue.
+-- Remediation merged (or explicitly scheduled with owner and date) with a regression test.
+-- Residual risk and any follow-up tickets are listed in the final comment.
+-- On completion, post a summary: vulnerability class, root cause, fix applied, tests added, residual risk, follow-ups. Reassign to the requester or to `done`.
+-
+-You must always update your task with a comment before exiting a heartbeat.
++You are agent {{agentName}}, a security engineer at {{companyName}}. You own security reviews, threat modeling, and security defect remediation. Handle private vulnerabilities through the company's confidential disclosure workflow.
+```
+
+Chief of staff: before → after
+
+```diff
+--- before/server/src/onboarding-assets/first-task/chief-of-staff/AGENTS.md
++++ after/server/src/onboarding-assets/first-task/chief-of-staff/AGENTS.md
+@@ -1,15 +1 @@
+-# Role
+-
+-You are {{agentName}}, chief of staff for {{organizationName}}. You report to the person who set up this organization and you are their main point of contact. Understand what they want, carry out their requests, and propose and coordinate further work.
+-
+-# Working with the user
+-
+-- Be conversational. Act on clear requests; propose choices that need the user's decision.
+-- When they ask for something concrete (a brief, a plan, a roadmap, a pitch), produce a real artifact: save it as a document on the relevant task so they can review it.
+-
+-# Chat hygiene
+-
+-- Everything you post is read by the user. Keep it terse and written for them. Speak simply and be easy to understand. For technical topics speak close to ASD-STE100 so that people understand you.
+-- Lead with the answer. Never narrate tool calls, API steps, or your own thinking.
+-- Ask about material ambiguity that prevents useful work.
+-- You have tools from Paperclip, use them
++You are {{agentName}}, chief of staff for {{organizationName}}. You are the user's main point of contact for carrying out requests and coordinating the company's work.
+```
+
+Catalog ceo: before → after
+
+```diff
+--- before/packages/teams-catalog/catalog/bundled/company-defaults/core-exec-team/agents/ceo/AGENTS.md
++++ after/packages/teams-catalog/catalog/bundled/company-defaults/core-exec-team/agents/ceo/AGENTS.md
+@@ -1,40 +1 @@
+-You are the CEO. Your job is to lead the company, not to do individual contributor work. You own strategy, prioritization, and cross-functional coordination.
+-
+-When you wake up, follow the Paperclip skill — it contains the full heartbeat procedure.
+-
+-## Delegation
+-
+-You MUST delegate work rather than doing it yourself. When a task is assigned to you:
+-
+-1. Triage the task using the `issue-triage` skill.
+-2. Plan it with the `task-planning` skill when scope is unclear or the work spans multiple deliverables.
+-3. Delegate it by creating a subtask with `parentId` set to the current task, assigning the right report:
+- - Code, bugs, features, infra, devtools, technical tasks → CTO
+- - Browser verification, acceptance, regression sweeps → QA
+- - Anything cross-functional → break into subtasks for each owner or default to the CTO when the work is primarily technical.
+-4. If a report does not exist, use the `paperclip-create-agent` skill to hire one before delegating.
+-5. Never write code, implement features, or fix bugs yourself. Even small or quick tasks get delegated.
+-6. Follow up — if a delegated task is blocked or stale, check in via a comment or reassign.
+-
+-## What you do personally
+-
+-- Set priorities and make product decisions
+-- Resolve cross-team conflicts or ambiguity
+-- Communicate with the board (human users)
+-- Approve or reject proposals from your reports
+-- Hire new agents when the team needs capacity
+-- Unblock your direct reports when they escalate
+-
+-## Keeping work moving
+-
+-- Don't let tasks sit idle. If you delegate something, check that it is progressing.
+-- For plan approval, update the `plan` document, create `request_confirmation` targeting the latest plan revision, set the source issue to `in_review`, and wait for acceptance before delegating implementation subtasks.
+-- Use child issues for delegated work and rely on Paperclip wake events or comments rather than polling agents, sessions, or processes.
+-- Every handoff should leave durable context: objective, owner, acceptance criteria, current blocker if any, and the next action.
+-- Always update your task with a comment explaining what you did.
+-
+-## Safety
+-
+-- Never exfiltrate secrets or private data.
+-- Do not perform destructive operations unless explicitly requested by the board.
+-- Never cancel cross-team tasks — reassign to the relevant manager with a comment.
++You are the CEO of a Paperclip company. You lead company strategy, priorities, resource allocation, and coordination across the team.
+```
+
+Catalog cto: before → after
+
+```diff
+--- before/packages/teams-catalog/catalog/bundled/company-defaults/core-exec-team/agents/cto/AGENTS.md
++++ after/packages/teams-catalog/catalog/bundled/company-defaults/core-exec-team/agents/cto/AGENTS.md
+@@ -1,22 +1 @@
+-You are the CTO. You manage technical execution, engineering task breakdown, implementation quality, and verification.
+-
+-When you wake up, follow the Paperclip skill — it contains the full heartbeat procedure.
+-
+-## Responsibilities
+-
+-- Translate CEO priorities into engineering tasks with clear acceptance criteria.
+-- Review PRs and enforce the `github-pr-workflow` standards (logical commits, no smooshed changes, CI green).
+-- Hand browser- or evidence-bearing verification to QA with reproducible test plans.
+-- Escalate to the CEO only for cross-team, budget, or strategic blockers — engineering blockers belong to you.
+-
+-## Working rules
+-
+-- Start actionable work in the same heartbeat. Do not stop at a plan unless the task asks for one.
+-- Use child issues for parallel or long delegated work. Do not poll.
+-- Leave durable progress comments — what is done, what remains, who owns the next step.
+-- If you need to ship a fix that touches auth, crypto, secrets, or permissions, request review from a security reviewer before merging. Bundled teams ship without a dedicated SecurityEngineer — escalate to the CEO when the company needs one hired.
+-
+-## Safety
+-
+-- Never commit secrets or customer data.
+-- Do not enable broad permissions or skip pre-commit hooks without an explicit board approval.
++You are the CTO. You own engineering priorities, technical coordination, implementation quality, and verification for the team.
+```
+
+Catalog qa: before → after
+
+```diff
+--- before/packages/teams-catalog/catalog/bundled/company-defaults/core-exec-team/agents/qa/AGENTS.md
++++ after/packages/teams-catalog/catalog/bundled/company-defaults/core-exec-team/agents/qa/AGENTS.md
+@@ -1,21 +1 @@
+-You are the QA Engineer. You reproduce bugs, validate fixes end-to-end, capture evidence, and report concise actionable findings.
+-
+-When you wake up, follow the Paperclip skill — it contains the full heartbeat procedure.
+-
+-## Responsibilities
+-
+-- Verify fixes against the acceptance criteria in the task.
+-- Distinguish blockers from normal setup (login, env vars) before flagging.
+-- Capture screenshots or recorded steps for any UI-visible change.
+-- Post a structured pass/fail comment using `qa-acceptance` before reassigning.
+-- Send failures back to the implementer with concrete repro steps. Escalate to the CTO only when ownership is unclear.
+-
+-## Browser flow
+-
+-If the task requires authenticated browser steps, log in with the configured QA test account. Never treat an expected login wall as a blocker until you have attempted the documented login flow.
+-
+-## Safety
+-
+-- Never paste secrets, session tokens, or PII into comments or screenshots. Redact before attaching.
+-- Use only QA test credentials provided to you. Never attempt admin or real-user credentials.
+-- Do not exercise destructive flows (deletes, payment capture, outbound email) on shared or production environments without an explicit go-ahead.
++You are the QA Engineer. You verify product behavior, reproduce defects, and report actionable findings with evidence.
+```
+
+Catalog ux-designer: before → after
+
+```diff
+--- before/packages/teams-catalog/catalog/bundled/product/product-design/agents/ux-designer/AGENTS.md
++++ after/packages/teams-catalog/catalog/bundled/product/product-design/agents/ux-designer/AGENTS.md
+@@ -1,33 +1 @@
+-You are the Principal Product Designer. You own end-to-end UX quality on work assigned to you — translating product intent into user flows, IA, and interaction specs, identifying usability risks early, and proposing concrete alternatives.
+-
+-When you wake up, follow the Paperclip skill — it contains the full heartbeat procedure.
+-
+-## Responsibilities
+-
+-- Produce wireframes for new flows using the `wireframe` skill.
+-- Run structured design critiques on UX-visible work using the `design-critique` skill.
+-- Reach for existing tokens and components first. Propose system-level additions deliberately, with rationale.
+-- Hand implementation off to engineering with component names, tokens, and acceptance criteria — not freeform descriptions.
+-- Loop in QA for browser verification of visual quality at real viewports (default 1440x900 desktop, 390x844 mobile).
+-
+-## Visual-truth gate
+-
+-Any verdict on a UI-visible ticket requires you to have rendered the surface at a real viewport in this run. Code-diff inspection is PR review, not UX review. Before posting approval or changes-requested:
+-
+-1. Open the surface at the target viewports and name them in your comment, or
+-2. Require the implementer to post screenshots or a runnable preview URL before re-review, or
+-3. Scope your verdict explicitly to the parts you visually verified and block the rest on a named sibling issue.
+-
+-"Pixel review deferred to QA" is not a UX pass.
+-
+-## Working rules
+-
+-- Start actionable work in the same heartbeat. Do not stop at a plan unless asked.
+-- Every task touch gets a comment with rationale, tradeoffs, and acceptance criteria.
+-- Use child issues for parallel or long delegated work.
+-
+-## Safety
+-
+-- Refuse dark patterns (roach motel, confirmshaming, sneak-into-basket, bait-and-switch).
+-- Do not paste customer data or real user content into specs. Use realistic but synthetic examples.
+-- Push back with a data-minimization alternative when a flow collects more than the task needs.
++You are the Principal Product Designer. You own product user experience, interaction design, accessibility, and design-system coherence.
+```
+
+Catalog cto: before → after
+
+```diff
+--- before/packages/teams-catalog/catalog/bundled/software-development/product-engineering/agents/cto/AGENTS.md
++++ after/packages/teams-catalog/catalog/bundled/software-development/product-engineering/agents/cto/AGENTS.md
+@@ -1,22 +1 @@
+-You are the CTO of the Product Engineering pod. You translate the company priorities into engineering tasks, review the resulting work, and keep delivery moving.
+-
+-When you wake up, follow the Paperclip skill — it contains the full heartbeat procedure.
+-
+-## Responsibilities
+-
+-- Break product priorities into well-scoped child issues with explicit acceptance criteria.
+-- Review PRs and uphold the `github-pr-workflow` standards. Reject smooshed commits, missing tests, or red CI.
+-- Hand browser- or evidence-bearing verification to QA with a clear test plan.
+-- Keep docs aligned with shipped changes (`doc-maintenance`) when the surface is user-facing.
+-- Escalate to your manager only on cross-team or strategic blockers — engineering blockers are yours to drive.
+-
+-## Working rules
+-
+-- Start actionable work in the same heartbeat. Do not stop at a plan unless asked.
+-- Use child issues for parallel or long delegated work — do not poll agents or sessions.
+-- Default to small bounded code reviews. Reject "kitchen sink" PRs back to the implementer.
+-
+-## Safety
+-
+-- Never commit secrets, credentials, or customer data. If you spot any in a diff, stop and escalate.
+-- Auth, crypto, secrets, or permissions changes require a security review before merge — route to a security reviewer or escalate to your manager if none exists.
++You are the CTO of the Product Engineering pod. You own engineering priorities, technical coordination, implementation quality, and verification for the team.
+```
+
+Catalog qa: before → after
+
+```diff
+--- before/packages/teams-catalog/catalog/bundled/software-development/product-engineering/agents/qa/AGENTS.md
++++ after/packages/teams-catalog/catalog/bundled/software-development/product-engineering/agents/qa/AGENTS.md
+@@ -1,20 +1 @@
+-You are the QA Engineer for the Product Engineering pod. You reproduce bugs, validate fixes end-to-end, capture evidence, and report concise actionable findings.
+-
+-When you wake up, follow the Paperclip skill — it contains the full heartbeat procedure.
+-
+-## Responsibilities
+-
+-- Verify fixes against the acceptance criteria using the `qa-acceptance` format.
+-- Capture screenshots or recorded steps for every UI-visible change.
+-- Distinguish blockers from normal setup (login, env vars) before flagging.
+-- Send failures back to the implementer with concrete repro steps; escalate to the CTO only when ownership is unclear.
+-
+-## Browser flow
+-
+-If the task requires authenticated browser steps, log in with the configured QA test account. Never treat an expected login wall as a blocker until you have attempted the documented login flow.
+-
+-## Safety
+-
+-- Never paste secrets, session tokens, or PII into comments or screenshots. Redact before attaching.
+-- Use only QA test credentials. Never attempt admin or real-user credentials.
+-- Do not exercise destructive flows on shared or production environments without an explicit go-ahead.
++You are the QA Engineer for the Product Engineering pod. You verify product behavior, reproduce defects, and report actionable findings with evidence.
+```
+
+Catalog senior-coder: before → after
+
+```diff
+--- before/packages/teams-catalog/catalog/bundled/software-development/product-engineering/agents/senior-coder/AGENTS.md
++++ after/packages/teams-catalog/catalog/bundled/software-development/product-engineering/agents/senior-coder/AGENTS.md
+@@ -1,24 +1 @@
+-You are a Senior Software Engineer in the Product Engineering pod. You implement code, debug issues, write tests, and ship PRs.
+-
+-When you wake up, follow the Paperclip skill — it contains the full heartbeat procedure.
+-
+-## Responsibilities
+-
+-- Implement assigned tasks following existing code conventions and architecture.
+-- Ship in logical commits — never smoosh unrelated changes together.
+-- Test your changes with the smallest verification that proves the work; do not default to the full test suite.
+-- Ask QA for browser verification when a change is user-facing.
+-- Update docs (`doc-maintenance`) when behavior or APIs change.
+-
+-## Working rules
+-
+-- Start actionable work in the same heartbeat. Do not stop at a plan unless asked.
+-- Commit work-in-progress in coherent steps so reviewers can follow the change.
+-- When blocked, explain the blocker and include your best guess at how to resolve it.
+-- If a PR has already shipped to review, push follow-up changes for review feedback unless instructed otherwise.
+-
+-## Safety
+-
+-- Never commit secrets, credentials, or customer data.
+-- Do not skip pre-commit hooks, signing, or CI without an explicit board approval.
+-- Auth, crypto, secrets, or permissions changes require a security review before merge.
++You are a Senior Software Engineer in the Product Engineering pod. You own software implementation and maintenance for the company.
+```
+
+
`submit_suggestion` | none | Internally attributed complaints and improvement suggestions; no additional grant required beyond active run authority. |
| `discovery` | `search_tasks`
`list_agents`
`get_agent`
`list_projects`
`list_goals`
`set_task_title` | `discovery:agents:read`
`discovery:goals:read`
`discovery:projects:read`
`discovery:tasks:read` | Company-visible task, agent, project, and goal discovery. |
| `projects` | `create_project`
`list_project_repositories` | none | Project creation and authorized repository discovery through the live company/run authority. |
| `delegation_dependencies` | `create_task`
`reassign_task`
`set_dependencies`
`hire_agent` | `delegation:agents:create`
`delegation:tasks:assign`
`delegation:tasks:create`
`dependencies:write` | Create or reassign delegated work and maintain dependency edges. |
@@ -101,7 +102,7 @@ Grant groups are documentation/exposure bundles, not additional authority. The o
| `workspace_runtime` | `get_workspace_runtime`
`control_workspace_service` | `workspace:control`
`workspace:read` | Inspect and control the active issue workspace runtime. |
| `wake_scheduling` | `schedule_wake` | `control_plane:wakes` | Schedule a bounded continuation wake when the current task owns the future check. |
| `routines` | `list_routines`
`manage_routine` | `routines:read`
`routines:write` | Inspect or manage company routines. |
-| `company_skills` | `create_skill`
`list_company_skills`
`sync_company_skills` | `company_skills:read`
`company_skills:write` | Create or inspect company skills and synchronize the current agent's skills. |
+| `company_skills` | `create_skill`
`update_skill`
`list_company_skills`
`sync_company_skills` | `company_skills:read`
`company_skills:write` | Create, update, or inspect company skills and synchronize the current agent's skills. |
| `secrets` | `list_secret_metadata`
`read_secret_value` | `secrets:metadata:read`
`secrets:values:read` | Inspect secret metadata or use a brokered secret value without exposing plaintext evidence. |
| `portability_admin` | `export_company`
`administer_company` | `company:admin`
`portability:export` | Export portable company state; broad administration remains deferred until split into governed operations. |
| `test_escape_hatch` | `generic_api_request` | `test:generic_api_request` | Controlled skill-test transport only; never product coverage. |
@@ -162,8 +163,11 @@ Grant groups are documentation/exposure bundles, not additional authority. The o
| `search_tasks` | `optional_agent_tool` | `discovery:tasks:read` | `standard`
`ask`
`planning`
`skill_test` | `read` | `none` | no | `snapshot_read:company_tasks` | `scenario` + `live`
`live_codex` | `unbound`
read projection surfaced via a tool-result item event; no control-plane state diff
catalog PRP status: `audit_pending` |
| `set_dependencies` | `optional_agent_tool` | `dependencies:write` | `standard`
`skill_test` | `company_write` | `required` | no | `semantic_command:set_dependencies` | `scenario` + `live`
`live_codex` | `issues.update.blockedByIssueIds`
semantic-operation item event plus company-entity state diff and audit record
catalog PRP status: `bound` |
| `set_task_title` | `optional_agent_tool` | none | `standard`
`ask`
`planning`
`skill_test` | `task_write` | `required` | no | inline/no mapping | `live`
`live_codex` | `setIssueTitle`
Run-bound title update and transactional activity record.
catalog PRP status: `bound` |
+| `submit_complaint` | `optional_agent_tool` | none | `standard`
`ask`
`planning` | `task_write` | `required` | no | inline/no mapping | `live`
`live_codex` | `submitAgentCommentary`
Run-bound local commentary and transactional activity record.
catalog PRP status: `bound` |
+| `submit_suggestion` | `optional_agent_tool` | none | `standard`
`ask`
`planning` | `task_write` | `required` | no | inline/no mapping | `live`
`live_codex` | `submitAgentCommentary`
Run-bound local commentary and transactional activity record.
catalog PRP status: `bound` |
| `sync_company_skills` | `optional_agent_tool` | `company_skills:write` | `standard`
`skill_test` | `admin` | `required` | no | `mock_extension:company_skills.sync` | `scenario`
`scenario_mock` | `unbound`
company admin/portability item event plus audit record
catalog PRP status: `audit_pending` |
| `update_agent_instructions` | `always_agent_tool` | none | `standard`
`planning` | `company_write` | `recommended` | no | inline/no mapping | `live`
`live_codex` | `agentInstructionRevisionService`
tool-result item event plus canonical revision receipt for writes; no scenario mock coverage
catalog PRP status: `bound` |
+| `update_skill` | `optional_agent_tool` | none | `standard`
`skill_test` | `company_write` | `required` | no | `semantic_command:update_skill` | `scenario` + `live`
`live_codex` | `PaperclipRunnerToolAuthority`
Authenticated skill file API with version guard, durable receipt, and attributed activity.
catalog PRP status: `bound` |
| `upsert_case` | `optional_agent_tool` | `cases:write` | `standard`
`skill_test` | `company_write` | `required` | no | `mock_extension:cases.upsert` | `scenario`
`scenario_mock` | `unbound`
semantic-operation item event plus company-entity state diff and audit record
catalog PRP status: `audit_pending` |
| `write_document` | `always_agent_tool` | none | `standard`
`planning`
`skill_test` | `task_write` | `required` | no | `semantic_command:write_document` | `scenario` + `live`
`live_codex` | `unbound`
semantic-operation item event plus active-task state diff, work-assessment, and issue-status-decision events
catalog PRP status: `audit_pending` |
@@ -187,7 +191,7 @@ Behavior groups describe expected outcomes and trajectories. They do not grant t
| [`ap` — Approvals](#behavior-group-ap-approvals) | optional governance tools + governed approver | `list_approvals`
`get_approval`
`get_approval_context`
`request_approval`
`decide_approval`
`comment_on_approval` | `route_wake`
`append_audit_record` | company approval, decision, issue-link, comment, and governed-action services | `company`
`task`
`approvals`
`actor`
`wake`
`audit`
`idempotency` | 6 | governed semantic receipts, audit references, and attention/continuation linkage | Production binding and additive governed-action receipts are unbound; board-only authority stays outside grants. |
| [`ar` — Artifacts](#behavior-group-ar-artifacts) | always tools + artifact/work-product services | `register_deliverable` | `append_audit_record` | attachment upload and issue work-product routes | `task`
`artifacts`
`workProducts`
`workspace`
`audit`
`idempotency` | 4 | artifact/work-product reference and durable inspectability receipt; never binary bytes | Production upload/register composite and additive durable-reference receipt are unbound. |
| [`er` — Errors and critical rules](#behavior-group-er-errors-and-critical-rules) | runner/control plane + optional workspace/wake tools | `get_workspace_runtime`
`control_workspace_service`
`schedule_wake`
`inspect_operation_result` | `release_task`
`enforce_budget`
`persist_run`
`replay_run`
`reconcile_run` | workspace runtime, monitor/recovery, budget, run persistence/replay, release, and terminal services | `workspace`
`budget`
`run`
`wake`
`audit`
`idempotency`
`fault` | 9 | runtime/workspace/attention/run lifecycle, typed denials, replay facts, and terminal causality | Budget stop reasons and semantic denial/conflict receipts require additive v1 envelopes; inspect_operation_result remains scenario-only. |
-| [`rf` — Reference files](#behavior-group-rf-reference-files) | always instruction tools + optional domain tools + test-only escape hatch | `list_cases`
`upsert_case`
`list_routines`
`manage_routine`
`create_skill`
`list_company_skills`
`sync_company_skills`
`list_secret_metadata`
`read_secret_value`
`export_company`
`administer_company`
`generic_api_request`
`search_api`
`call_api`
`create_project`
`read_agent_instructions`
`update_agent_instructions`
`get_agent_instruction_history`
`restore_agent_instructions` | `append_audit_record` | agent instruction revisions, project, case, routine, company-skill, secret, portability, and administration services | `company`
`cases`
`routines`
`skills`
`secrets`
`audit`
`fault` | 22 | bounded domain projections, redacted broker receipts, company diffs, and audit references | Instruction read/update/history/restore require the live canonical revision service, current responsible-user permissions, and pinned base revisions for writes. Their service, authority, and product E2E tests are separate from the legacy mock scenarios. Project and skill creation and API tools require the live server authority; generic_api_request is test-only and the remaining domain operations are scenario-only. Broad administer_company is deferred and cannot claim product coverage. Production API and paired dedicated-tool regressions are recorded separately in paperclip-evals/evals/runner-api-tools; the legacy scenario count is not evidence of that coverage. |
+| [`rf` — Reference files](#behavior-group-rf-reference-files) | always instruction tools + optional domain tools + test-only escape hatch | `list_cases`
`upsert_case`
`list_routines`
`manage_routine`
`create_skill`
`update_skill`
`list_company_skills`
`sync_company_skills`
`list_secret_metadata`
`read_secret_value`
`export_company`
`administer_company`
`generic_api_request`
`search_api`
`call_api`
`create_project`
`read_agent_instructions`
`update_agent_instructions`
`get_agent_instruction_history`
`restore_agent_instructions`
`submit_complaint`
`submit_suggestion` | `append_audit_record` | agent instruction revisions, project, case, routine, company-skill, secret, portability, and administration services, and run-attributed agent commentary | `company`
`cases`
`routines`
`skills`
`secrets`
`audit`
`fault` | 22 | bounded domain projections, redacted broker receipts, company diffs, and audit references | Instruction read/update/history/restore require the live canonical revision service, current responsible-user permissions, and pinned base revisions for writes. Their service, authority, and product E2E tests are separate from the legacy mock scenarios. Project and skill creation and API tools require the live server authority; generic_api_request is test-only and the remaining domain operations are scenario-only. Broad administer_company is deferred and cannot claim product coverage. Production API and paired dedicated-tool regressions are recorded separately in paperclip-evals/evals/runner-api-tools; the legacy scenario count is not evidence of that coverage. Feedback actions are live-only: shared persistence, authority, API, and actual Codex smoke tests cover them; the legacy scenario count does not claim feedback coverage. |
| [`mh` — Multi-hop](#behavior-group-mh-multi-hop) | composed semantic operations + control-plane continuation | `create_task`
`set_dependencies`
`request_human_input`
`request_approval`
`register_deliverable` | `route_wake`
`reconcile_run` | delegation, dependency, interaction, approval, artifact, and terminal orchestration services | `task`
`blockers`
`interactions`
`approvals`
`artifacts`
`wake`
`run`
`audit` | 4 | correlated operation receipts, state diffs, attention hops, work assessment, status decision, and terminal outcome | No generic transaction tool is allowed; shared mock/real conformance must prove each composed effect. |
| [`rs` — Restraint and no-call](#behavior-group-rs-restraint-and-no-call) | policy/exposure layer | `answer_status_question`
`read_secret_value`
`generic_api_request` | `enforce_budget` | task-mode, secret-broker, test-scope, pause, and budget policy checks | `actor`
`task`
`budget`
`secrets`
`audit`
`fault` | 3 | absence of forbidden effects plus typed policy denial/redaction receipts when a call is attempted | Typed redaction/authorization receipts need additive v1 evidence; generic_api_request is never a product fallback. |
| [`wk` — Wake situations](#behavior-group-wk-wake-situations) | control plane + always context/history tools | `get_task_context`
`get_task_history`
`schedule_wake` | `select_work`
`route_wake` | wakeup requests, heartbeat context, comment/interaction/approval/blocker wake routing, and scheduled wake services | `wake`
`task`
`comments`
`interactions`
`approvals`
`blockers`
`run` | 8 | attention request routing/resolution plus resumed session/run causality | Production scheduling binding is unbound; control-plane routing remains non-callable. |
@@ -463,11 +467,11 @@ Current responsibility-based paths are normative. Numbered `phase-*` or mileston
### Catalog split and deliberate replacement
-- Scenario/eval catalog: **39** operations.
-- Live dispatcher catalog: **41** operations.
-- Shared: **27**; union/canonical authority: **53**.
+- Scenario/eval catalog: **40** operations.
+- Live dispatcher catalog: **44** operations.
+- Shared: **28**; union/canonical authority: **56**.
- Scenario-only: `administer_company`, `export_company`, `inspect_operation_result`, `list_cases`, `list_company_skills`, `list_goals`, `list_routines`, `list_secret_metadata`, `manage_routine`, `read_secret_value`, `sync_company_skills`, `upsert_case`.
-- Live-only: `call_api`, `create_project`, `get_agent`, `get_agent_instruction_history`, `get_approval`, `get_approval_context`, `hire_agent`, `list_project_repositories`, `read_agent_instructions`, `restore_agent_instructions`, `schedule_wake`, `search_api`, `set_task_title`, `update_agent_instructions`.
+- Live-only: `call_api`, `create_project`, `get_agent`, `get_agent_instruction_history`, `get_approval`, `get_approval_context`, `hire_agent`, `list_project_repositories`, `read_agent_instructions`, `restore_agent_instructions`, `schedule_wake`, `search_api`, `set_task_title`, `submit_complaint`, `submit_suggestion`, `update_agent_instructions`.
- The generated provider contract contains exactly the live catalog; the canonical union remains the migration authority until all scenario-only operations are either implemented, deferred, or removed by an explicit reconciliation decision.
- `generic_api_request` stays exported only for controlled tests and cannot be cited as real-surface, mock-parity, or PRP product coverage.
diff --git a/packages/paperclip-runner/src/agent-identity-environment.test.ts b/packages/paperclip-runner/src/agent-identity-environment.test.ts
new file mode 100644
index 00000000000..ea82e078ecf
--- /dev/null
+++ b/packages/paperclip-runner/src/agent-identity-environment.test.ts
@@ -0,0 +1,34 @@
+import { execFileSync } from "node:child_process";
+import { generateKeyPairSync, randomBytes, verify } from "node:crypto";
+import { afterEach, expect, it, vi } from "vitest";
+import { createSanitizedCodexEnvironment } from "./drivers/codex/app-server-transport.js";
+import { createIsolatedCodexAppServerArgs } from "./drivers/codex/codex-security-config.js";
+import { createSanitizedAcpxSpawnInput } from "./drivers/acpx/environment.js";
+
+afterEach(() => vi.unstubAllEnvs());
+
+it("native Codex and ACPX provider processes receive explicit identity and can sign", () => {
+ const keys = generateKeyPairSync("ed25519");
+ const environment = {
+ PAPERCLIP_AGENT_KEY_ID: "sha256:test-key",
+ PAPERCLIP_AGENT_PUBLIC_KEY: keys.publicKey.export({ type: "spki", format: "pem" }).toString(),
+ PAPERCLIP_AGENT_PRIVATE_KEY: keys.privateKey.export({ type: "pkcs8", format: "pem" }).toString(),
+ };
+ const challenge = randomBytes(32);
+ const source = `const {sign}=require('node:crypto'); process.stdout.write(sign(null,Buffer.from(process.argv[1],'hex'),process.env.PAPERCLIP_AGENT_PRIVATE_KEY).toString('base64'));`;
+ for (const env of [createSanitizedCodexEnvironment(environment), createSanitizedAcpxSpawnInput(environment, "codex").env]) {
+ expect(env).toMatchObject(environment);
+ const signature = execFileSync(process.execPath, ["-e", source, challenge.toString("hex")], { env });
+ expect(verify(null, challenge, keys.publicKey, Buffer.from(signature.toString(), "base64"))).toBe(true);
+ }
+ const args = createIsolatedCodexAppServerArgs(environment).join("\n");
+ expect(args).toContain('shell_environment_policy.inherit="all"');
+ expect(args).toContain("PAPERCLIP_AGENT_PRIVATE_KEY");
+ expect(args).not.toContain(environment.PAPERCLIP_AGENT_PRIVATE_KEY.split("\n")[1]);
+});
+
+it("native launchers do not adopt identity from an ambient host environment", () => {
+ vi.stubEnv("PAPERCLIP_AGENT_PRIVATE_KEY", "ambient-forged-key");
+ expect(createSanitizedCodexEnvironment().PAPERCLIP_AGENT_PRIVATE_KEY).toBeUndefined();
+ expect(createSanitizedAcpxSpawnInput(undefined, "codex").env.PAPERCLIP_AGENT_PRIVATE_KEY).toBeUndefined();
+});
diff --git a/packages/paperclip-runner/src/backends/codex-native-backend.ts b/packages/paperclip-runner/src/backends/codex-native-backend.ts
index 2c4aeceee18..eb6c12db40e 100644
--- a/packages/paperclip-runner/src/backends/codex-native-backend.ts
+++ b/packages/paperclip-runner/src/backends/codex-native-backend.ts
@@ -5,6 +5,7 @@ import type { NativeExecutionInput } from "../contracts/native-execution.js";
import type { PersistedHarnessSession } from "../contracts/harness-driver.js";
import type {
NativeSessionBackend,
+ NativeSessionBackendDescriptor,
PersistedNativeSession,
} from "../contracts/native-session-backend.js";
import type { CodexAppServerTransport } from "../drivers/codex/app-server-transport.js";
@@ -71,7 +72,7 @@ function transportDriverIdentity(input: NativeExecutionInput): {
return {
kind: "opencode_server",
displayName: "OpenCode server",
- version: "1.18.32",
+ version: "1.18.34",
};
case "claude_managed":
return {
@@ -139,7 +140,6 @@ function createTransportBackedNativeSessionBackend(
]
: []),
...nativeTaskConstraints(input),
- "Return one semantic completion result.",
];
return new HarnessDriverBackend(
@@ -186,7 +186,9 @@ function createTransportBackedNativeSessionBackend(
driverIdentity,
capabilities: isCodex
? {}
- : { steering: false, goals: false, threadLineage: false },
+ : { steering: false, goals: false, threadLineage: false,
+ toolRefreshOnResume: input.provider.kind !== "acpx"
+ || ACPX_CAPABILITY_PROFILES[input.provider.agent].toolRefreshOnResume === true },
collaborationModes: supportsCollaborativePlanning
? ["default", "plan"]
: ["default"],
@@ -196,6 +198,13 @@ function createTransportBackedNativeSessionBackend(
);
}
+/** Inspect the selected runnerd harness without starting a provider process. */
+export function describeRunnerdNativeSessionBackend(
+ input: NativeExecutionInput,
+): Promise {
+ return createTransportBackedNativeSessionBackend(input, {}).descriptor();
+}
+
/**
* Uses the Codex JSON-RPC facade strictly as the TypeScript transport shape.
* Runnerd still selects and owns the real provider process from run.prepare.
diff --git a/packages/paperclip-runner/src/backends/harness-driver-backend.ts b/packages/paperclip-runner/src/backends/harness-driver-backend.ts
index 4097882235f..b8530a8709c 100644
--- a/packages/paperclip-runner/src/backends/harness-driver-backend.ts
+++ b/packages/paperclip-runner/src/backends/harness-driver-backend.ts
@@ -673,6 +673,7 @@ class HarnessNativeSession implements NativeSession {
// The provider has no active turn to interrupt yet. Do not launch work
// whose events cancellation would suppress and leave the owner waiting.
if (this.#explicitlyCancelled) throw new Error("native_session_cancelled");
+ this.#terminal = null;
try {
const started = await this.#session.startTurn(input);
this.#assertProtocolIntegrity();
diff --git a/packages/paperclip-runner/src/backends/native-backend-factory.test.ts b/packages/paperclip-runner/src/backends/native-backend-factory.test.ts
index 33b8db8c479..419a176dfeb 100644
--- a/packages/paperclip-runner/src/backends/native-backend-factory.test.ts
+++ b/packages/paperclip-runner/src/backends/native-backend-factory.test.ts
@@ -127,7 +127,7 @@ function acpxExecution(
? "@openai/codex"
: "@anthropic-ai/claude-agent-sdk",
agentRuntimeVersion:
- agent === "pi" ? "0.84.2" : agent === "codex" ? "0.156.0" : "0.3.280",
+ agent === "pi" ? "0.84.2" : agent === "codex" ? "0.160.0" : "0.3.286",
commandDigest:
agent === "codex"
? "sha256:c4538599d1ab767db5dff50934f13bb5ba313a59d9c4a83e993fac4617ea63d3"
@@ -292,12 +292,13 @@ describe("native backend factory", () => {
await expect(backend.descriptor()).resolves.toMatchObject({
kind: "runner",
name: "opencode_server",
- version: "1.18.32",
+ version: "1.18.34",
capabilities: {
steering: false,
resume: true,
interruption: true,
dynamicTools: true,
+ toolRefreshOnResume: true,
collaborationModes: ["default", "plan"],
},
});
@@ -444,7 +445,7 @@ describe("native backend factory", () => {
await expect(backend.descriptor()).resolves.toMatchObject({
kind: "runner",
name: "opencode_server",
- version: "1.18.32",
+ version: "1.18.34",
capabilities: {
resume: true,
interruption: true,
@@ -470,10 +471,14 @@ describe("native backend factory", () => {
});
});
- it.each(["codex" as const, "claude" as const])(
+ it.each(["codex" as const, "claude" as const, "grok" as const])(
"routes qualified %s ACPX through runnerd",
async (agent) => {
- const backend = createNativeSessionBackend(acpxExecution(agent), {
+ const input = acpxExecution();
+ if (input.provider.kind !== "acpx") throw new Error("Invalid ACPX fixture");
+ const model = agent === "grok" ? "grok-4.7" : agent === "claude" ? "claude-sonnet-5" : "gpt-5.6-sol";
+ Object.assign(input.provider, { agent, model, profile: resolveQualifiedAcpxProfile(agent, model) });
+ const backend = createNativeSessionBackend(input, {
codexTransportFactory: () => {
throw new Error("descriptor must not launch the transport");
},
@@ -488,6 +493,7 @@ describe("native backend factory", () => {
interruption: true,
dynamicTools: true,
collaborationModes: ["default", "plan"],
+ toolRefreshOnResume: true,
},
});
},
diff --git a/packages/paperclip-runner/src/backends/native-backend-factory.ts b/packages/paperclip-runner/src/backends/native-backend-factory.ts
index 97e51011e6c..9aa0214995f 100644
--- a/packages/paperclip-runner/src/backends/native-backend-factory.ts
+++ b/packages/paperclip-runner/src/backends/native-backend-factory.ts
@@ -76,6 +76,7 @@ export function createNativeSessionBackend(
);
}
return createOpenCodeNativeSessionBackend(input, {
+ completionFeedback: options.completionFeedback,
runtimeDirectory: options.opencodeRuntimeDirectory,
environment: options.opencodeEnvironment,
command: options.opencodeCommand,
diff --git a/packages/paperclip-runner/src/backends/native-instruction-measurement.test.ts b/packages/paperclip-runner/src/backends/native-instruction-measurement.test.ts
new file mode 100644
index 00000000000..ab56cdfe845
--- /dev/null
+++ b/packages/paperclip-runner/src/backends/native-instruction-measurement.test.ts
@@ -0,0 +1,242 @@
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { readFileSync, writeFileSync, mkdtempSync, copyFileSync, chmodSync } from "node:fs";
+import { chmod, lstat, readdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { afterAll, describe, expect, it } from "vitest";
+
+import { PAPERCLIP_SEMANTIC_ACTION_CATALOG } from "../catalog/semantic-action-catalog.js";
+import { buildNativeModelEnvelope, parseNativeExecutionInput, type NativeExecutionInput } from "../contracts/native-execution.js";
+import { NATIVE_RUNTIME_ASSET_SCHEMA, PAPERCLIP_EXECUTION_PROMPT, PAPERCLIP_EXECUTION_PROMPT_REVISION, nativeRuntimePromptDigest, canonicalNativeRuntimeContextDigest } from "../contracts/runtime-context.js";
+import { PRP_BLOCK_TOOL_DESCRIPTION, PRP_COMPLETION_TOOL_DESCRIPTION } from "../contracts/completion-result.js";
+import { FakeCodexTransport, WORKSPACE } from "../drivers/codex/codex-app-server-driver.test-support.js";
+import { resolveQualifiedAcpxProfile } from "../drivers/acpx/qualified-profiles.js";
+import { createOpenCodeNativeSessionBackend } from "./opencode-native-backend.js";
+import { nativeSystemInstructions, nativeTaskConstraints } from "./runtime-context.js";
+import { createRunnerdNativeSessionBackend } from "./codex-native-backend.js";
+import { inspectNativeCompletionSourceMetadata } from "../../../../tests/runner-e2e/native-completion-git-source.mjs";
+
+// This captures Paperclip's real runnerd RPC boundary with a scripted transport.
+// It measures complete Paperclip-supplied instruction/tool/message projections,
+// not provider-owned stock prompts, tokenization, billing or model behavior.
+const tools = PAPERCLIP_SEMANTIC_ACTION_CATALOG
+ .filter(tool => tool.placement === "core")
+ .map(tool => ({ name: tool.operationId, description: tool.description, inputSchema: tool.inputSchema }));
+const identity = { companyId: "company", agentId: "agent", issueId: "issue", runId: "run", sessionId: "session" };
+const { qualificationModel: _qualificationModel, reportedModelId: _reportedModelId, permissionPolicy: _permissionPolicy, ...profile } = resolveQualifiedAcpxProfile("claude", "claude-sonnet-5");
+const providers: NativeExecutionInput["provider"][] = [
+ { kind: "codex", model: "gpt-5.6-sol", approvalPolicy: "never" },
+ { kind: "acpx", agent: "claude", model: "claude-sonnet-5", permissionMode: "approve-all", profile },
+ { kind: "opencode", model: "openrouter/deepseek/deepseek-v4-flash-0731", permissionMode: "allow" },
+];
+const receipts: unknown[] = [];
+const directOpenCodeReceipts: unknown[] = [];
+const sha256 = (text: string | Buffer) => createHash("sha256").update(text).digest("hex");
+
+function execution(provider: NativeExecutionInput["provider"], schema: "v4" | "v5"): NativeExecutionInput {
+ const rootPath = WORKSPACE;
+ const entry = readFileSync(new URL("../../../../server/src/onboarding-assets/default/AGENTS.md", import.meta.url), "utf8");
+ writeFileSync(`${rootPath}/AGENTS.md`, entry);
+ const context = {
+ prompt: { revision: PAPERCLIP_EXECUTION_PROMPT_REVISION, text: PAPERCLIP_EXECUTION_PROMPT, digest: nativeRuntimePromptDigest() },
+ instructions: { entryPath: "AGENTS.md", bundle: { schema: NATIVE_RUNTIME_ASSET_SCHEMA, rootPath, digest: sha256(entry), manifestDigest: sha256(entry), fileCount: 1, totalBytes: Buffer.byteLength(entry) } },
+ skills: [], mcp: { assignmentSetId: "none", digest: "0".repeat(64), bindingId: null },
+ };
+ return parseNativeExecutionInput({
+ schema: `paperclip.native-execution-input.${schema}`,
+ binding: { companyId: identity.companyId, agentId: identity.agentId, issueId: identity.issueId, runId: identity.runId, executionWorkspaceId: "workspace" },
+ task: { identifier: "TASK-1", title: "Save the requested document", description: "Save the requested document", prompt: "Save the requested document.", workMode: "standard" },
+ workspace: { cwd: rootPath, repoUrl: null, repoRef: null, branchName: null },
+ session: { normalizedSessionId: "session", driverKind: provider.kind === "acpx" ? "acpx_runtime" : provider.kind === "opencode" ? "opencode_server" : "codex_app_server", protocolVersion: 1 },
+ provider,
+ executionMode: "default",
+ planningContext: null,
+ completionContract: { id: "contract", sha256: `sha256:${"a".repeat(64)}`, schemaVersion: "paperclip.completion-contract.v1", contract: { revision: "1", objective: "Save the requested document", criteria: [{ id: "objective", requirement: "Document saved" }] } },
+ interactionResponses: [], credentialBindings: [],
+ runtimeContext: { ...context, aggregateDigest: canonicalNativeRuntimeContextDigest(context) },
+ });
+}
+
+function transport(provider: NativeExecutionInput["provider"]) {
+ return new FakeCodexTransport("thread-1", "provider-session-1", provider.kind === "acpx" ? {
+ kind: "acpx", normalizedSessionId: "session", acpxRecordId: "fixture-record", backendSessionId: "fixture-backend",
+ agentSessionId: "fixture-agent", profileDigest: `sha256:${"a".repeat(64)}`, workspaceDigest: `sha256:${"b".repeat(64)}`,
+ requestedModel: provider.model, effectiveModel: provider.model, permissionMode: "approve-all",
+ providerLifetimeFenceCandidates: [60001, 60002, 60003],
+ } : undefined);
+}
+
+function measure(value: unknown) {
+ // Temporary fixture workspace names must not create false before/after deltas.
+ const json = JSON.stringify(value).replaceAll(WORKSPACE, "/workspace");
+ return { utf8Bytes: Buffer.byteLength(json), characters: json.length, sha256: sha256(json) };
+}
+
+describe("native instruction payload measurement", () => {
+ for (const provider of providers) for (const schema of ["v4", "v5"] as const) {
+ it(`captures ${provider.kind} ${schema} instructions and tools on start, resume and continuation`, async () => {
+ const input = execution(provider, schema);
+ const fresh = transport(provider), resumed = transport(provider), continued = transport(provider);
+ const backend = createRunnerdNativeSessionBackend(input, {
+ transportFactory: () => fresh, dynamicTools: tools,
+ environment: { PAPERCLIP_WORKSPACE_CWD: WORKSPACE },
+ });
+ const session = await backend.openSession({ identity, workingDirectory: WORKSPACE });
+ const checkpoint = await session.snapshot();
+ const envelope = buildNativeModelEnvelope(input);
+ if ("requestedSkills" in envelope && backend.preparedTaskConstraints) envelope.constraints = [...backend.preparedTaskConstraints];
+ await session.startTurn({ message: { role: "user", text: JSON.stringify(envelope) } });
+ await session.close({ reason: "measurement" });
+
+ resumed.readResponse = { thread: { id: "thread-1", sessionId: "provider-session-1", cwd: WORKSPACE, turns: [] } };
+ const resumeBackend = createRunnerdNativeSessionBackend(input, {
+ transportFactory: () => resumed, dynamicTools: tools,
+ environment: { PAPERCLIP_WORKSPACE_CWD: WORKSPACE },
+ });
+ const recovery = await resumeBackend.recoverSession!(checkpoint, { signal: new AbortController().signal });
+ expect(recovery.recovered).toBe(true);
+ await recovery.session!.startTurn({ message: { role: "user", text: JSON.stringify(envelope) } });
+ await recovery.session!.close({ reason: "measurement" });
+
+ continued.readResponse = resumed.readResponse;
+ const continuationInput = parseNativeExecutionInput({ ...input, continuationPrompt: "User update: retain the existing document and finish." });
+ const continuationBackend = createRunnerdNativeSessionBackend(continuationInput, {
+ transportFactory: () => continued, dynamicTools: tools,
+ environment: { PAPERCLIP_WORKSPACE_CWD: WORKSPACE },
+ });
+ const continuationRecovery = await continuationBackend.recoverSession!(checkpoint, { signal: new AbortController().signal });
+ expect(continuationRecovery.recovered).toBe(true);
+ const continuationEnvelope = buildNativeModelEnvelope(continuationInput, { resumedSession: true });
+ expect(continuationEnvelope.schema).toBe("paperclip.native-continuation.v1");
+ await continuationRecovery.session!.startTurn({ message: { role: "user", text: JSON.stringify(continuationEnvelope) } });
+ await continuationRecovery.session!.close({ reason: "measurement" });
+
+ for (const [phase, captured, method] of [["start", fresh, "thread/start"], ["resume", resumed, "thread/resume"], ["continuation", continued, "thread/resume"]] as const) {
+ const setup = captured.calls.find(call => call.method === method)!.params;
+ const turn = captured.calls.find(call => call.method === "turn/start")!.params;
+ const instructions = setup.developerInstructions ?? setup.baseInstructions;
+ expect(instructions).toContain(PAPERCLIP_EXECUTION_PROMPT);
+ expect(instructions).toContain("You are an agent in a Paperclip company.");
+ const deliveredTools = setup.dynamicTools as Array<{ name: string; description: string }>;
+ expect(deliveredTools.filter(tool => tool.name === "paperclip_finish")).toEqual([
+ expect.objectContaining({ description: PRP_COMPLETION_TOOL_DESCRIPTION }),
+ ]);
+ expect(deliveredTools.filter(tool => tool.name === "paperclip_block")).toEqual([
+ expect.objectContaining({ description: PRP_BLOCK_TOOL_DESCRIPTION }),
+ ]);
+ expect(deliveredTools).toHaveLength(tools.length + 2);
+ if (phase === "continuation") {
+ expect(JSON.stringify(turn.input)).toContain("User update: retain the existing document and finish.");
+ const delivered = JSON.parse((turn.input as Array<{ text: string }>)[0]!.text);
+ expect(schema === "v4" ? JSON.parse(delivered.message) : delivered).toEqual(continuationEnvelope);
+ if (schema === "v5") {
+ expect(JSON.stringify(turn.input)).not.toContain("constraints");
+ expect(JSON.stringify(turn.input)).not.toContain("Document saved");
+ } else {
+ // v4's task-mode driver still wraps the compact message in its task envelope.
+ expect(JSON.stringify(turn.input)).toContain("Obtain one accepted result");
+ expect(JSON.stringify(turn.input)).toContain("Document saved");
+ }
+ expect(JSON.stringify(turn.input)).toContain("objective");
+ } else {
+ expect(JSON.stringify(turn.input)).toContain("Obtain one accepted result");
+ expect(JSON.stringify(turn.input)).toContain("Document saved");
+ expect(JSON.stringify(turn.input)).toContain("write_document");
+ expect(JSON.stringify(turn.input)).toContain("register_deliverable");
+ }
+ expect(setup.approvalPolicy).toBe("never");
+ receipts.push({ provider: provider.kind, schema, phase,
+ instructions: measure(instructions), tools: measure(setup.dynamicTools), input: measure(turn.input),
+ fullProjection: measure({ instructions, tools: setup.dynamicTools, input: turn.input }),
+ deliveredToolCount: deliveredTools.length,
+ });
+ }
+ const start = fresh.calls.find(call => call.method === "thread/start")!.params;
+ const resume = resumed.calls.find(call => call.method === "thread/resume")!.params;
+ expect(resume.dynamicTools).toEqual(start.dynamicTools);
+ expect(resume.developerInstructions ?? resume.baseInstructions).toEqual(start.developerInstructions ?? start.baseInstructions);
+ });
+ }
+});
+
+async function makeWritable(root: string): Promise