Recognize the persisted provider-qualified OpenCode/Pi model convention without reinterpreting legacy Codex counters. Match production USD headline event counts in Storybook while retaining other currencies in reports and the timeline.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Preserve legacy Gemini cache totals, compare provider pace warnings with the displayed company cap, and sort and limit preview financial events like production. Cover all three review cases, including both Costs surfaces.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Reuse a batch index of immutable receipt identities so settlements read only matching or newly published files. Verify unrelated receipts are read once, company locks remain available during indexing, and late publications still settle correctly.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Keep fresh budget admission blocked without cancelling the native recovery needed to close accounting. Drain every matching disk receipt under the accounting lock and retain files until ledger commit. Add PostgreSQL rollback, backlog, movement, and budget-scope regressions.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Encrypt and fsync replacement OAuth tokens before vault/grant/activity writes. Retry failed saves from the journal without consuming the old refresh token again; retain durable recovery through rollback, commit failures, restart, and lost commit responses. Fence replay against revocation and reconnect.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is an open source control plane for AI-agent companies.
> - Company skills give agents reusable work instructions.
> - Skill Studio can edit skill files and save version history.
> - Agents can create a skill, but they do not have a first-class update
tool.
> - An agent update needs a version check and safe retry behavior to
prevent lost edits.
> - This pull request adds `update_skill` through the existing company
skill file API.
> - The change keeps company policy, version history, and audit records
in one path.
## Linked Issues or Issue Description
**Subsystem affected**
Cross-cutting: the server API, shared validation, and runner tool
catalog.
**Problem or motivation**
An agent can create a company skill but cannot update its `SKILL.md`
through a first-class tool. An unguarded retry can also create duplicate
versions or overwrite a newer edit.
**Proposed solution**
Add `update_skill` with a required current version ID and a retry key.
Route it through the existing skill file API. Reject stale versions and
changed-input retries. Save the version and audit event together.
**Alternatives considered**
A separate write endpoint would duplicate the Skill Studio mutation path
and policy checks. This PR reuses that path instead.
**Roadmap alignment**
This work extends Skills Manager and Skill Studio, which are listed in
`ROADMAP.md`.
**Additional context**
The tool accepts a complete `SKILL.md`, not a partial patch. Callers
must read the current version before they edit it.
## What Changed
- Add optional version and retry fields to the existing skill file
update contract.
- Add a guarded API update with a stable retry receipt and attributed
audit event.
- Add `update_skill` to native and semantic runner tool catalogs, with
mode and policy gates.
- Add unit, integration, protocol, and semantic-tool regression
coverage.
- Document agent use and extend the OpenAPI request contract.
## Verification
- Focused tests and direct server and runner TypeScript checks passed
before this PR.
- `git diff --check` passed after the rebase onto `master`.
- CI passed on the latest PR head, including the full test matrix,
typecheck, and build. Local full typecheck and build stopped because
`cargo` is not installed. The local full test run ended without a
verdict.
- No dedicated end-to-end eval scenario was added or run. The protocol
coverage and semantic-tool test cover the new action deterministically.
- Reviewers can read a skill version, call `update_skill`, repeat the
same key, then try a stale version and a changed-input key. Only the
first edit must create a new version.
## Risks
- File writes and database transactions must stay in sync when a write
fails. The integration tests cover failed writes and retry behavior, but
CI must verify them on the PR head.
- Existing Skill Studio callers do not send the new optional
coordination fields. Their request shape remains valid.
## Model Used
- OpenAI Codex CLI assisted with this change. The runner did not expose
the exact model ID or context window. The agent used code execution and
repository tools.
## 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; exact model ID and context window were not exposed)
- [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 (focused tests; full suite
is pending CI)
- [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 (53 pass, 4 skip on the latest
head)
- [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>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Its adapters supply task context and access to Paperclip skills and
tools.
> - The default hire manual and shared prompts also repeat general work
procedures.
> - Those procedures overlap with stock provider instructions and the
Paperclip skill.
> - Existing E2E fixtures supply a QA manual, so they do not qualify the
production default.
> - This pull request reduces the generic instructions and adds real
default-hire coverage.
> - The benefit is less competing guidance, with inspectable evidence
for preserved skills and task context.
## Linked Issues or Issue Description
Refs: #14920. That merged change preserves native Codex base
instructions. This PR covers the default manual, shared legacy prompts,
operational skill guidance, and the narrowly approved ACP
skill-discovery/session-environment repair for measured delivery and
credential-persistence failures.
**What existing behavior does this improve?**
New non-CEO hires without a custom bundle and legacy task/chat startup
and continuation prompts.
**Current behavior**
The shipped default manual contains 602 words. Generic task/chat prompts
and ordinary resume deltas repeat work procedures already available
through the harness and Paperclip skill.
**Proposed behavior**
The default manual contains only the eight-word company identity. Shared
startup prompts retain identity and connection guidance. Ordinary resume
deltas retain current work context without the generic execution
contract.
**Reason and benefit**
Let the stock harness guide general work. Keep Paperclip-specific
capabilities and independently test default hires, skills, ordered
comments, and chat restart.
**Breaking changes**
New default hires receive less guidance. Existing saved manuals,
explicit custom bundles, CEO templates, and specialized wake contracts
retain their behavior. The obsolete includeExecutionContract option
remains accepted for source compatibility.
## What Changed
- Reduce the default hire manual to one sentence.
- Reduce shared task/chat defaults and remove the generic
ordinary-resume contract.
- Keep connection guidance, auth, skills, custom prompts, and
specialized wake context.
- Add credential-free instruction-boundary gates and 26 explicit Product
E2E cells across eight legacy/native profiles, including two focused
Paperclip-storage cases.
- Capture public hire receipts before providers run, then grade
delivered prompts and independent task/chat outcomes.
- Add an early legacy skill API recipe for saving a task document,
checking the saved revision receipt and linking the document. Improve
stock task/heartbeat skill-selection metadata and show a clickable
Markdown UI-link example. Keep native tool completion separate.
- Advertise bounded routing descriptions and exact successfully staged
SKILL.md paths in legacy ACP Claude; keep full bodies on demand and
preserve remote path rebasing.
- Remove only the provider environment from copied persisted ACP session
records, while loading current run credentials and preserving all other
options/conversation state.
- Regenerate both capability metadata inventories and reject stale
manifests/inventories before provider admission.
- Publish the original reduction and focused skill-repair comparisons,
preserving all failures, automatic recovery, cost coverage and
limitations.
## Verification
**Behavioral qualification remains pending.** Original legacy ACP Claude
loses the issue document only in the reduced cohort beneath an unchanged
credential failure. A source-backed diagnosis finds that neither
ordinary assignment reads the staged operational skill, while the
runtime persists provider environment in session state. The new common
repairs expose skill metadata/path and omit persisted env; strict
document and credential guards stay intact. [Inspectable diagnosis and
retained
hashes](https://github.com/paperclipai/paperclip/blob/9f654db4541d3d002769c988f6e51fc0b08dadbd/doc/plans/2026-10-03-legacy-acp-claude-readiness.md).
Current repair head `de0965984ff3edf611ae6d0e7ca5c7d5ae3947bb`
incorporates master `569c7203aa24b95440682983ce7940ba1d4247bd` (merged
#14961/#15007). All 222 affected adapter tests, adapter-utils/E2E
typechecks, and final 96 variant/grader/retry calibrations pass. The
frozen historical comparator is
`c25697f4260b6f3adfea143c3ae9932e2f42986d`: 8,280 of 8,291 paths
identical, exactly two production instruction paths plus nine declared
unit expectations differ. The operational skill/discovery/environment
repairs, selected model/profile/task/core grader/auth/permissions/retry
policy are identical. Both actual launcher prepare→verify admissions
pass with zero providers. [Immutable manifest and exact
receipts](https://github.com/paperclipai/paperclip/blob/9f654db4541d3d002769c988f6e51fc0b08dadbd/doc/plans/2026-10-03-legacy-acp-claude-evidence/manifest.json).
One original legacy ACP Claude cell per variant is authorized, with
enforced single campaign attempts, 12-minute deadlines and company/agent
1,000-cent hard stops; every product recovery run/cost is counted.
Actual live outcomes are pending. Current normal CI has one failed
server shard and failed aggregate verify under diagnosis; other normal
gates including typecheck/build/Rust/all eight browser shards pass.
Fresh review completed successfully; the valid historical startup/resume
masking finding was fixed with per-invocation task/chat checks and
strict complete-snapshot capture, calibrated and resolved. Prior heads,
failures and campaigns below remain historical evidence, not checks on
this repair head.
- Prior head `36aa4d81c49a1a8f6f04b1a068fae19aa901955f` is replayed on
merged hiring master `862a5758ba0e88a33232c1f1fa645e85c38a3113`. All 52
current-head checks pass with two intentional Storybook skips, including
repository typecheck/test/build and the browser shard. Fresh Greptile is
5/5 with zero unresolved review threads. Exact-head stock prerequisites
pass 599 assertions (598 TypeScript + 1 Rust), all six gates and
retained receipt verification, zero providers/source errors. Fingerprint
`a7f5a22d860a88fe20cce213c6d5e0004788f32c8363930729aea4fd740ad16d`.
Combined catalog/hiring calibrations pass 67 assertions, E2E typecheck
and 26-cell stock discovery pass. Canonical contract/inventory checks
and the later issue-derived reference calibration are retained; that
reference-only follow-up is not live-qualified by earlier frozen runs.
- Prior full repository typecheck/build passed. The complete local
Vitest run executed 14,956 tests: 14,870 passed, 83 skipped, three
timing failures. All three affected files passed unchanged narrow
reruns; original failures remain retained. Current-head CI now passes
the full general checks; the original local failures remain retained.
- The original 24-pair default-manual/shared-prompt comparison has two
new overall classic Claude/OpenCode document-delivery failures plus an
additional legacy ACP Claude document loss beneath an unchanged
credential-guard failure (not closed by later runs), two newly passing
OpenCode ordered cases, seven unchanged failures and 13 unchanged
passes. Equal 15/24 totals do not establish behavioral equivalence.
[Complete original
report](https://github.com/paperclipai/paperclip/blob/875f4c397d9e8c3f12f39dedd59abaf1eaf5236e/doc/plans/2026-10-02-stock-harness-live-comparison.md).
- The skill-only repair holds the eight-word manual/shared prompts and
merged #14920 fixed. All four matched profile configurations and 203
fixture/behavior files match. Candidate
`abd0b628ca642c09a54a4edc56a5227402f6686e` varies only the two skill
sources against baseline `bc83fe030234439ac51279502a28803958963e2e`.
[Candidate
workflow](https://github.com/paperclipai/paperclip/actions/runs/37060885547)
and [baseline
workflow](https://github.com/paperclipai/paperclip/actions/runs/37060888047)
each pass 571 exact-source prerequisites before providers; all eight
cells clean up successfully. Failed campaigns publish successfully and
remain failed.
- Repair pairs: Claude original Fail → Pass; Claude explicit Pass →
Pass; both OpenCode cases Fail → Fail. Explicit OpenCode's handoff
worsens beneath the unchanged failing UI-link grade: baseline gives a
clickable API URL, candidate gives a code-formatted path without an
anchor. The request's usable-link wording is narrower in the UI-only
oracle. [Complete repair report and safe
projection](https://github.com/paperclipai/paperclip/blob/875f4c397d9e8c3f12f39dedd59abaf1eaf5236e/doc/plans/2026-10-02-legacy-document-skill-repair.md).
- The subsequent narrow stock metadata/link correction has two matched
Pass → Pass cases, zero new machine failures/passes and no pending
pairs. Both original-case handoff links remain deficient: candidate uses
a wrong PAP prefix, baseline supplies a bare prefix-less slug path; the
preserved original oracle only requires a durable document. Both
explicit clickable UI-link cases pass revision/content/link grading. All
four exact-source 587-check gates, single assignment runs and cleanup
pass. This does not establish fix causality because baseline also
succeeds. [Candidate
workflow](https://github.com/paperclipai/paperclip/actions/runs/37069547401)
freezes `fe9dc1e3c518825242ed889ab9c8352986f8c2ed`; [matched
baseline](https://github.com/paperclipai/paperclip/actions/runs/37069552374)
freezes `0d7ecfa96d72fba79b7f0a25052b42c0686c0488`. This is a skill-only
comparison with reduced manuals/shared prompts held constant, not a
repeat of the historical-manual comparison. Only original and clarified
explicit classic OpenCode cases are selected, two per variant/four
expected turns. 8,242 other tracked files and both profile hashes match;
protected workflows admit each exact source before credentials.
[Complete qualification
report](https://github.com/paperclipai/paperclip/blob/74d0d3d945f4c52d0814b5a845ab5bd09f33cd6b/doc/plans/2026-10-02-opencode-skill-routing-link-qualification.md).
Candidate original loads Paperclip/reference before saving publicly;
baseline original loads it after writing locally, then saves publicly
within the same assignment. Reported cost totals are $0.0107824490
candidate / $0.0107909015 baseline, with unmetered runtime. The later
reference-only issue-derived link correction is provider-free calibrated
and **not live-qualified** by these frozen runs; no further paid runs.
- Retained tool calls show the repaired original OpenCode assignment
loads only its assigned output skill before writing locally. Operational
Paperclip is first loaded during automatic disposition recovery; its
early recipe is visible then, but it never saves the missing document.
Explicit candidate loads Paperclip and reads the new reference before
saving successfully. All nine actual runs are counted. Reported LLM
totals are $0.3802537209 baseline and $0.4918990161 candidate; local
runtime is unmetered.
- Initial setup, packaging, cancelled/missing-cell recovery, callback
test and relative-output attempts remain retained. No completed provider
failure was rerun. Frozen measurement branches are unchanged by later
canonical metadata maintenance.
- Run `pnpm test:e2e:runner:stock-harness`, `pnpm test:e2e:runner:unit`,
and `pnpm test:e2e:runner:typecheck`. Select `stock-harness` explicitly
for paid execution; it is excluded from `--all`.
Prior-head integration: `36aa4d81c49a1a8f6f04b1a068fae19aa901955f`
replays this PR on merged hiring #14985
(`862a5758ba0e88a33232c1f1fa645e85c38a3113`), preserving the four
explicit custom-CEO-bundle checks, minimal generic manual boundary, and
both suites. The combined fixture catalog and hiring calibrations pass
67 assertions; exact-head stock prerequisites pass 599 assertions (598
TypeScript + 1 Rust), all six gates and retained-receipt verification,
zero providers/source errors, fingerprint
`a7f5a22d860a88fe20cce213c6d5e0004788f32c8363930729aea4fd740ad16d`. E2E
typecheck and 26-cell stock discovery pass. Fresh current-head CI passes
all 52 checks with two intentional skips, and fresh Greptile is 5/5 with
zero unresolved review threads.
The prior source-plan browser failure is retained: a deterministic
process fixture replayed its last `fixture:plan` command on
`chat_task_completed`, writing revision 2 with identical body after the
approval handoff. This was not paid provider execution. Rebased
current-head CI passes the same assertion without an old-head retry or a
change to that browser fixture.
The merged hiring change was measured separately on immutable matched
unions, with this reduced/shared/operational context and native
completion guidance held constant. [Complete original two-profile
report](https://github.com/paperclipai/paperclip/blob/f0512647656be78e48abd8c22a3078db8bf6bcd2/doc/plans/2026-10-02-hiring-template-live-comparison.md):
[candidate](https://github.com/paperclipai/paperclip/actions/runs/37075466208)
/ [historical
baseline](https://github.com/paperclipai/paperclip/actions/runs/37075469463),
705 provider-free prerequisites each. Both pairs are unchanged Fail →
Fail on the exact-five count, with six core delivery checks passing all
four cells; 28 actual successful runs include eight automatic completion
wakes, zero retries, four successful cleanups. Source-read coverage is
uncomparable, actual model charges unknown. Separately versioned
provider-free accounting remains analytical work; original verdicts are
preserved. This does not rerun or qualify the completed default-manual
or native campaigns.
## Risks
- Legacy ACP Claude's additional delivery loss is not closed by any
later matched run and blocks the no-extra-failing-behavior merge
criterion. Legacy document delivery may have relied on the prior
manual/shared prompts. The early skill repair improves Claude in one
trial; the later OpenCode pairs pass in both variants and cannot
establish causality or robust recovery. Both original-case links remain
deficient beneath the storage-only grade. The later issue-derived
reference correction has only provider-free validation. Native
finish/block descriptions must not be supplied to legacy agents.
- The comparison holds merged native Codex fix#14920 constant; it
cannot measure that fix's before/after task performance.
- These bounded skill/context/chat workflows do not measure general
coding quality. Unrepresented providers remain unqualified.
- Saved manuals and old Codex sessions are not automatically migrated.
Codex through ACP still has a separate base-instruction follow-up.
## Model Used
OpenAI Codex, GPT-6 family as identified by this session. The exact
deployment ID and context-window size are not exposed. The assistant
used reasoning, repository tools, code execution, and delegated PR/eval
work.
## 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 (relevant suites and all
three unchanged narrow reruns pass; complete-run timing failures
retained in Verification)
- [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 on the new repair head
(prior-head checks retained above)
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
on the new repair head
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Product E2E evals check real hiring and delegated task completion.
> - The hiring fixture requires three requested CEO turns and two coder
executions.
> - The server can also wake the CEO when each delegated task completes.
> - Two exact-five-run guards rejected these valid completion turns in
all four retained cells.
> - This pull request validates bounded completion turns in both guards.
> - The benefit is accurate workflow grading while all actual runs and
coverage failures remain visible.
## Linked Issues or Issue Description
Refs: #14985, #14948, #14961.
**What happened?**
The original hiring comparison reports Codex Fail → Fail and Claude Fail
→ Fail. Each cell has seven successful runs. The five requested work
turns are accompanied by two server task-completion notifications. All
six other delivery checks pass.
**Expected behavior**
Require exactly three distinct user-requested CEO turns and one coder
execution for each of two known tasks. Admit at most two strictly
attributed server completion turns, including one turn that batches both
tasks. Reject unknown, duplicate, failed, retried or extra-work runs.
**Steps to reproduce**
Inspect the retained four-cell report linked below. Each original result
fails `five-successful-turns`. The same exact count was also enforced by
the final chat-flow guard.
## What Changed
- Add one typed lifecycle helper shared by the hiring scorer and the
hiring-only final chat guard.
- Validate public run ledgers, company/user/account identity, request
attribution, task origins, completion deliveries, timing and replies.
- Keep exactly five required work turns; declare seven maximum total
turns for cost and timeout planning.
- Count all actual runs, including notification runs and unexpected
resets. Keep other chat count guards unchanged.
- Version the hiring grader as v3 (turn accounting v2) and include the
helper and chat guard in its definition digest.
- Keep source-read, exact coder-body and all six other delivery checks
unchanged.
- Add 144 focused helper/scorer/settlement calibrations and separately
versioned exact retained-input replay reports.
- Retry complete bracketed observations, await both owed callbacks and
attributed replies, and refresh the final guard consistently.
- Reject unrelated completion writes and failed mutation attempts using
exact canonical/native action IDs. Missing identity mapping is
uncomparable action coverage.
## Verification
- All 977 credential-free E2E support tests pass across 64 files,
including 144 focused lifecycle/action/scorer/settlement calibrations.
- E2E typecheck, ordinary plugin SDK and Runner TypeScript dependency
builds, capability contract/inventory checks and the existing two-cell
hiring discovery pass.
- [Executable replay
report](https://github.com/paperclipai/paperclip/blob/fed1729018cc100f5f4bbfb692777e49009c423b/doc/plans/2026-10-02-hiring-executable-accounting-replay.md)
pins current code revision `e4077ade1818d98b9862ae79ee1d49a007dcf9c1`,
v3 definition digest, exact source/input hashes and each original/new
check.
- The stricter replay verifies both Codex variants through both
executable guards. ACPX Claude action attribution remains
unresolved/uncomparable because provider execution IDs cannot be exactly
joined to native request IDs; guards fail closed. No notification writes
are observed. All six other outcomes and every original source/template
coverage check stay unchanged. Original files and Fail → Fail machine
verdicts remain preserved; zero providers are called.
- Full attempts remain uncomparable in both profiles. Historical Claude
also keeps its six-backtick exact-template mismatch. This grading repair
does not prove model-performance equivalence.
- The limited sidecar-v1 and initial executable-v2 passes checked
notification-created tasks but could miss unrelated document writes.
Those assessments remain preserved and do not prove harmless
notifications. The stricter v3 replay is separate.
- [Original measurement and separate
sidecar](https://github.com/paperclipai/paperclip/blob/8eb517ca1497687237163bdef4dfc4d3332ea916/doc/plans/2026-10-02-hiring-template-live-comparison.md)
retain 28 actual runs, eight automatic notifications, four successful
cleanups and unknown actual model charges. No models are rerun.
- The branch is replayed on master `59c07ede7`. Intervening master
changes are UI-only; eval source bytes and replay verdicts match. The
four-cell provider-free replay was repeated against the reachable code
revision.
- Initial-head normal CI retained browser failures in agent-run denial
feedback and touch-picker scroll position. Those browser paths and
imports were unchanged, but their cause was not established. The
necessary review-fix head passes both browser checks; no blind rerun was
requested.
- Local full repository typecheck/test/build were not repeated.
Exact-head normal CI passes the required repository gates, including
typecheck, tests, build and browser shards. Fresh Greptile review
completed on `fed1729018cc100f5f4bbfb692777e49009c423b` with 5/5 and
zero unresolved threads. An independent rerun of the 144 focused
helper/scorer/settlement tests passes on the unchanged head.
**Merge readiness:** This PR repairs the evaluator. Its positive and
negative calibrations pass, both guards reject missing action
attribution, current-head CI and review pass, and there are no merge
conflicts. The retained ACPX cells remain uncomparable because their
action IDs cannot be joined. That coverage limit remains a separate
follow-up; it does not require relaxing this grader or changing the old
results. No model calls, production instructions, carrier changes, or
historical regrades are part of this readiness update.
## Risks
- Missing or inconsistent public lifecycle evidence fails the bounded
helper. The focused calibrations reject plausible false positives and
malformed observations. Unmatched action IDs fail closed and are
reported as uncomparable rather than a model task regression.
- Source-read evidence remains incomplete. This PR does not change
provider event carriers or relax the coverage oracle.
- The versioned count check differs from original v1 results. Reports
retain both versions and exact input hashes.
## Model Used
OpenAI Codex, GPT-6 family as identified by this session. The exact
deployment ID and context-window size are not exposed. The assistant
used reasoning, repository tools, code execution and delegated
calibration work.
## 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 normal CI gates are green (exact head
`fed1729018cc100f5f4bbfb692777e49009c423b`; fresh review tracked
separately below)
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
(completed exact-head review; zero unresolved threads)
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip lets people steer and recover AI-agent conversations.
> - Recovery eligibility depends on retained cancellation receipts.
> - Run presentation intentionally omits result JSON on SQL_ASCII
databases and reduces oversized output.
> - Retry and the saved-input sweep mistakenly used that presentation
read for admission.
> - The banner could offer Retry while the endpoint rejected the same
stopped run.
> - Read the narrow execution-evidence fields for internal admission and
keep normal presentation unchanged.
## Linked Issues or Issue Description
Refs #15024 and #15015. Searched existing recovery and redaction PRs; no
duplicate fix found.
**What happened?**
On a SQL_ASCII instance, a verified pre-dispatch review-wait
cancellation offers Retry in the recovery notice. Clicking it returns an
eligibility conflict, and a saved user message remains deferred. The
notice reads the retained database receipt, but the endpoint and sweep
read a presentation projection where `resultJson` is null.
**Expected behavior**
Retry and saved user input use the recorded execution evidence and
ordinary admission gates, independent of presentation redaction. Public
run reads retain their existing encoding and output-size protections.
**Steps to reproduce**
1. Record a cancelled, unclaimed review-wait continuation and its
recovery hold.
2. Use the SQL_ASCII presentation projection, where run result JSON is
omitted.
3. Click Retry or save a new user message and let the recovery sweep
inspect it.
4. Verify a fresh turn starts once, with no replay of consumed input.
**Paperclip version or commit**
Reproduced on `9ae3d8db3`.
**Deployment mode**
Authenticated private self-hosted server with a SQL_ASCII database.
## What Changed
- Add an explicit internal read of cancellation, startup, review-wait,
tool-inventory, and Stop evidence; omit provider diagnostics.
- Use that read in the Retry route, wakeup validation, and saved-input
continuation checks.
- Preserve the distinction between absent result JSON and an
unrecognized stored result.
- Cover the reproduced SQL_ASCII Retry and saved-input failures,
retained public redaction, native Stop behavior, and excluded provider
output.
- Document the presentation and admission distinction.
## Verification
- Red: four selected assertions fail before the fix, including the
SQL_ASCII eligibility conflict and saved input remaining deferred.
- Targeted green regressions and existing native Stop cases pass.
- Workspace `pnpm -r typecheck` and `pnpm build` pass.
- All 626 affected recovery, continuation, and route tests pass,
including 22 focused admission and native Stop cases. Current-head CI
has 54 passing gates and 2 skipped optional Storybook checks. Greptile
reviewed `9b94af91e295a4e8007dfc6bff6a8d532d945e36` at 5/5 with no
findings or open review threads. No complete local monolithic pass is
claimed; the complete suite runs in sharded CI.
## Risks
Admission still checks recorded process and controller ownership,
provider events, cleanup, company scope, user authority, pending
decisions, and task holds. The evidence projection must retain every
field used by these eligibility predicates; existing native Stop cases
guard against dropping its acknowledgement receipt. No schema,
dependency, UI, or public response change.
## Model Used
OpenAI Codex, an agent based on GPT-6. The exact runtime model ID and
context window are not exposed in this session. Used reasoning,
repository tools, code execution, and browser inspection.
## 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>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The queued-run gate can cancel a continuation that must wait for
review.
> - This cancellation happens before execution authority or a provider
starts.
> - Recovery currently treats the gate receipt as unknown provider
execution.
> - That mistake blocks a conversation after a successful reply and
hides Retry.
> - This pull request recognizes only the recorded, unclaimed
review-wait state.
> - Review waits keep their normal disposition path, and new user input
can recover older false holds.
## Linked Issues or Issue Description
Refs #15015, #15020, and #15022. Related #11614 narrows the review
posture that causes cancellation; this change corrects recovery after a
valid cancellation.
**What happened?**
After a successful agent reply, the queued-run gate cancelled an
automatic continuation with `issue_continuation_waiting_on_review`. The
gate retained `timeoutSource: stale_queued_run_gate` and a matching stop
reason. No execution authority or provider started. Recovery still
created an unknown-action hold, moved the task to Blocked, and hid
Retry.
**Expected behavior**
Use normal review-wait disposition repair for this recorded state. Allow
Retry, a new user message, or saved undelivered input to recover an
older false hold after ordinary admission checks pass. Preserve the
cancelled run and do not replay its input.
**Steps to reproduce**
1. Finish an agent turn on an open task that has a real review target.
2. Let the automatic continuation reach the queued-run review gate.
3. Refresh after the cancelled run is checked by recovery.
4. Confirm a review wait is handled as a wait rather than unknown
provider work.
5. Reproduce an older false hold for the same receipt, then request
Retry or send a new message.
6. Confirm only one fresh turn starts, and contradictory execution or
cleanup evidence retains the hold.
**Paperclip version or commit**
Reproduced on `215586d127`.
**Deployment mode**
Authenticated private self-hosted server, built from source.
## What Changed
- Recognize the exact review-wait dispatch receipt only while all
execution claims remain unset.
- Exempt recovery only after checking retained launch and provider
events, coordinators, and environment cleanup. Keep the synchronous
classifier conservative without that database proof.
- Apply the verified classification to automatic recovery, heartbeat
retries, and stranded-queue release, so saved user input starts once.
- Reuse guarded startup admission for Retry, new input, and saved input
on older false holds.
- Show a precise review-wait notice and keep continuation guidance
consistent with Retry availability.
- Verify provider events, launch events, coordinators, and cleanup
before admission.
- Add five initial red regressions, three additional red recovery
evidence regressions, concurrent saved-input coverage, and negative
evidence checks.
- Document the review-wait contract.
## Verification
- Red: five regressions fail on unchanged master. Existing review-wait
and contradictory-evidence cases still pass.
- Workspace `pnpm -r typecheck` passes.
- All 752 affected recovery, continuation, queue, classification, and
retry-scheduling tests pass.
- Three additional review regressions failed before the database proof
was added; all 12 focused review-wait cases then pass.
- Workspace `pnpm build` passes.
- Saved-input promotion and recovery notice regressions fail before
their fixes and pass afterward.
- Current-head CI has 54 passing checks and 2 skipped optional Storybook
checks. Greptile reviewed `0bf1437110e1617ae4544afa41f4319eac763dba` at
5/5 with zero open findings. The complete suite runs in sharded CI. No
complete local monolithic pass is claimed; an earlier long run was
stopped, and its unrelated failing case passed in isolation.
## Risks
The error code alone cannot establish that no provider started. This
exception also requires the server gate receipt, matching stop reason,
and null execution authority fields. User admission separately checks
coordinator, launch and provider events, environment cleanup, pending
decisions, ownership, task holds, budget, and active execution. No
migration or dependency change.
## Model Used
OpenAI Codex, an agent based on GPT-6. The exact runtime model ID and
context window are not exposed in this session. Used reasoning,
repository tools, code execution, and browser inspection.
## 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>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - A cancelled preparation must preserve history while allowing a new
user turn.
> - Older preparation can retain its cancellation fence but omit the
unwind marker.
> - The controller from that older boot is gone, its lease expired, and
no provider started.
> - Use the same narrow preparation proof for this retained-fence state.
> - The benefit is working Retry and saved-message recovery after
interrupted startup.
## Linked Issues or Issue Description
Refs #15020 and #15015. Related #13293 addresses post-launch recovery.
**What happened?**
A preparation interrupted before native selection retained
`startupCancellation.beforeNativeSelection: true` but no
preparation-settled marker. Its owner expired across restart and it had
no environment leases. The missing-receipt compatibility rule did not
recognize the retained fence, leaving Retry absent and saved messages
deferred.
**Expected behavior**
Admit one new user turn when the preparation evidence agrees, the old
controller expired, and cleanup is complete. Preserve previous results
and do not replay the cancelled input.
**Steps to reproduce**
1. Cancel Paperclip Runner preparation before runtime selection.
2. Retain the cancellation fence without an unwind marker or environment
leases.
3. Restart after its old controller lease expires.
4. Send a new message, select Retry, or allow the saved-message worker
to reconsider new input.
5. Confirm one successor receives only undelivered input. Repeat with
live ownership, invocation evidence, or pending cleanup and confirm
execution stays held.
**Paperclip version or commit**
Reproduced on `94f6f3eb4`.
**Deployment mode**
Authenticated private self-hosted server, built from source.
## What Changed
- Accept a retained before-selection cancellation fence in the expired
historical preparation proof.
- Retain runtime, stage, adapter, ownership expiry, process, event, and
cleanup requirements.
- Extend Retry, fresh-message, partial-queue, concurrent-worker, and
contradictory-evidence tests to both receipt states.
- Document recovery when the preparation-settled marker was not
retained.
## Verification
- Red: five exact-state regressions fail on the parent commit.
- Green: all 203 continuation tests pass, including the five new
regressions and 13 additional negative evidence cases. Process recovery
and queued-comment routes add 413 passing tests.
- A read-only candidate service check against the retained live run
returns Retry eligibility without changing any task state.
- An unrelated containment assertion failed once in CI. All 85 tests in
that route suite pass locally and the CI shard passes on rerun.
- Workspace `pnpm -r typecheck` and `pnpm build` pass.
- Final head `48240de3d`: all 54 CI checks pass, two optional Storybook
checks skip, and Greptile is 5/5 with zero unresolved threads. The
complete local monolithic suite is covered by sharded CI; the earlier
local run was stopped after a workspace case failed, and that case
passed in isolation.
- After merge, deploy the exact merged commit and verify an actual agent
reply through the task composer.
## Risks
A cancellation receipt alone must not certify that provider execution
stopped. This path still requires unresolved preparation, no native
identity or coordinator, an expired controller from another boot, no
launch or provider evidence, and completed environment cleanup.
Current-boot preparation remains held until it settles. No schema or
dependency change.
## Model Used
OpenAI Codex, an agent based on GPT-6. The exact runtime model ID and
context window are not exposed in this session. Used reasoning,
repository tools, code execution, and browser inspection.
## 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>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - A task conversation must accept new user input after an interrupted
startup.
> - Native startup begins with a legacy preparation row before runtime
selection.
> - Older builds did not retain the startup cancellation receipt on that
row.
> - The immutable adapter claim and expired controller can still prove
that no provider started.
> - This pull request uses that narrow proof for explicit Retry and
saved user input.
> - The benefit is a conversation that recovers after an upgrade without
repeating old work.
## Linked Issues or Issue Description
Refs #15015. Related #13293 covers retained process evidence after
provider startup. This change covers interrupted preparation before
native runtime selection.
**What happened?**
After an upgrade, a task stopped during native preparation can still
show automatic recovery stopped. A new user message saves but does not
start. Retry is absent because the historical run has no cancellation
receipt.
**Expected behavior**
Offer Retry and admit new user input when immutable run evidence proves
that no provider started and cleanup is complete. Preserve incomplete or
contradictory evidence as a recovery hold.
**Steps to reproduce**
1. Retain a cancelled run with the Paperclip Runner adapter claim, an
unresolved runtime, and the preparing stage.
2. Keep its old controller boot ID and expired lease. Retain no native
identity, coordinator, result, process identity, or provider events.
3. Upgrade from a build that did not save the startup cancellation
receipt.
4. Send a new user message or select Retry. Confirm that one fresh turn
starts.
5. Repeat with an active controller, a provider launch, or unfinished
cleanup. Confirm that execution stays held.
**Paperclip version or commit**
Reproduced on `cc67d4e1d` with a historical interrupted preparation row.
**Deployment mode**
Authenticated private self-hosted server, built from source.
## What Changed
- Recognize historical interrupted native preparation from immutable run
evidence and an expired controller from another server boot.
- Reject adapter invocation evidence in the startup proof. Keep process
and environment cleanup checks.
- Apply the same proof to saved user messages in the bounded recovery
worker.
- Recheck saved-message eligibility under the existing task and run
locks. Keep normal ownership, decision, pause, and budget gates.
- Add regression tests for Retry, a new message, concurrent
saved-message recovery, and contradictory evidence. Document the
compatibility rule.
## Verification
- Red: Retry, new-message recovery, and saved-message recovery fail on
the parent commit.
- Green: 185 continuation tests, 335 process-recovery tests, and 78
queued-comment route tests pass. Two additional red regressions cover
partially delivered saved queues and pass after the admission fix.
- Workspace `pnpm -r typecheck` and `pnpm build` pass.
- Final head `48db53f4f`: all 54 CI checks pass; two optional Storybook
checks skip. Greptile is 5/5 with zero unresolved threads.
- The local monolithic `pnpm test:run` was stopped after CI passed. One
unrelated workspace case failed in that long run; all three workspace
reconciliation cases pass in isolation. No complete local monolithic
pass is claimed.
- After merge, deploy the exact merged commit and verify recovery
through the normal task composer.
## Risks
Historical compatibility could grant a new turn without enough startup
evidence. The proof requires an immutable native adapter claim, an
unresolved preparing stage, no result or native identity, an expired
controller from another server boot, and no invocation or provider
evidence. Environment cleanup remains mandatory. The fix does not replay
old input or change historical run results. No schema or dependency
change.
## Model Used
OpenAI Codex, an agent based on GPT-6. The exact runtime model ID and
context window are not exposed in this session. Used reasoning,
repository tools, code execution, and browser inspection.
## 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>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - A task conversation must let a user guide a running agent and resume
stopped work.
> - The active run owns its input protocol, even when the user changes
the next model or effort.
> - Queue delivery waits for a provider receipt, which must be able to
persist during the request.
> - A stopped startup also needs a clear user action that passes normal
task admission.
> - This pull request fixes steering delivery, makes queue actions
immediate, and restores explicit continuation.
> - The benefit is a responsive conversation that can recover without
losing saved input.
## Linked Issues or Issue Description
**What happened?**
A queued message could change from Steer to Interrupt while a native run
prepared. A steer request could wait on its own database lock and fail
to deliver. A stopped startup could then leave the conversation without
a working Retry or message continuation. Interrupt also waited for the
server and showed a toast.
**Expected behavior**
The active run keeps its input protocol. Steer delivers input to that
run. Steer and Interrupt clear the submitted queue rows and show the
input in the conversation immediately. Failed delivery restores the
latest queue with an inline error. An eligible stopped run offers Retry,
and authenticated user input can start a fresh turn through normal task
admission.
**Steps to reproduce**
1. Start a task with a native Paperclip Runner.
2. Change the selected model or effort while that run prepares.
3. Queue a message and press Steer.
4. Observe the provider receipt and queue state during the request.
5. Stop a startup before its provider process begins, then try Retry or
send a new message.
6. Repeat queued delivery with a legacy runner and press Interrupt.
**Paperclip version or commit**
Reproduced on the parent of this branch, `59c07ede7`.
**Deployment mode**
Authenticated private deployment. The fixes also cover local task
conversations.
Related work: Refs #12834, Refs #13354, Refs #13275. The open refactor
in #13160 moves the same queue route; it does not fix the receipt lock
or stopped-run continuation addressed here.
## What Changed
- Select queue behavior from the active run's immutable dispatch and
runtime resolution.
- Leave the run row unlocked during provider acknowledgement, then lock
and read it before merging the receipt.
- Retain queued input if the target run stops during that wait. Keep
inline delivery errors visible after empty queue updates.
- Permit exact Retry and authenticated continuation after verified
native startup cancellation. Preserve pause, approval, budget,
ownership, and process-stop gates.
- Carry undelivered native queue input into a fresh turn once the old
execution is confirmed stopped.
- Show Steer and Interrupt input in the conversation and clear submitted
composer rows immediately. Restore the latest queue inline on failure.
Remove delivery toasts.
- Keep optimistic delivery stable across stale polls, empty queues, and
paginated history. Preserve classic Interrupt error handling.
- Document recovery and optimistic delivery behavior. Add regression
tests across server, shared queue projection, and UI boundaries.
## Verification
- Red-green regression tests reproduced the queue protocol, receipt
lock, stopped-startup continuation, and optimistic delivery failures.
- The focused server route, continuation, queue, and runner boundary
suites passed during implementation.
- The queue-route suite passes with 78 tests. The three complete
conversation UI suites pass with 347 tests.
- UI typecheck, production build, and `pnpm check:token-gates` pass.
- Workspace `pnpm -r typecheck` and `pnpm build` pass. The local
monolithic `pnpm test:run` is still running; remote CI verifies the
complete suite on the latest commit.
- All CI gates pass on `bd9031ad56abfcde13d13a13488c1b9217c2fd3a`,
including the full test shards, runner verification, browser E2E,
typecheck, release registry, and canary dry run.
- Greptile reports 5/5 for that commit. Both review threads are
resolved.
## Risks
This changes queue display and explicit continuation admission. The UI
must restore rejected delivery without losing other-session edits. The
server must preserve concurrent provider result updates and must not
resume a process whose stop is uncertain. Focused tests cover these
boundaries. This change has no database migration.
## Model Used
OpenAI Codex, an agent based on GPT-6. The exact runtime model ID and
context window are not exposed in this session. Used reasoning,
repository tools, code execution, and browser inspection.
## 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>
