Reserve exact computer generations for graceful suspension, keep provider checkpoints on their persistent remote authority, and fence failed prelaunch attempts before retry. Recover previously retired quiescent Codex checkpoints only with exact ownership and unchanged-byte evidence.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Preserve the two existing additive runtime acceptance suites in the stacked feature PR while keeping browser synchronization fixes in the independently checked core branch.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Fence admission and ordinary commands at warm expiry, reserve exact-generation process control for at most thirty seconds of shutdown, and always retire the owned slice after graceful close or timeout.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Persist exact upload ownership before staging, renew a five-minute inactivity lease per chunk, and reclaim verified expired uploads on seed or home admission. Preserve active uploads and unrelated directories, and fence delayed writes and aborts after replacement.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Bound each physical Boat to eight SSH operations with six ordinary slots and four bulk transfers. Preserve command deadlines while queued and always release admission after transport completion or failure.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Preserve historical PRP workspace coordinates and require the recorded lease run plus exact retired owner before rotating authority.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Stream initial personal files through bounded chunks into private staging and atomically publish without replacing an existing home. Keep the home-level runtime directory out of instruction enumeration and seeding while preserving nested user content.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Probe IBus without replacing a healthy daemon. Rebind a failed restored socket to the same user private runtime directory before viewer access or Cua MCP startup; headless execution stays independent.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Preserve Boat workspace and credential policies in prepareHeartbeatWorkspace. Move computer route acceptance coverage to the stacked UI PR without dropping coverage from the full feature tree.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The heartbeat service prepares the workspace and dispatches each
agent run.
> - After the runtime extraction, `heartbeat.ts` still had 6,417 lines.
> - Workspace setup occupied one contiguous 857-line block inside
`executeRun`.
> - This pull request moves that block into one workspace preparation
module.
> - The executor keeps dispatch gates and terminal cleanup. Reviewers
can inspect workspace setup as one phase.
## Linked Issues or Issue Description
Refs #15803 and #15578. This continues the heartbeat refactor series.
The search found no open duplicate workspace preparation extraction.
**What existing behavior does this improve?**
It makes heartbeat workspace preparation easier to maintain. It does not
change the workspace policy or execution behavior.
**Current behavior**
`executeRun` contains workspace resolution, freshness decisions,
provisioning, persistence, issue binding, environment acquisition, and
realization inline.
**Proposed behavior**
`prepareHeartbeatWorkspace` owns that sequence in
`server/src/services/heartbeat/workspace-preparation.ts`. `heartbeat.ts`
calls it at the same point and uses its returned workspace, lease,
target, and metadata.
**Reason and benefit**
The main file falls from 6,417 to 5,597 lines. The workspace phase has a
typed boundary and direct regression tests.
**Breaking changes**
None. There are no schema, API, feature-flag, or execution-policy
changes.
## What Changed
- Extract the 857-line workspace preparation block without changing its
operations or their order.
- Preserve native recovery bindings, workspace persistence failure
cleanup, issue rebinding after realization, and the cloned restore
lease.
- Keep environment selection, dispatch admission, terminalization, and
final lease release in `heartbeat.ts`.
- Add 12 boundary tests with disposable PostgreSQL, real Git
repositories, and real local environment leases.
- Make the existing Stop and plan-only recovery tests await executor
completion instead of short polling deadlines. Assert exactly one
continuation for the specific plan-only source run.
- Keep server-only Node preload hooks out of the deterministic process
adapter used by Stop browser acceptance.
- Refresh workspace recovery browser acceptance for the current task
composer, and give its disposable test-drive an explicit 10-second
snapshot deadline. Production snapshot settings stay unchanged.
- Document the workspace preparation boundary in `doc/DEVELOPING.md`.
## Verification
- AST comparison: all 857 moved lines match the original block. The
remaining module body differs only at the extraction call.
- `pnpm build`: passed.
- `pnpm -r typecheck`: passed.
- Focused regression coverage: 651 distinct cases across eight suites
passed across targeted runs, including all 12 new boundary tests. The
complete 400-test recovery suite passed together on the final commit.
- Workspace bootstrap browser acceptance: both journeys passed (4.2
minutes), including preserved source edits, ignored-file exclusion,
bounded retries, and persistence across reload.
- Stop/queue browser acceptance: both process and native runner journeys
passed (2.2 minutes), covering queueing, Stop, subtree pause/cancel,
resume, and unrelated-task isolation.
- [Full repository
CI](https://github.com/paperclipai/paperclip/actions/runs/38062408589):
all 47 jobs passed, including the general and serialized test suites,
eight browser shards, build, typecheck, native runner checks, and canary
dry run.
- The local `pnpm test:run` was interrupted to prioritize the recovery
regression; the complete repository suite was verified in CI.
- Greptile: 5/5 on `c28e698b885cf5fd12f36f7b4052e7a2e6f879d7`, with no
open review threads.
## Risks
- This code writes durable workspace bindings and acquires environment
leases. A changed operation order could break recovery or cleanup after
partial setup. The extraction preserves the original statements and
exception boundaries.
- The new tests cover creation, reuse, immutable recovery bindings,
persistence failure, acquisition and realization failure, controller
ownership loss, isolation, execution policy, and lease snapshot
independence.
- Browser acceptance uses real application services with deterministic
local workers and a fake Codex protocol provider. It does not qualify
live cloud providers.
## Model Used
OpenAI GPT-6 through Codex, with code editing, shell execution, and test
tools. The exact serving model identifier and context-window size are
not exposed in this session.
## 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>
Boat invalidates descriptors for unlinked backing files, causing Node startup to abort. Retain the0600 stdin spool until normal cleanup, and reap abandoned command spools only after exact-owner retirement stops its cgroup.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Boat invalidates descriptors for unlinked backing files, causing Node startup to abort. Retain the0600 stdin spool until normal cleanup, and reap abandoned command spools only after exact-owner retirement stops its cgroup.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Root runner binaries, harness installs, provider packs, and session state under the trusted persistent agent home and normalized session. Keep the shared project working directory unchanged and preserve existing sandbox paths.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Root runner binaries, harness installs, provider packs, and session state under the trusted persistent agent home and normalized session. Keep the shared project working directory unchanged and preserve existing sandbox paths.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Pass the existing workspace credential provider through computer realization separately from durable metadata, and supply its URL-scoped helper only to the clone subprocess. Verify authenticated clone behavior and credential non-retention.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Hash remote files through confined descriptors in bounded chunks before editor mutations. Preserve the remote compare-and-swap removal check and read-size cap; cover a real 17 MiB file, stale deletion, and path confinement.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Pass the existing workspace credential provider through computer realization separately from durable metadata, and supply its URL-scoped helper only to the clone subprocess. Verify authenticated clone behavior and credential non-retention.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Hash remote files through confined descriptors in bounded chunks before editor mutations. Preserve the remote compare-and-swap removal check and read-size cap; cover a real 17 MiB file, stale deletion, and path confinement.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Disable systemd environment expansion so the shell receives its identity marker variables and positional arguments unchanged.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
