mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-18 14:35:55 +01:00
## 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>
68 lines
3.7 KiB
Plaintext
68 lines
3.7 KiB
Plaintext
---
|
|
description: Run, session, launch, and pack state saved by one release must resume on the next or fail with a permanent, named code - never a generic retryable one.
|
|
globs: "server/src/services/native-runtime/**,server/src/services/recovery/**,server/src/services/heartbeat/session-preparation.ts,server/src/services/heartbeat/run-state.ts,server/src/services/runner-revision-mismatch.ts,server/src/services/sandbox-provider-runtime.ts,packages/paperclip-runner/**,packages/adapter-utils/src/acpx-engine/**,docker/daytona-runner/**,packages/db/src/schema/native_*.ts,packages/db/src/schema/agent_task_sessions.ts,packages/db/src/schema/run_identity_contexts.ts"
|
|
alwaysApply: false
|
|
---
|
|
|
|
# Upgrade-safe run state
|
|
|
|
## Scope and purpose
|
|
|
|
This rule covers native runtime, recovery, session preparation, runner, ACPX
|
|
engine, provider-pack, and sandbox image code, and the database schema for
|
|
native run, checkpoint, session, and run identity state. Deploys and restarts happen while
|
|
runs are saved or in flight, so state written by one release is routinely
|
|
resumed by the next. Code here must treat that cutover as a normal path, not an
|
|
edge case.
|
|
|
|
Persisted run identity includes:
|
|
|
|
- launch configuration and protected launch arguments;
|
|
- provider and runner pack identity, such as profile versions, command digests,
|
|
and pack contract digests;
|
|
- execution leases, owners, and runtime API listeners;
|
|
- saved session, thread, and checkpoint schema;
|
|
- workspace authority, paths, and sandbox confinement.
|
|
|
|
## Required behavior
|
|
|
|
- **State the previous-release story.** A change that adds, removes, or changes
|
|
persisted run or session state, launch configuration, or pack identity must
|
|
say in the PR how state saved by the previous release is handled: it carries
|
|
forward, it is migrated, or it is refused.
|
|
- **Refuse permanently and by name.** When saved identity is unknown or no longer
|
|
accepted, map it to a permanent, named error code that recovery does not
|
|
retry. Never report it as a generic retryable code such as
|
|
`native_session_interrupted`. A retry cannot change saved identity; it repeats
|
|
the refusal, and a replacement can destroy saved state.
|
|
- **Keep saved state on refusal.** A permanent refusal leaves the saved session,
|
|
checkpoint, and workspace intact and hands the run on with that named reason.
|
|
- **Fix the class.** Prefer one admission or recovery rule that classifies
|
|
release-incompatible state over adding single error codes to a list.
|
|
- **Test the cutover.** Add an old-saved/new-resumed regression that saves state
|
|
in the previous release's shape and resumes it with the new code. When a run
|
|
can be in flight at the cutover (preparing, attaching, holding a lease or
|
|
listener), add a case where the deploy or restart lands mid-run.
|
|
- **Apply remote confinement in tests.** Remote-sandbox paths need a test that
|
|
applies the provider's workspace confinement rules. A local test without them
|
|
does not prove the remote path.
|
|
|
|
## Exceptions
|
|
|
|
- A deliberate reset of saved sessions (for example an ACPX profile version
|
|
bump under [`acpx-profile-identity.mdc`](acpx-profile-identity.mdc)) is
|
|
allowed when the PR names which saved state it resets and why, and the reset
|
|
is reported with a named code rather than as an interruption.
|
|
- Refactors, comments, and logging that change no persisted shape or identity
|
|
need no cutover test.
|
|
|
|
## Review criteria
|
|
|
|
- Does the PR say how state saved by the previous release is handled?
|
|
- Does changed or unknown saved identity map to a permanent, named code instead
|
|
of a generic retryable one?
|
|
- Is there an old-saved/new-resumed regression, and a deploy-lands-mid-run case
|
|
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?
|