DottaandPaperclip
32ec84db2e
## Thinking Path > - Paperclip manages AI agents and their work. > - Native sessions retain provider state across execution attempts. > - A same-run retry can receive a replacement plugin task lease. > - The executor loaded the old task checkpoint only for crash recovery. > - An ordinary retry could fail its local authority check before reading that checkpoint. > - This change restores the checkpoint through the existing authorized lease transfer. ## Linked Issues or Issue Description **What happened?** A native provider turn ended without its completion result. Paperclip scheduled an exact-checkpoint retry on the same heartbeat run. The retry acquired a new plugin task lease, then failed with `runner_state_identity_mismatch: authority_indeterminate`. The checkpoint restore branch required a `resume_dead_runner` restart claim. Ordinary same-run retries have no such claim. A controlled fixture with a retained remote checkpoint and no local lifecycle receipt reproduces the error. The original controller file contents were unavailable, so that part of the incident mechanism remains inferred. **Expected behavior** Load the retained plugin checkpoint after the existing policy proves the lease transfer is safe. Keep the original run, session, and saved control journal. Reject an unverified predecessor or a changed checkpoint identity. **Steps to reproduce** 1. Start a native session through a plugin task environment. 2. End its provider turn without a completion result and retain its checkpoint. 3. Retry the same run on a replacement task lease without a restart claim. 4. With no local lifecycle receipt, observe the authority error before the checkpoint read. **Paperclip version or commit** Reproduced against source `507dc70be26c191e372f09e58dc0965e73bf8f57`. **Deployment mode** Native Runner with a plugin task environment. The observed provider used ACPX Claude. The controlled executor fixture uses the shared native boundary. Related work: #17439 concerns recovery after controller replacement. This fix uses the existing checkpoint contract and does not depend on that PR. ## What Changed - Restore prior plugin state for an ordinary same-run attempt when its lease changes. - Keep the existing company, agent, workspace, retained-state, and termination checks. - Extend executor regressions for ordinary retries, mismatched checkpoints, and missing stop proof. - Exercise the same-run checkpoint read through the database-backed task API. - Document the recovery rule and verification recipes. ## Verification - Failing before: the ordinary retry reproduces `authority_indeterminate`. Both new denial cases also fail because the old branch never reaches the transfer policy. - Passing after: all six focused checkpoint cases pass. The saved control journal stays byte-for-byte unchanged. Rejected cases do not construct a provider backend. - `pnpm -r typecheck` passes. - Map and module-boundary checks pass. - All 858 executor, database lease-authority, plugin task, and ownership tests pass. `pnpm build` passes. - The broad local `pnpm test:run` attempt did not complete. It hit a 20-second timeout in the existing historical workspace-recovery HTTP Retry case. That exact case then passed in isolation on the unchanged head. The broad local attempt was stopped after the full CI matrix passed; it is not counted as a local pass. - Greptile reviewed current head `5bc11fa978ab87d3d9c5d575fa9666185aaafc2c` at 5/5 with no actionable findings. The full current-head CI matrix passed on attempt 2: 55 checks passed, no pending or failed checks, and two expected Storybook jobs skipped. - The first broader local attempt could not bind embedded PostgreSQL inside the sandbox (`EPERM`). It was stopped and restarted with loopback access. This was a setup failure, separate from the observed red regression. - The first CI attempt failed two existing checks: the process-adapter signoff happy path exhausted its run wait budget, and the workspace export scheduler did not reach `complete` within 20 seconds. Both tests pass in isolated local runs on the unchanged head. Both failed shards passed on their single rerun without code changes. The initial failures remain recorded. Their timing cause is not proven by the later passes. - Live acceptance at the fixed revision has not run. The hosted workspace still serves the earlier release. No deployment or retry of the original task is claimed. ## Risks The new checkpoint read runs only for same-run plugin recovery with a replacement lease. Missing termination proof, changed scope, or a changed Runner identity still stops execution. The lease resolver owns these checks. The fix does not replay tools or change retry budgets. A turn that omitted its completion result still needs the existing bounded continuation to finish useful work. ## Model Used OpenAI GPT-6 through Codex, with reasoning, repository tools, and code execution. The runtime does not expose a more specific backend model ID or context-window size. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge Co-authored-by: Paperclip <noreply@paperclip.ing>
10 KiB
Local, SSH, and sandbox environments — agent access
Product map: Local, SSH, and sandbox environments.
Feature ID: execution-environments.
Review date: 2026-10-12. Source commit: f981fa3cc10cb8663a87dec60345fbff46d54d0a.
This is a source-reviewed baseline of representative operations and known gaps. Each capability needs operation-level review before its entire scope can be qualified. No live agent execution is claimed. Follow the map contract for format, permission checks, evidence and maintenance.
Scoped immutable-platform source review: 2026-10-12 at
d16eccf109b524778ceb896f79ccb3881bc61a9b, limited to saved sandbox probing,
server-owned qualification metadata and read/invalidation behavior. The original
baseline commit and review depth remain for unrelated operations; no live agent
or provider qualification is claimed by this update.
configuration
Capability ID: execution-environments/configuration.
Review: baseline.
API: present — representative operation IDs:
GET /api/companies/{companyId}/environments.POST /api/companies/{companyId}/environments.
Agent access: restricted — Board read/admin management REST / CLI environment.
Policy: Environment management is instance administrator/board; permitted assignment uses agent/project policy.
Evidence: source-only — implementation
at the reviewed commit above.
Verification: not-run — assert the documented agent denial with an owned test fixture;
verify any listed agent request/result path separately. A delegated operation needs its
own policy and access review.
Gaps: API exists; an agent cannot use instance environment management as an ordinary company actor.
Scoped source review: environment routes require board organization access for reads and local-implicit board or instance administrator for management. Create/PATCH reject client-supplied platform-proof metadata; service updates discard supplied proof, preserve current server proof atomically for metadata-only edits, and invalidate it when the target configuration or driver changes. Public row responses hide the private record. This is source-only at the scoped commit. Verify forged metadata rejection, concurrent probe/update preservation, target invalidation and restricted-reader redaction; actual agent-denial proof remains not run. Company/team packages do not import or export environment rows, so those packages do not transfer platform qualification.
capabilities
Capability ID: execution-environments/capabilities.
Review: baseline.
API: present — representative operation IDs:
GET /api/companies/{companyId}/environments/capabilities.
Agent access: partial — Board environment capabilities endpoint; native run gets
server-selected runtime context.
Policy: Environment management is instance administrator/board; permitted assignment uses agent/project policy.
Evidence: source-only — implementation
at the reviewed commit above.
Verification: not-run — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability.
Gaps: Endpoint discovery and already-bound run capabilities differ; decide whether a safe agent-readable capability listing is desired.
probe
Capability ID: execution-environments/probe.
Review: baseline.
API: present — representative operation IDs:
POST /api/environments/{id}/probe.POST /api/companies/{companyId}/environments/probe-config.
Agent access: restricted — Board/admin probes / CLI environment.
Policy: Environment management is instance administrator/board; permitted assignment uses agent/project policy.
Both probe endpoints require a board actor that is local-implicit or an instance administrator; ordinary agent identity and company membership alone are denied. The saved sandbox probe also resolves company/environment and secret access before allocating a fresh lease. Its measurement is company-bound to an immutable image digest or verified Daytona snapshot ID, effective provider configuration and active custom-image identity; only confirmed cleanup permits recording it. A draft probe does not record saved qualification. Reading stored qualification does not lease/provision a target and does not grant an agent permission to probe or manage that target.
Evidence: source-only — implementation
at the reviewed commit above.
Verification: not-run — assert the documented agent denial with an owned test fixture;
verify any listed agent request/result path separately. A delegated operation needs its
own policy and access review.
Gaps: Reachability probes are not granted by an agent's right to execute assigned work.
Scoped Evidence: source-only — probe authorization,
immutable binding, measurement and read,
private metadata writes and
custom-image binding
at the scoped commit. A connection-only success or a fixture cannot certify
native compatibility, account authentication or agent access.
Scoped Verification: not-run — on one authorized owned target, compare pinned
image and provider snapshot-ID proof with mutable-image, unverified-snapshot
and changed-config/account controls; require independent
cleanup evidence before recording proof. Assert agent/non-admin board denial,
secret-context denial where the actor lacks access and forged-proof rejection.
Verify API reads hide the private record and metadata-only updates cannot overwrite it. Then use
runtime validation for account/model/native startup.
There is no new delegated agent probe binding or client proof-write API. Any human-action request/result handoff requires its own admitted path and verification; an accepted interaction does not turn the caller into a board administrator.
assignment
Capability ID: execution-environments/assignment.
Review: baseline.
API: present — representative operation IDs:
PATCH /api/agents/{id}.PATCH /api/projects/{id}.
Agent access: partial — Permitted agent/project REST / native fallback, subject to
protected configuration policy.
Policy: Environment management is instance administrator/board; permitted assignment uses agent/project policy.
Evidence: source-only — implementation
at the reviewed commit above.
Verification: not-run — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability.
Gaps: Choosing among permitted targets differs from creating/configuring host targets; test authorized and denied selection.
Scoped plugin execution update: paperclip_runner supports a saved plugin
environment through the server-selected lease and the SDK environmentTask RPC.
This is an execution path, not a new agent-callable management endpoint. Host
company/project checks and native PRP authorization remain required; declaring a
plugin capability does not authorize the agent to change its environment.
The integration fixture
exercises the host and SDK with synthetic tasks and a mocked WebSocket.
The task API does not transfer files or reveal guest filesystem paths.
This source update does not qualify live agent access, warm retention, or a provider.
See the execution contract.
Same-run checkpoint recovery also uses the saved lease path after a turn omits its completion result. It requires verified prior termination, retained session state, and matching company, agent, workspace, and complete Runner identity. The executor regression checks checkpoint retrieval and identity/termination denials. The lease authority fixture checks the same-run read through the database-backed task API. These are controlled regressions; live provider acceptance remains separate.
images
Capability ID: execution-environments/images.
Review: baseline.
API: present — representative operation IDs:
POST /api/environments/{environmentId}/custom-image-setup-sessions.
Agent access: restricted — Board/admin image APIs and existing terminal protocol.
Policy: Environment management is instance administrator/board; permitted assignment uses agent/project policy.
Evidence: source-only — implementation
at the reviewed commit above.
Verification: not-run — assert the documented agent denial with an owned test fixture;
verify any listed agent request/result path separately. A delegated operation needs its
own policy and access review.
Gaps: No default agent custom-image administration/terminal path; this is a policy decision before adding a tool.
The task-only setup path uses a Core-issued expiring probe identity and a real, read-only Runner hello. The plugin checks project authentication before provider startup. Setup probe coverage uses the real Runner and a synthetic Codex provider through loopback PRP; TLS termination is replaced by the fixture. It does not qualify a live plugin provider.
The plugin prepares execution-host resources and the provider descriptor. Core validates the result, then supplies task identity and PRP launch limits.
Managed account transfer requires projectAuthCheckVersion: 1 and a successful
check_project_auth result for the exact prepared configuration, provider, and
project set. New preparation removes old validation. Core checks the saved
validation again in the dispatch update.