feat(dot): expand governed Runner capabilities and finish pairing setup

Co-Authored-By: Paperclip <noreply@paperclip.ing>

doc/DEVELOPING.md

@@ -92,6 +92,12 @@ The vite dev server serves an unbundled module graph. This is fast to reload on
 
 The preview server binds `0.0.0.0` and accepts any Host, so a tailnet or LAN address (e.g. `http://<host>.ts.net:3101/`) works out of the box. The `/api` proxy sets `x-forwarded-host` and `x-forwarded-proto`, which the server's board mutation guard uses to trust the browser's Origin — mutations from `:3101` succeed against the API on `:3100` without further configuration. An HTTPS tunnel in front of the preview server (ngrok, tailscale funnel) is also supported: the tunnel's `x-forwarded-proto` header is preserved when set.
 
+Static UI mode compresses built JavaScript, CSS, and HTML with Brotli or gzip
+when the browser supports it. Hashed assets retain their immutable cache policy;
+byte-range responses retain their original representation. This reduces initial
+page downloads through bandwidth-limited HTTPS tunnels such as Tailscale Funnel.
+API responses and MCP transports keep their existing compression behavior.
+
 ## Storybook
 
 The board UI Storybook keeps stories and Storybook config under `ui/storybook/` so component review files stay out of the app source routes.

doc/openai-dot-runner.md

@@ -19,12 +19,23 @@ controller deployments are not qualified. The feature is off by default.
    `PAPERCLIP_ENABLE_OPENAI_DOT` environment flag no longer enables the provider.
 2. Create an approved Paperclip Runner agent with provider **OpenAI Dot**.
    Acknowledge that its provider billing is external and unmetered. Save it.
-3. In the agent configuration, choose **Pair Dot**. Connect a private ChatGPT
-   plugin to the displayed `/mcp/runner` URL and approve its dedicated agent
-   OAuth scope. The personal `/mcp/paperclip` connection cannot execute as Dot.
-4. Give the Dot the one-use pairing code. It calls `paperclip_dot_pair`, then
-   subscribes to `paperclip.dot.mailbox_updated` with the returned company and
-   binding IDs. Its callback must pass the signed webhook verification.
+3. In the agent configuration, choose **Pair Dot**, then **Set up with Dot**.
+   The shared setup-prompt component copies the MCP URL, one-use pairing code,
+   expiry, and event instructions. Paste the prompt into your Dot so it can add
+   or reuse the private plugin and finish OAuth in its own browser. Dot enters
+   the one-use code on the Paperclip connection page and chooses
+   **Connect Dot with pairing code**. Entering a valid code first shows the
+   exact company, agent, permissions, and ongoing revocable access duration;
+   previewing consumes no code and creates no grant. No operator sign-in in Dot’s browser is
+   needed. The personal `/mcp/paperclip` connection
+   cannot execute as Dot.
+4. The OAuth code approval pairs Dot atomically. Attach the connected plugin
+   to the Dot conversation if ChatGPT has not exposed its action tools. Dot calls
+   `paperclip_dot_inbox` to verify access, then subscribes to
+   `paperclip.dot.mailbox_updated` with the setup company and inbox binding IDs.
+   Its callback must pass the signed webhook verification. The prompt stays
+   only in page memory and disappears when its code expires; if you leave the
+   page or the code expires, revoke the pending connection and pair again.
 5. Choose **Test event delivery**. Dot drains `paperclip_dot_inbox` and confirms
    the readiness challenge. Readiness requires this round trip, not just an
    HTTP acknowledgement from the callback.
@@ -38,8 +49,12 @@ 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 `<origin>/mcp/runner/oauth`; the personal issuer remains `<origin>`.
-The shared consent page identifies Dot agent access and requires an operator
-role. Device codes and browser requests stay bound to their original resource
+The shared consent page identifies Dot agent access. A code issued by an
+operator preapproves only its selected company and agent; redemption rechecks
+current operator membership, agent availability, all experimental prerequisites,
+expiry, revocation, and the authorization request’s organization hint. Redemption
+consumes the code and attaches the grant atomically; it creates no board session.
+Manual browser and device consent still require 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.
 
@@ -47,6 +62,40 @@ Database migration `0312_broken_sentinels.sql` adds only Dot tables and extensio
 after the merged gateway migrations. It is safe to reapply. The earlier
 prototype migration number is retired; published master migrations are intact.
 
