Files
PaperClipAI/rules/upgrade-safe-run-state.mdc
T
DottaandClaude Opus 5.5 11b09b7234 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>
2026-11-14 20:29:25 -06:00

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?