mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 03:31:44 +01:00
refactor: remove doc/execution-semantics.md and its references (#21699)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Contributors and agents read the docs under `doc/` for background on run execution > - `doc/execution-semantics.md` grew to 6,310 lines of per-PR notes > - It was hard to read and it drifted from the code > - The code and tests are the source of truth for execution behavior > - This pull request removes the file and every reference to it > - The benefit is one less stale document that readers can mistake for a requirement ## Linked Issues or Issue Description **Issue type** Outdated or unclear documentation. **Where is the issue?** `doc/execution-semantics.md`, and the docs, rules, skills, maps, code comments and log text that link to it. **What's wrong?** The file is 6,310 lines of notes added one PR at a time. Much of it repeats or contradicts the code. Readers and agents treat it as a contract, but the code and tests decide the behavior. **Suggested fix** Delete the file. Remove each link to it. Keep the documents that link to it. Point at code where a pointer is still useful. Do not move the content to another doc. Refs #10664 (an open docs PR that edits this file; it becomes obsolete). ## What Changed - Delete `doc/execution-semantics.md`. - Remove links and pointers in `doc/PRODUCT.md`, `doc/LOW-TRUST-PRESETS.md`, `doc/TASK-WATCHDOG.md`, `doc/composer-stop.md`, `doc/native-workspace-finalization-recovery.md`, `doc/run-log-events.md`, `doc/runner-internals.md` and `doc/workspace-repositories.md`. - `doc/TASK-WATCHDOG.md` now points at `server/src/modules/active-run-watchdog/` for the silent active-run watchdog. - Remove the link in `rules/upgrade-safe-run-state.mdc` and `maps/feature-map/recovery.md`. - Update the skills `diagnose-why-work-stopped`, `fix-failed-paperclip-run` and `terminal-bench-loop`. The `fix-failed-paperclip-run` skill now points at `server/src/services/heartbeat/` and `server/src/services/recovery/`. - Remove the file from the source anchors in `.devin/wiki.json`. - Remove the doc name from four code comments in `server/` and `ui/`. - The failed-attachment log message no longer ends with a link to the removed doc. Two tests now check the message text instead of the link. - Leave two dated plan files under `doc/plans/` unchanged. They are history. ## Verification - `git grep -i execution-semantics` finds no hits outside `doc/plans/`. - Every relative Markdown link in the changed files resolves. - `node scripts/check-maps.mjs` passes. - `node --test .github/scripts/tests/*.test.mjs` passes (808 tests). - `pnpm verify` was not run locally. The worktree has no `node_modules`. CI runs the changed Vitest files. ## Risks - Low risk. Most changes are docs and comments. - One runtime log line is shorter. It no longer has a link. No logic changes. - Open PRs that edit the deleted file, such as #10664, will conflict. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use and shell access. ## 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 - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
adc3356ad3
commit
11b09b7234
22 files changed
+33
-6374
No files matched your search
@@ -16,7 +16,7 @@ approval before implementation, perform the investigation and safety analysis
|
||||
within that scope. For example, a Terminal-Bench diagnosis child does not override
|
||||
the loop's board approval boundary. Keep the next action and its owner explicit.
|
||||
|
||||
For issue-tree diagnosis, read the current `doc/execution-semantics.md`, inspect the
|
||||
For issue-tree diagnosis, inspect the
|
||||
relevant subtree and recent repairs, and classify non-progressing nodes:
|
||||
|
||||
- **Genuine wait:** a named human or external dependency must act.
|
||||
|
||||
@@ -43,9 +43,9 @@ Use authorized diagnostic access. If company scoping blocks a read, use an
|
||||
already-authorized diagnostic path or label the missing evidence; do not bypass
|
||||
the boundary.
|
||||
|
||||
Read repository instructions and the relevant current execution contract. In this
|
||||
repository, use `doc/execution-semantics.md` for ownership, continuation, waiting,
|
||||
finalization, and recovery. Inspect recent changes and open/merged repairs in the
|
||||
Read repository instructions. In this repository, the code and tests under
|
||||
`server/src/services/heartbeat/` and `server/src/services/recovery/` define
|
||||
ownership, continuation, waiting, finalization, and recovery. Inspect recent changes and open/merged repairs in the
|
||||
affected area. A correct fix that has not reached the target is a deployment gap;
|
||||
do not create a second patch without evidence that the first is insufficient.
|
||||
Choose code repair, configuration repair, or recovery from that evidence. If an
|
||||
|
||||
@@ -12,7 +12,7 @@ A repeatable operating skill for driving one Terminal-Bench problem to a passing
|
||||
|
||||
This skill is **operational + diagnostic**, not engineering. It coordinates issues, artifacts, and approvals around a Terminal-Bench loop. It does not authorize code changes — product fixes require a board confirmation before implementation.
|
||||
|
||||
Canonical execution model: read `doc/execution-semantics.md` before starting a loop or moving any loop issue. Every loop issue must rest in a state the doc allows: terminal (`done`/`cancelled`), explicitly live (active run / queued wake), explicitly waiting (`in_review` with participant/interaction/approval), or explicit recovery/blocker (`blocked` with `blockedByIssueIds` and a named owner).
|
||||
Every loop issue must rest in an allowed state: terminal (`done`/`cancelled`), explicitly live (active run / queued wake), explicitly waiting (`in_review` with participant/interaction/approval), or explicit recovery/blocker (`blocked` with `blockedByIssueIds` and a named owner).
|
||||
|
||||
## When to use
|
||||
|
||||
@@ -77,7 +77,7 @@ Wire dependencies with `blockedByIssueIds`, never with prose like "blocked by X"
|
||||
|
||||
### 0. Read the current execution contract
|
||||
|
||||
Before opening or advancing a loop, read `doc/execution-semantics.md`. Use that document's terms intact when classifying loop-issue state: live path / waiting path / recovery path; post-run disposition; bounded continuation; productivity review; pause-hold; watchdog. Do not invent a new state.
|
||||
Before opening or advancing a loop, use these terms when classifying loop-issue state: live path / waiting path / recovery path; post-run disposition; bounded continuation; productivity review; pause-hold; watchdog. Do not invent a new state.
|
||||
|
||||
### 1. Open or reuse the top-level loop issue
|
||||
|
||||
|
||||
+5
-5
@@ -4,7 +4,7 @@
|
||||
"content": "Audience and outcome: write a guided architecture handbook for contributors and coding agents. Help a reader understand the control plane, trace a task through the code, choose the right place to change behavior, and find the tests that protect it. Explain the problem and mental model before introducing symbols. Prefer a concrete example and a short causal explanation to exhaustive class, endpoint, package, or configuration inventories. Use plain language and define abbreviations on first use."
|
||||
},
|
||||
{
|
||||
"content": "Evidence and document authority: use current implementation, schemas, configuration, public exports, and tests to establish what ships in the indexed revision. Read `doc/GOAL.md` and `doc/PRODUCT.md` for intent; the focused docs under `doc/` (for example `doc/execution-semantics.md`) give background on policy. Contributor instructions such as `AGENTS.md` are not implementation evidence. Explain material disagreements between code and policy instead of silently treating either as proof of the other. Plans, historical snapshots, proposed ADRs, prototypes, fixtures, and roadmap entries do not establish shipping behavior. Verify their claims against production wiring and distinguish implemented, gated/experimental, and proposed behavior."
|
||||
"content": "Evidence and document authority: use current implementation, schemas, configuration, public exports, and tests to establish what ships in the indexed revision. Read `doc/GOAL.md` and `doc/PRODUCT.md` for intent; the focused docs under `doc/` give background on policy. Contributor instructions such as `AGENTS.md` are not implementation evidence. Explain material disagreements between code and policy instead of silently treating either as proof of the other. Plans, historical snapshots, proposed ADRs, prototypes, fixtures, and roadmap entries do not establish shipping behavior. Verify their claims against production wiring and distinguish implemented, gated/experimental, and proposed behavior."
|
||||
},
|
||||
{
|
||||
"content": "Page contract: each subsystem page should explain the problem it solves, what it owns, its inputs and outputs, authoritative persisted state, and its boundaries with neighboring systems. Trace one representative flow through actual entry points. Include a compact 'Where to change it' map linking responsibilities to source, relevant regression tests with the behavior they protect, and practical investigation steps for characteristic failures. Cite the code that performs a decision or effect rather than an import list or unrelated file. A passing unit fixture does not establish live provider support. Parent pages should offer reading routes, boundary maps, or diagnostic routing instead of repeating all their children."
|
||||
@@ -60,7 +60,7 @@
|
||||
"content": "Use a concept-to-schema/service table for company, agent/org tree, goal, project, task/issue, wake, run, session, approval/interaction, and work product. Explain company scope and documented instance-level exceptions without asserting every table has identical tenancy. Distinguish assignment from execution ownership, parent/child structure from blockers, and business goals from provider session goals. Give concrete examples of atomic checkout, company-boundary rejection, and a durable wait. Explain where these invariants are enforced and tested; leave full state transitions, permissions, and database operations to their owning pages."
|
||||
},
|
||||
{
|
||||
"content": "Source anchors: `doc/execution-semantics.md`, `packages/db/src/schema/index.ts`, `packages/db/src/schema/issues.ts`, `packages/db/src/schema/agents.ts`, `packages/db/src/schema/heartbeat_runs.ts`, `packages/db/src/schema/agent_task_sessions.ts`, `packages/shared/src/constants.ts`, `server/src/services/issues.ts`. Regression anchors: `server/src/__tests__/authz-company-access.test.ts`, `server/src/__tests__/issues-service.test.ts`, `server/src/__tests__/heartbeat-auto-checkout.test.ts`."
|
||||
"content": "Source anchors: `packages/db/src/schema/index.ts`, `packages/db/src/schema/issues.ts`, `packages/db/src/schema/agents.ts`, `packages/db/src/schema/heartbeat_runs.ts`, `packages/db/src/schema/agent_task_sessions.ts`, `packages/shared/src/constants.ts`, `server/src/services/issues.ts`. Regression anchors: `server/src/__tests__/authz-company-access.test.ts`, `server/src/__tests__/issues-service.test.ts`, `server/src/__tests__/heartbeat-auto-checkout.test.ts`."
|
||||
}
|
||||
]
|
||||
},
|
||||
@@ -162,7 +162,7 @@
|
||||
"content": "Introduce the control loop: accepted work, eligible wake, owned execution, persisted outcome, and either completion, durable waiting, continuation, or visible recovery. Use a responsibility table for issue service, wake queue, dispatch gates, heartbeat orchestration, status arbitration, and recovery. Explain that orchestration policies stay in Paperclip even when execution is remote. Provide a short symptom routing table for never-started work, blocked work, review waits, repeated turns, and interrupted work. Link to the four child pages and Run Agents; keep provider transports and detailed state machines out of this parent."
|
||||
},
|
||||
{
|
||||
"content": "Source anchors: `doc/execution-semantics.md`, `server/src/services/issues.ts`, `server/src/modules/wake-queue/index.ts`, `server/src/modules/run-dispatch/index.ts`, `server/src/services/heartbeat.ts`, `server/src/services/recovery/service.ts`, `server/src/services/native-runtime/status-arbiter.ts`. Policy evidence: `server/src/modules/wake-queue/domain/policy.test.ts`, `server/src/modules/run-dispatch/domain/policy.test.ts`."
|
||||
"content": "Source anchors: `server/src/services/issues.ts`, `server/src/modules/wake-queue/index.ts`, `server/src/modules/run-dispatch/index.ts`, `server/src/services/heartbeat.ts`, `server/src/services/recovery/service.ts`, `server/src/services/native-runtime/status-arbiter.ts`. Policy evidence: `server/src/modules/wake-queue/domain/policy.test.ts`, `server/src/modules/run-dispatch/domain/policy.test.ts`."
|
||||
}
|
||||
]
|
||||
},
|
||||
@@ -214,7 +214,7 @@
|
||||
"content": "Separate operator stop/cancel/pause, provider failure, controller restart, network loss, output silence, and stranded-task recovery. Trace direct-adapter controller ownership separately from native runner leases, reconnect, and replacement evidence. Explain when replay/reattachment is safe, why transport redelivery is not permission to replay side-effecting tools, and what prevents two controllers from owning execution. Distinguish source-scoped recovery actions, independent repair tasks, bounded same-owner retries, board escalation, and explicitly configured task watchdogs. Explain stopped-run cleanup and later user messages. Diagnose using durable identity/lease/decision records before suggesting retries; link scheduler and status details elsewhere."
|
||||
},
|
||||
{
|
||||
"content": "Source anchors: `doc/execution-semantics.md`, `server/src/services/recovery/service.ts`, `server/src/services/legacy-execution-recovery.ts`, `server/src/services/native-runtime/native-runner-ownership.ts`, `server/src/services/native-runtime/native-safe-replacement.ts`, `server/src/modules/active-run-watchdog/index.ts`. Regression anchors: `server/src/__tests__/issue-recovery-actions.test.ts`, `server/src/services/legacy-execution-recovery.test.ts`, `server/src/services/native-runtime/native-runner-restart-recovery.integration.test.ts`."
|
||||
"content": "Source anchors: `server/src/services/recovery/service.ts`, `server/src/services/legacy-execution-recovery.ts`, `server/src/services/native-runtime/native-runner-ownership.ts`, `server/src/services/native-runtime/native-safe-replacement.ts`, `server/src/modules/active-run-watchdog/index.ts`. Regression anchors: `server/src/__tests__/issue-recovery-actions.test.ts`, `server/src/services/legacy-execution-recovery.test.ts`, `server/src/services/native-runtime/native-runner-restart-recovery.integration.test.ts`."
|
||||
}
|
||||
]
|
||||
},
|
||||
@@ -354,7 +354,7 @@
|
||||
"content": "Organize this landing page around six questions: where to add a company-scoped feature, why assigned work did not start, why a successful run left a task open, who owns cancellation/restart recovery, how a tool obtained authority/credentials, and where a deliverable or diagnostic event went. For each, name the first durable record or decision to inspect and link the owning page. Explain company/actor/task/run correlation and distinguish activity history, run events, traces, telemetry, transcripts, and artifacts. Include an example investigation that follows evidence across layers without treating a UI symptom or model claim as the root cause. Avoid prescribing blind retries or copying sensitive payloads into reports."
|
||||
},
|
||||
{
|
||||
"content": "Source anchors: `doc/execution-semantics.md`, `doc/run-log-events.md`, `doc/observability.md`, `doc/AGENT-ARTIFACTS.md`, `server/src/routes/authz.ts`, `server/src/services/budgets.ts`, `server/src/services/work-products.ts`. Regression anchors: `server/src/__tests__/authz-company-access.test.ts`, `server/src/__tests__/budgets-service.test.ts`, `server/src/__tests__/work-product-runtime-reconciliation.test.ts`. Link orchestration and runtime investigations back to those chapters rather than repeating their state machines."
|
||||
"content": "Source anchors: `doc/run-log-events.md`, `doc/observability.md`, `doc/AGENT-ARTIFACTS.md`, `server/src/routes/authz.ts`, `server/src/services/budgets.ts`, `server/src/services/work-products.ts`. Regression anchors: `server/src/__tests__/authz-company-access.test.ts`, `server/src/__tests__/budgets-service.test.ts`, `server/src/__tests__/work-product-runtime-reconciliation.test.ts`. Link orchestration and runtime investigations back to those chapters rather than repeating their state machines."
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
@@ -126,8 +126,7 @@ company-boundary checks.
|
||||
|
||||
## Child→Parent Reporting Under Containment
|
||||
|
||||
The direct-parent report comment (`doc/execution-semantics.md` §6, "Child→Parent
|
||||
Reporting") is **off by default** for `low_trust_review`: a contained run reads
|
||||
The direct-parent report comment is **off by default** for `low_trust_review`: a contained run reads
|
||||
untrusted input, so a free-prose comment into the higher-trust parent thread is
|
||||
a prompt-injection promotion path. Contained reviewers report by completing
|
||||
their own review issue (`done` — the verdict is the deliverable; the
|
||||
|
||||
+1
-1
@@ -544,7 +544,7 @@ The agent performs authorized setup, reuses saved accounts and drafts, and hands
|
||||
|
||||
Authorized policy administration includes user-requested changes that loosen the acting agent’s own tool controls. These writes remain bounded by management grants, resource scope and the responsible user’s current authority; they do not need an additional approval solely because the agent is a target. Subsequent tool calls obey the resulting policy. Agents cannot approve their own governed action requests or edit their own principal permission grants.
|
||||
|
||||
Ordinary tool approvals remain reviewable without an implicit one-hour deadline. Authenticated OAuth refresh preserves a pending approval for the same saved action and authorization. Sign-in repair retains an accepted decision and resumes through connection-change events after revalidation; changed consent, permissions, credentials or action targets require a new review. Current access, explicit deadlines, task closure and execution receipts remain enforced. See [Delayed tool approvals](execution-semantics.md#delayed-tool-approvals).
|
||||
Ordinary tool approvals remain reviewable without an implicit one-hour deadline. Authenticated OAuth refresh preserves a pending approval for the same saved action and authorization. Sign-in repair retains an accepted decision and resumes through connection-change events after revalidation; changed consent, permissions, credentials or action targets require a new review. Current access, explicit deadlines, task closure and execution receipts remain enforced.
|
||||
|
||||
The implementation, operation inventory, permission matrix and fixture qualification are recorded in [Agent API parity for connection configuration](plans/2026-10-13-connection-api-parity.md). Provider fixtures establish API behavior; they do not constitute live provider setup or an empirical agent-success claim.
|
||||
|
||||
|
||||
@@ -30,7 +30,7 @@ Agents can stop work for the wrong reasons: misreading a blocker, accepting a st
|
||||
|
||||
A task watchdog gives you a second pass on stopped work without rerunning the original assignee. It is verification-shaped, not execution-shaped: the watchdog reads what other agents claimed, checks it against the evidence in the thread, and either accepts the stop or restores a live path.
|
||||
|
||||
It is **not** an output-silence monitor for active runs. That is a separate mechanism — the silent active-run watchdog described in [`doc/execution-semantics.md`](execution-semantics.md) §12. Task watchdog only fires when the whole watched subtree has come to rest.
|
||||
It is **not** an output-silence monitor for active runs. That is a separate mechanism — the silent active-run watchdog in `server/src/modules/active-run-watchdog/`. Task watchdog only fires when the whole watched subtree has come to rest.
|
||||
|
||||
---
|
||||
|
||||
@@ -112,7 +112,7 @@ The mandate also enforces safety constraints that custom instructions **cannot o
|
||||
- No creating another watchdog for the watched subtree. No waking itself. Exactly one reusable review task per watched issue.
|
||||
- Custom instructions can narrow focus or veto specific shortcuts. They cannot grant authority the server does not already give the watchdog.
|
||||
|
||||
The formal authority contract (the full list of allowed and disallowed mutations) is in [Authority contract](#authority-contract) below. The ordinary interaction resolver contract is in [execution semantics](execution-semantics.md#issue-thread-interaction-resolution).
|
||||
The formal authority contract (the full list of allowed and disallowed mutations) is in [Authority contract](#authority-contract) below.
|
||||
|
||||
### Writing custom instructions
|
||||
|
||||
@@ -198,10 +198,6 @@ Within the watched subtree, a watchdog run may perform only mutations that resto
|
||||
|
||||
Every watchdog-triggered mutation must write activity with the watchdog id, source issue id, watchdog issue id when present, run id, and stop fingerprint. Mutations still use the normal status-transition, blocker, assignment, budget, and company-boundary guards.
|
||||
|
||||
The atomic recovery batch, restoration verification and escalation, and interaction
|
||||
resolution rules for watchdog runs are in
|
||||
[execution semantics §11](execution-semantics.md#11-task-watchdog-for-issue-trees).
|
||||
|
||||
### Disallowed watchdog mutations
|
||||
|
||||
A task watchdog must not:
|
||||
@@ -229,8 +225,7 @@ Deliberately deferred and disallowed for the first implementation: letting watch
|
||||
| Topic | File |
|
||||
| -------------------------------- | --------------------------------------------------------------------- |
|
||||
| Authority contract (formal) | [Authority contract](#authority-contract) (this doc) |
|
||||
| Execution semantics (formal) | [`doc/execution-semantics.md`](execution-semantics.md) §11 |
|
||||
| Silent active-run watchdog | [`doc/execution-semantics.md`](execution-semantics.md) §12 |
|
||||
| Silent active-run watchdog | `server/src/modules/active-run-watchdog/` |
|
||||
| Database schema | `packages/db/src/schema/issue_watchdogs.ts` |
|
||||
| Server service | `server/src/services/task-watchdogs.ts` |
|
||||
| Scope enforcement | `server/src/services/task-watchdog-scope.ts` |
|
||||
|
||||
@@ -19,7 +19,7 @@ terminal tasks. Resume/restore retain the optional wake-agents checkbox.
|
||||
## Resume and execution recovery
|
||||
|
||||
Resume releases a hold. Work the pause interrupted is re-dispatched once
|
||||
automatically, under current admission gates (see `doc/execution-semantics.md`).
|
||||
automatically, under current admission gates.
|
||||
Waking other agents is optional and only applies to tasks in
|
||||
`todo`, `in_progress`, or `in_review`; parked and terminal tasks stay untouched.
|
||||
The current execution-recovery policy requires verified outcomes before a stopped
|
||||
|
||||
File diff suppressed because it is too large.
Load diff
@@ -369,8 +369,7 @@ refuses any archive whose manifest names an absolute or escaping link. Omitting
|
||||
a tracked link shows as a deletion in `git status` after restore.
|
||||
|
||||
Saves that recovery exhausted before this policy (capture policy version 1) are
|
||||
retried once automatically; see the capture-policy re-arm in
|
||||
`doc/execution-semantics.md`.
|
||||
retried once automatically.
|
||||
|
||||
## Automatic unsafe archive recovery
|
||||
|
||||
|
||||
@@ -462,7 +462,7 @@ runner lifecycle, `other` for an unknown value, or `unavailable` when the state
|
||||
none. `runnerSettled` is true only when the outbox is empty and no terminal delivery,
|
||||
provider cleanup or warm transition is pending. These fields explain how the runner
|
||||
stopped. The event is not recorded when a scheduled retry resumes a runner that
|
||||
exited after a settled suspension; see `doc/execution-semantics.md`.
|
||||
exited after a settled suspension.
|
||||
|
||||
`native.interrupted_turn_outcome_unknown` (level `warn`) is recorded once on a
|
||||
failed run whose reattachment proved the Runner process gone
|
||||
|
||||
@@ -291,8 +291,7 @@ of the same class, then the stable Runner default. The task shows a warning with
|
||||
the requested model, effective model, and CLI version. Agent and task settings
|
||||
stay unchanged. Update the image CLI to restore the requested model on later
|
||||
runs. Explicit `PAPERCLIP_RUNNER_REMOTE_CODEX_PATH` and
|
||||
`PAPERCLIP_RUNNER_REMOTE_CODEX_NPM_SPEC` settings take precedence. See
|
||||
[execution semantics](execution-semantics.md#remote-codex-model-compatibility).
|
||||
`PAPERCLIP_RUNNER_REMOTE_CODEX_NPM_SPEC` settings take precedence.
|
||||
|
||||
### Sandbox ACP input delivery
|
||||
|
||||
|
||||
@@ -105,7 +105,7 @@ Paperclip applies one process-wide scheduler to expensive host-side workspace Gi
|
||||
|
||||
The shared scan subprocess sets `GIT_OPTIONAL_LOCKS=0`, including when a caller supplies an environment. This prevents background `git status` from rewriting the index's stat cache and competing with workspace writers. Git still computes current tracked and untracked changes. Required write locks remain enforced; existing lock files are never removed or treated as stale by a scan. This avoids optional index refresh work but may make later scans repeat stat checks. See Git's [background refresh guidance](https://git-scm.com/docs/git-status#_background_refresh).
|
||||
|
||||
Workspace snapshots list ignored paths with `git ls-files --others --ignored --exclude-standard --directory -z` so ignored directory contents do not require a full status walk. Changed, untracked, deleted, and ignored filename lists stream into private SQLite manifests. There is no total filename-list byte limit. The parser and each sink chunk are limited to 64 KiB, and each SQLite connection uses a 1 MiB page cache with disk-backed temporary storage. Records must be complete NUL-delimited UTF-8 paths. Invalid, oversized, or incomplete records fail the scan. Explicit file selection excludes files created after the scan. Buffered browser/guard and referenced-source scan bounds stay unchanged. Snapshot failures retain their typed cause instead of becoming a non-Git-folder result. During pre-provider setup, scan timeouts and queue saturation use the existing two automatic failure retries with a 30-second delay. Cancellation, output limits, and other Git errors stop with specific recovery guidance. See `doc/execution-semantics.md` for the ownership and retry-budget contract.
|
||||
Workspace snapshots list ignored paths with `git ls-files --others --ignored --exclude-standard --directory -z` so ignored directory contents do not require a full status walk. Changed, untracked, deleted, and ignored filename lists stream into private SQLite manifests. There is no total filename-list byte limit. The parser and each sink chunk are limited to 64 KiB, and each SQLite connection uses a 1 MiB page cache with disk-backed temporary storage. Records must be complete NUL-delimited UTF-8 paths. Invalid, oversized, or incomplete records fail the scan. Explicit file selection excludes files created after the scan. Buffered browser/guard and referenced-source scan bounds stay unchanged. Snapshot failures retain their typed cause instead of becoming a non-Git-folder result. During pre-provider setup, scan timeouts and queue saturation use the existing two automatic failure retries with a 30-second delay. Cancellation, output limits, and other Git errors stop with specific recovery guidance.
|
||||
|
||||
|
||||
Snapshot scans default to a 30-minute execution deadline, including disk backpressure, rather than the short interactive scan deadline. Set `PAPERCLIP_WORKSPACE_GIT_SNAPSHOT_TIMEOUT_MS` to allow slower storage or larger trees (1 second to 24 hours). Disk capacity, filesystem path limits, Git's own resource use, and this execution budget remain practical limits. Each manifest is admitted with a page allowance equal to one quarter of the available bytes above the host reserve at creation. SQLite enforces that allowance before page allocation, so one snapshot cannot consume all available storage. This is a disk-capacity admission policy, not a fixed filename-list byte or record limit. Nested repository and baseline manifests receive separate allowances from the remaining capacity. Manifest writers also check available disk space before creation and at most every 1 MiB of input thereafter. They stop below a 256 MiB free-space reserve. `PAPERCLIP_WORKSPACE_MANIFEST_MIN_FREE_BYTES` can raise or lower the reserve, with a 64 MiB minimum. Concurrent writers can consume space between checks; filesystem quota and write errors still fail the operation. The scheduler keeps the active slot until the child, pipes, and pending sink write finish. Snapshot failures cancel sibling producers and settle all started producers before removing temporary storage.
|
||||
|
||||
@@ -468,8 +468,7 @@ only. Separately inspect the underlying execution if it is still stuck.
|
||||
silently trigger recovery that fights the user's instruction.
|
||||
- Source inspection and mocked component tests do not qualify real server
|
||||
restart continuity. Use the appropriate runtime suite for that claim.
|
||||
- See [execution semantics](../../doc/execution-semantics.md) for the governing
|
||||
recovery contract and [steering](./steering.md) for saved follow-ups.
|
||||
- See [steering](./steering.md) for saved follow-ups.
|
||||
|
||||
### Storybook verification
|
||||
|
||||
|
||||
@@ -65,6 +65,3 @@ Persisted run identity includes:
|
||||
where the run can be in flight?
|
||||
- Is the fix class-level, rather than one more per-code exception?
|
||||
- Do remote-sandbox paths have a test that applies the provider's confinement?
|
||||
|
||||
The release-compatibility contract is stated in
|
||||
[`doc/execution-semantics.md`](../doc/execution-semantics.md#94-release-compatibility-of-saved-run-state).
|
||||
@@ -2888,8 +2888,7 @@ export function createHeartbeatRecovery(db: Db, dependencies: HeartbeatRecoveryD
|
||||
const shouldRetry =
|
||||
!await pendingCaseHandoffForRun(db, run.id, run.companyId) &&
|
||||
// Process loss spends the durable failure retry budget that
|
||||
// enqueueProcessLossRetry schedules against (execution-semantics
|
||||
// "Shutdown, process loss, and provider failure"). Checking it here
|
||||
// enqueueProcessLossRetry schedules against. Checking it here
|
||||
// keeps "retrying once" honest and lets an exhausted chain fall
|
||||
// through to the interaction continuation path below.
|
||||
// A conversation run that a restart ended draws on the server-restart
|
||||
|
||||
@@ -716,14 +716,14 @@ describe.skipIf(!support.supported)("heartbeat runtime execution boundary", () =
|
||||
expectCleanup(input);
|
||||
});
|
||||
|
||||
it("logs a pointer to the docs when a same-run retry follows a failed attachment", async () => {
|
||||
it("logs an explanation when a same-run retry follows a failed attachment", async () => {
|
||||
const { input, run } = await fixture(true);
|
||||
await db.update(heartbeatRuns).set({ nativeIssueId: input.task.issueId }).where(eq(heartbeatRuns.id, run.id));
|
||||
await db.insert(nativeRunFinalizations).values({ companyId: run.companyId, issueId: input.task.issueId!, runId: run.id, phase: "retryable_failure" });
|
||||
const error = new Error('native_session_recovery_failed: Error: PRP command run.attach failed: {"result":{"message":"run.attach requires a settled Codex provider session: active_turn"}}');
|
||||
vi.mocked(executePaperclipNativeSession).mockRejectedValueOnce(error);
|
||||
await expect(executeHeartbeatRuntime(db, input)).rejects.toMatchObject({ name: "NativeSessionResumeScheduledError", original: error });
|
||||
expect(input.output.onLog).toHaveBeenCalledWith("stderr", expect.stringContaining("doc/execution-semantics.md#session-settlement-after-a-run"));
|
||||
expect(input.output.onLog).toHaveBeenCalledWith("stderr", expect.stringContaining("A later run may start a new provider thread."));
|
||||
expect(input.output.onLog).toHaveBeenCalledWith("stderr", expect.stringContaining("run.attach requires a settled Codex provider session: active_turn"));
|
||||
expectCleanup(input);
|
||||
});
|
||||
|
||||
@@ -78,11 +78,11 @@ describe("settled remote warm control evidence", () => {
|
||||
.toBe("provider.notice.recorded x2, session.goal.snapshot x1");
|
||||
});
|
||||
|
||||
it("points a failed attachment at the reviewed docs with its real cause", () => {
|
||||
it("explains a failed attachment with its real cause", () => {
|
||||
const stored = 'native_session_recovery_failed: Error: PRP command run.attach failed: {"commandType":"run.attach","result":{"code":"command_execution_failed","message":"run.attach requires a settled Codex provider session: active_turn"},"status":"failed"}';
|
||||
const pointer = describeFailedAttachment(stored);
|
||||
expect(pointer).toContain("run.attach requires a settled Codex provider session: active_turn");
|
||||
expect(pointer).toContain("https://github.com/paperclipai/paperclip/blob/master/doc/execution-semantics.md#session-settlement-after-a-run");
|
||||
expect(pointer).toContain("A later run may start a new provider thread.");
|
||||
expect(describeFailedAttachment("run.attach requires the restored Codex provider process")).toContain("restored Codex provider process");
|
||||
const quoted = `PRP command run.attach failed: ${JSON.stringify({ result: { message: 'run.attach provider is invalid: unknown "value" here' } })}`;
|
||||
expect(describeFailedAttachment(quoted)).toContain('run.attach provider is invalid: unknown "value" here. A later run');
|
||||
|
||||
@@ -157,16 +157,14 @@ export function describeOwnFailedAttachment(recoveryHistory: unknown): string {
|
||||
return `runner_state_identity_mismatch: prior_attach_failed: ${typeof cause === "string" && cause ? cause : "unknown"}`;
|
||||
}
|
||||
|
||||
const SETTLEMENT_DOC = "https://github.com/paperclipai/paperclip/blob/master/doc/execution-semantics.md#session-settlement-after-a-run";
|
||||
|
||||
/** Points whoever diagnoses a failed attachment at reviewed docs. The stored
|
||||
* failure is already redacted and bounded; other failures produce no pointer. */
|
||||
/** Explains a failed attachment to whoever diagnoses it. The stored failure is
|
||||
* already redacted and bounded; other failures produce no explanation. */
|
||||
export function describeFailedAttachment(failureMessage: unknown): string | null {
|
||||
if (typeof failureMessage !== "string" || !/\brun\.attach (failed|requires)\b/.test(failureMessage)) return null;
|
||||
const encoded = /"message":("(?:[^"\\]|\\.)*")/.exec(failureMessage)?.[1];
|
||||
let cause = failureMessage;
|
||||
try { if (encoded) cause = JSON.parse(encoded) as string; } catch { /* Keep the whole failure. */ }
|
||||
return `This run could not attach to its provider session: ${cause}. A later run may start a new provider thread. See ${SETTLEMENT_DOC}`;
|
||||
return `This run could not attach to its provider session: ${cause}. A later run may start a new provider thread.`;
|
||||
}
|
||||
|
||||
type WarmRecoveryRefusal = "identity_incomplete" | "target_not_resumed_sandbox" | "owner_unsettled" | "execution_mismatch"
|
||||
|
||||
@@ -616,7 +616,7 @@ async function checkVisibleNextAction(db: Db, now: Date, limit: number): Promise
|
||||
const page = await db.select({ id: issues.id, companyId: issues.companyId, executionRunId: issues.executionRunId,
|
||||
updatedAt: issues.updatedAt })
|
||||
.from(issues).where(and(eq(issues.status, "in_progress"), isNotNull(issues.assigneeAgentId),
|
||||
// A saved monitor deadline is a first-class wait path (doc/execution-semantics.md §8).
|
||||
// A saved monitor deadline is a first-class wait path.
|
||||
or(isNull(issues.monitorNextCheckAt), lt(issues.monitorNextCheckAt, now)),
|
||||
notExists(db.select({ one: sql`1` }).from(heartbeatRuns).where(and(
|
||||
eq(heartbeatRuns.companyId, issues.companyId), inArray(heartbeatRuns.status, ACTIVE_RUN_STATUSES),
|
||||
|
||||
@@ -222,9 +222,7 @@ function GovernanceSelect({
|
||||
*
|
||||
* The open default is the headline — interactions are resolvable by anyone in
|
||||
* the company unless a row here narrows them — so the panel only offers
|
||||
* narrowing choices and never presents an unrestricted card as board-required
|
||||
* (PAP-17280, contract in `doc/execution-semantics.md`, "Issue-thread
|
||||
* interaction resolution").
|
||||
* narrowing choices and never presents an unrestricted card as board-required.
|
||||
*/
|
||||
export function InteractionGovernancePanel({
|
||||
governance,
|
||||
|
||||
@@ -1,7 +1,5 @@
|
||||
/**
|
||||
* Plain-language presentation of *who may resolve* an issue-thread interaction
|
||||
* (PAP-17280, Phase 3 of the open-default resolver contract in
|
||||
* `doc/execution-semantics.md`, "Issue-thread interaction resolution").
|
||||
* Plain-language presentation of *who may resolve* an issue-thread interaction.
|
||||
*
|
||||
* The product default is open: an interaction created without an explicit
|
||||
* `resolverPolicy` is resolvable by `anyone` in the company — the board or any
|
||||
|
||||
Reference in new issue
Block a user