+## Troubleshoot plugin OAuth discovery
+
+Use the exact server URL `<origin>/mcp/runner` with OAuth authentication. The
+resource metadata lives at `/.well-known/oauth-protected-resource/mcp/runner`;
+its authorization server is `<origin>/mcp/runner/oauth`, with discovery at
+`/.well-known/oauth-authorization-server/mcp/runner/oauth`. Both metadata URLs
+must return JSON without a login or redirect. An unauthenticated MCP request
+returns `401` with a `WWW-Authenticate` header pointing to the resource metadata.
+The server advertises both CIMD and Dynamic Client Registration; use CIMD when
+ChatGPT discovers it. A manually entered client secret is not required.
+ChatGPT’s CIMD prefers `private_key_jwt` but explicitly lists `none` among its
+supported methods. Paperclip selects the public PKCE method it advertises and
+rejects clients whose published capabilities do not include that method.
+
+The browser authorization page must also be reachable from Dot’s computer.
+Discovery and browser reachability are separate checks: a temporary tunnel may
+work for ChatGPT’s MCP service while Dot’s browser blocks its hostname. If the
+same instance already has another trusted public HTTPS browser ingress, set
+`PAPERCLIP_MCP_AUTHORIZATION_ORIGIN` to that origin and allow its hostname in the
+instance configuration. The advertised authorization endpoint, consent pages,
+and device verification pages use that origin. The MCP resource, issuer, token
+endpoint and PKCE validation remain on `PAPERCLIP_PUBLIC_URL`. Consent mutations
+accept only these explicitly configured origins; this does not allow arbitrary
+return destinations or expose another instance.
+
+If ChatGPT times out, compare its retry with the server access log. No incoming
+MCP or discovery request means that attempt did not reach Paperclip; entering
+OAuth URLs manually does not repair that connection. Verify public reachability
+from outside the tailnet: MagicDNS on the host can route a Tailscale URL directly
+to the private tailnet address even when the same URL uses Funnel externally.
+Check the public ingress separately before concluding that public access works.
+The plugin builder's timeout alone does not establish a blocked port or a
+missing discovery document. See [OpenAI's authentication guidance](https://developers.openai.com/plugins/build/auth).
+
 ## Assignment protocol
 
 Events contain mailbox references. Dot drains the inbox after its saved cursor,
@@ -83,12 +132,11 @@ tools; those narrow inbox reads leave its task cursor unchanged.
 ## Limits and recovery
 
 - One active assignment per binding. Acceptance expires after 10 minutes;
-  execution authority expires after two hours. Fifteen minutes without useful
+  execution authority starts with a two-hour lease. Accepted, still-authorized assignments can renew with `paperclip_dot_renew` for up to two hours ahead, within a 24-hour total bound. Fifteen minutes without useful
   activity is shown in the connection panel as requiring attention.
 - No mounted workspace, selectable model, native Dot thread identifier,
   provider usage or provider cost. Text deliverables use Paperclip documents.
-  Assigned skill files and third-party MCP bindings are currently unsupported
-  and fail admission explicitly.
+  Assigned skills are read from verified pinned bundles; app tools use the assigned MCP gateway. The optional workspace bridge provides files, sandboxed commands, and verified downloadable artifacts without mounting files into OpenAI. Commands require macOS sandbox-exec or Linux bubblewrap; there is no unrestricted fallback. Networking and injected credentials are excluded from commands; use assigned app tools for services.
 - Cancel, pause, reassignment and revocation fence Paperclip authority. They do
   not confirm that Dot stopped all external activity. A fence acknowledgement
   records receipt only.
@@ -107,7 +155,7 @@ assignment or replay tool effects. OAuth revocation and refresh-token replay
 also revoke the matching binding, fence its assignments, and cancel waiting
 Paperclip runs. Revoking an old grant cannot revoke a replacement binding.
 Reopening an agent form restores the binding reference from the server so a
-previously completed pairing can still be saved in the agent configuration.
+previously completed pairing remains visible. Completing pairing also saves the exact binding reference and a configuration revision atomically; revocation clears only that matching reference. A separate form save is unnecessary.
 
 ## Verification evidence
 
@@ -121,14 +169,53 @@ closed launch fields, expiry and late effect receipts after fencing.
 The earlier real-Dot account experiment proved OAuth and signed wake/report
 transport through the reference harness; see `dot-runner-prototype.md`. That
 proof does not qualify this new dedicated endpoint against a real account.
-The dedicated adapter's real-account acceptance test remains to be run.
+The dedicated adapter was subsequently qualified against a real Dot account
+on 2026-10-07, as recorded below.
 On 2026-10-06, a hands-on browser test used a fresh authenticated instance with
 synthetic account, company, and agent data through its public HTTPS origin.
 It verified the experimental prerequisites, saved toggle behavior, Dot harness,
 dedicated MCP URL, one-use pairing instructions, and revocation. The instance
 was created with `worktree init --empty`, so it copied no private instance data
-or signing keys. Real Dot pairing, event delivery, and task completion remain
-to be qualified.
+or signing keys. At that point, real Dot pairing, event delivery, and task
+completion had not yet been qualified.
+
+On 2026-10-07, the real Dot account completed the dedicated endpoint acceptance
+in that empty synthetic test-drive. Dot created the private ChatGPT plugin and
+reviewed the exact agent grant. The human approved the connection in Codex;
+Codex submitted that actual consent through the existing plugin Connect flow.
+Dot could not verify an agent relay of human approval, so this did not rely on
+impersonating the human or overriding Dot's policy. Codex attached the connected
+app to the Dot conversation when its tools were not initially exposed. No
+human operated Dot's computer. Dot verified its inbox and enabled its signed
+MCP Events subscription. A Paperclip readiness challenge woke Dot without a
+manual chat message and was confirmed successfully.
+
+The first task exposed a missing Dot descriptor in ordinary heartbeat admission.
+Admission now inspects the dedicated bridge's actual capabilities without
+starting a broker or provider process; it does not route Dot through the
+Codex-compatible JSON-RPC facade. A normal UI retry then completed **DOT-1**:
+mailbox item 2 woke Dot, which accepted the assignment, used the projected tool
+catalog to write and read back `dot-runner-acceptance`, and submitted accepted
+structured completion. The document contains the exact synthetic nonce and
+has one revision authored by the Dot agent. The ordinary native finalizer
+committed **Done**, with a succeeded run, exit code 0, no remaining work, and
+no verification caveats. Provider usage and cost remained null.
+
+Inspect these persisted synthetic acceptance records in the test-drive:
+
+- Task: `a3ecdff5-41b0-400a-8146-51317c0b864e` (DOT-1).
+- Run: `9a44feeb-2779-4217-8210-092852019511`.
+- Assignment: `fbee1530-5a20-41d0-8f8f-226ef45f8a58`.
+- Document: `3f094689-6346-4a9c-8138-7c08df5da6b1`, revision
+  `033be018-f6f6-4b6b-a10f-e892627e12e3`.
+
+After the admission fix, 34 Runner/driver tests and 13 real Rust/broker integration
+tests passed. Full workspace typecheck and build passed. The earlier full
+repository test attempt remains incomplete after unrelated failures and a
+workspace snapshot stress timeout. This live qualification covers the current
+local-controller endpoint; it does not establish a green full suite, hosted
+broker qualification, or a permanent public ingress. The temporary tunnel must
+be replaced with a stable origin for continued use.
 
 The current integration includes master through `a6306ba60`, including the
 assistant configuration and tool expansion in #15380. Dot still uses its own
@@ -192,3 +279,57 @@ responses. These screenshots show preview data, not a qualified Dot account:
 ![Synthetic pairing preview](screenshots/openai-dot-runner/pairing.jpg)
 
 ![Synthetic connected preview](screenshots/openai-dot-runner/connected.jpg)
+
+
+## Starting work from a Dot conversation
+
+Call `paperclip_dot_capabilities` to discover the bound agent, responsible person, permissions, prerequisites and active assignment. An idle Dot can call `paperclip_dot_request_turn` with a prompt and stable UUID. Paperclip creates one visible, agent-authored intake task and admits it through the ordinary heartbeat/Runner path. Retries reuse the task and wake receipt; the same UUID with a different prompt is rejected. Company and agent pause, grants, budgets, task assignment permissions and single-assignment ownership apply. The intake is work attributed to the Dot, not a fabricated operator message or an OAuth permission expansion.
+
+Read and accept the resulting assignment, then call its catalog through `paperclip_dot_tool`. Use `get_identity` and paginated `list_people` to identify the owner. `create_task` accepts either `assigneeActorId` for an agent or `assigneeUserId` for an active company person. `reassign_task` also accepts a person and checks the previous agent/person and status version before the ownership change. Human tasks do not wake agents.
+
+The shared catalog adds `get_task`, `comment_on_task`, `list_task_documents`, `read_task_document`, and `write_task_document` through the existing authenticated REST authority. Company boundaries, task visibility, mode restrictions, document revisions, locks and mutation receipts still apply. `call_api` remains the discovery-based route for other authorized control-plane actions.
+
+`list_assigned_skills` and `read_assigned_skill` read the turn's exact pinned skill versions, with manifest and file digest checks. Assigned app tools are projected by the existing MCP gateway; its permission checks, approvals, receipts and revocations remain authoritative. Credentials are kept on Paperclip. Newly granted app tools arrive in a continuation with a new pinned catalog.
+
+Enable **Workspace files and commands** on the agent to expose `workspace_list`, `workspace_read`, `workspace_write`, and `workspace_run`. The server binds these to the admitted execution workspace. File paths reject absolute paths, traversal and symlinks. New writes require an absent file; overwrites require its observed SHA-256. Commands have bounded output/time and an OS sandbox, use a workspace-local home, and do not inherit credentials. Live authority loss kills the owned command process group. Register requested files with `register_deliverable` before finishing. Workspace mutation attempts are reserved durably before effects; an interrupted attempt returns an unknown outcome instead of replaying a possible effect. Inspect state before deciding another mutation.
+
+Mailbox `follow_up` entries reference new comments on an accepted assignment. Read `get_task_history` and incorporate them at a safe boundary. This supplies new input without claiming OpenAI steering support. `paperclip_dot_tasks` pages by the last task ID. Each assignment allows up to 4,000 broker operations; lower domain-specific limits still apply. A fenced assignment's control acknowledgement remains available at that limit. `hire_agent` creates a distinct unpaired Paperclip Dot teammate; the operator still pairs a separate OpenAI Dot. No existing binding or workspace permission is inherited.
+
+
+## Tool inventory
+
+The top-level MCP catalog contains these 15 transport and lifecycle tools:
+`paperclip_dot_capabilities`, `paperclip_dot_request_turn`, `paperclip_dot_tasks`,
+`paperclip_dot_request_work`, `paperclip_dot_pair`, `paperclip_dot_inbox`,
+`paperclip_dot_read`, `paperclip_dot_accept`, `paperclip_dot_tool`,
+`paperclip_dot_progress`, `paperclip_dot_finish`, `paperclip_dot_operation_status`,
+`paperclip_dot_confirm_event`, `paperclip_dot_renew`, `paperclip_dot_control_ack`.
+
+After accepting work, use `paperclip_dot_tool` with a name from the assignment's
+actual catalog. Availability depends on work mode, permissions, assigned apps,
+and workspace/attachment bindings. Advertising a tool does not bypass its
+server-side authorization.
+
+| Area | Runner tools |
+| --- | --- |
+| Identity and people | `get_identity`, `list_people`, `list_agents`, `get_agent` |
+| Task work | `get_task_context`, `get_task_history`, `search_tasks`, `get_task`, `report_progress`, `set_task_title`, `create_task`, `reassign_task`, `set_dependencies`, `comment_on_task` |
+| Human input and approvals | `request_human_input`, `list_approvals`, `get_approval`, `get_approval_context` |
+| Documents | `list_documents`, `read_document`, `list_document_revisions`, `write_document`, `list_task_documents`, `read_task_document`, `write_task_document` |
+| Agent instructions | `read_agent_instructions`, `update_agent_instructions`, `get_agent_instruction_history`, `restore_agent_instructions` |
+| Skills | `create_skill`, `update_skill`, `list_assigned_skills`, `read_assigned_skill` |
+| Projects | `create_project`, `list_projects`, `list_project_repositories` |
+| Apps and control-plane APIs | `connections_search`, `connection_request`, `search_api`, `call_api`, `hire_agent`; assigned gateway tools are discovered from the actual catalog, or via `paperclip_search_assigned_tools` / `paperclip_call_assigned_tool` for large catalogs |
+| Workspace and output | `workspace_list`, `workspace_read`, `workspace_write`, `workspace_run`, `register_deliverable` |
+| Bound chat inputs | `list_chat_attachments`, `reuse_chat_attachment`; `read_chat_attachment` and `read_current_wake_comments` require verified server bindings |
+| Feedback | `submit_complaint`, `submit_suggestion` |
+| Completion | `paperclip_finish`, `paperclip_block`; a separate review run offers its limited read catalog and `resolve_review` |
+
+Dot does not automatically stage inbound task attachments. An attachment reader
+is available only when a verified read scope is supplied. Assigned skills,
+workspace files and registered deliverables use the separate paths above.
+
+A plugin upgraded during a running Dot conversation can retain an old top-level
+tool catalog. Refresh its tools in ChatGPT plugin settings and reattach it.
+Inspect the real exposed actions before claiming new idle or lease actions
+are available. The assignment catalog is read on each new assignment.

doc/plans/2026-10-02-openai-dot-runner-adapter.md

@@ -931,3 +931,23 @@ This plan is saved in the existing isolated worktree. There is no assigned
 Paperclip issue or authenticated issue-artifact context in this Codex chat, so
 it is a repository plan rather than an uploaded issue artifact. When execution
 is assigned in Paperclip, link this plan as its plan document/work product.
+
+
+## 15. First-time onboarding checkpoint — 2026-10-07
+
+The live onboarding attempt found and fixed two authorization problems. ChatGPT’s client metadata prefers `private_key_jwt` while also publishing `none` as a supported method; Paperclip now negotiates the supported public-client method while retaining S256 PKCE. Dot’s browser blocks the temporary Cloudflare hostname even though ChatGPT’s MCP discovery service reaches it. An optional `PAPERCLIP_MCP_AUTHORIZATION_ORIGIN` separates the browser authorization ingress from the MCP resource, issuer, and token ingress. Both routes use existing operator-approved tunnels; no new hosted infrastructure was created.
+
+An operator-issued, expiring, one-use pairing capability now lets Dot approve its exact agent grant without receiving an operator password or board session. The preview validates the pending request, binding, company, current operator membership, and agent status, and displays company, agent, permitted task operations, and access duration before submission. Approval and binding consumption are atomic, and the resulting token remains restricted to the Runner resource and exact agent. The copied setup prompt uses this path and retains the user-requested plugin-creation authorization paragraph. The live attempt also exposed a plugin-name collision and uncertainty about entering the code; the prompt now handles an existing name for another URL, and both the prompt and consent page explain that code entry previews access while submitting Connect grants it.
+
+The synthetic test-drive remains separate from production. Dot created the fresh custom plugin and reached the Tailscale consent page. It entered the code, confirmed the exact company, agent, permissions, and duration in its own scope preview, and stopped before submitting Connect. The human approved the exact connection in Codex. Dot could not verify an agent relay of that approval, so Codex completed the actual consent through the existing private plugin Connect action using the direct human authorization. The registered ChatGPT callback exchanged the real OAuth token successfully. Attaching the already connected app to the Dot conversation exposed its tools; Dot verified its inbox, created and verified the mailbox event subscription, and confirmed a readiness challenge triggered from Paperclip with no manual chat wakeup. The connection is ready. The first ordinary task exposed a heartbeat descriptor omission before dispatch; admission now uses the real dedicated Dot bridge descriptor, rather than the JSON-RPC facade. Its regression test verifies the same capabilities as execution without starting a process or broker. The normal UI retry completed DOT-1 through the real Rust Runner without a manual chat wakeup. Dot accepted mailbox item 2, wrote and read back the exact-nonce document, and completed both reporting steps. The ordinary finalizer committed Done; run `9a44feeb-2779-4217-8210-092852019511` succeeded with exit code 0, no remaining work or verification caveats, and unknown provider usage/cost retained as null. The live connection and local-controller task path are qualified; stable production ingress and hosted/remote modes remain outside this acceptance.
+
+Verification: the focused OAuth/onboarding API suite passed 11 cases, the affected UI suites passed 27 cases, the relevant server/UI typechecks and token gates passed, and the workspace build passed. The earlier focused Runner/MCP suites also passed. A full `test:run` was stopped after unrelated failures and a 300-second workspace snapshot stress timeout; isolated tool-access and event-sequencing rechecks passed, but the full suite is incomplete. After the admission fix, 34 Runner/driver tests and 13 real Rust/broker integration tests passed, and full workspace typecheck and build passed again. The full repository suite is still incomplete, so this checkpoint is not a PR-ready verification claim.
+
+During deployment, macOS exhausted its PostgreSQL shared-memory IDs. One confirmed unused PostgreSQL interlock with zero attachments and an exited creator was reclaimed; no running database was stopped. Another development instance had occupied the old API port during the outage, so this test-drive and its existing public tunnels were moved to port 3109. The temporary MCP tunnel hostname consequently changed; fresh plugin onboarding must use the current runtime prompt rather than an old copied URL or expired pairing code.
+
+
+## 2026-10-07 full Runner capability extension
+
+User authorized implementation and live qualification of all six expansion areas. Delivery scope: idle request admission with normal run ownership; human assignees and person discovery; authorized cross-task tools; pinned skill reads and assigned MCP gateway relay; explicitly enabled host workspace tools and verified artifacts; truthful capability discovery; rolling lease renewal, pagination and follow-up input. Preserve provider limits for model choice, usage, cost, and unconfirmed global external stopping.
+
+Acceptance: an idle Dot creates a hello task assigned to the responsible person; an assigned Dot reads a pinned skill, uses an authorized assigned gateway tool, produces a verified downloadable file, handles follow-up input, renews its lease, and cannot continue mutations after fencing. Verify replay, company isolation, budget stops and permission denials. Do not reseed the synthetic test-drive from production.