## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - When an agent run fails and cannot resume exactly, Paperclip continues the task in a fresh run from its last saved work > - If a person sent a message while the task was blocked, the fresh-continuation fallback lets that saved message start the next run (`delivery: saved_input`) and does not queue its own run > - The release step that promotes the saved message skips the "needs reconciliation" hold for a native run that the fallback superseded, but not for a legacy run > - So for a legacy run the task moves to To do, the person's message stays saved, and no run starts until a watchdog finds the task idle > - This pull request applies the same superseded-run rule to legacy runs in the release step > - The benefit is that a person's message after a failed run starts the next run at once, for legacy runs as for native runs ## Linked Issues or Issue Description **What happened?** A person sent a message on a task whose last legacy run failed. Paperclip continued the task from saved work and moved it to To do. The message stayed saved. No run started until the assigned-work watchdog queued one later. **Steps to reproduce** 1. Let a legacy run fail with an active recovery hold, so the task is Blocked. 2. Post a comment as a person. The wake is saved as `deferred_issue_execution`. 3. Let the fresh-continuation fallback continue the task. It records `delivery: saved_input`. 4. Run the deferred receipt and stranded-queue passes. **Expected behavior** One run starts and carries the person's message. **Actual behavior** No run starts. The release step returns `released` because `legacyExecutionNeedsReconciliation` is true for the superseded legacy run. ## What Changed - `server/src/modules/wake-queue/adapters/postgres.ts`: the release pre-drain check does not ask for legacy reconciliation when the run is superseded by a fresh continuation. This matches the existing native rule in the same function. - `server/src/services/fresh-continuation-fallback.test.ts`: a red/green test for native and legacy runs. A person's comment goes through the real wake path while the task is blocked, the task continues from saved work, and exactly one run must start with the comment. ## Verification - Red: before the fix, the legacy case fails. The saved wake stays `deferred_issue_execution` and no run starts. The native case passes. - Green: after the fix, both cases pass. - `pnpm verify` for the affected selection. ## Risks - Low risk. The change applies only when the fresh-continuation fallback has already marked the run superseded. That decision already records that the old run is not replayed, and the successor runs as a fresh turn. Other callers of `legacyExecutionNeedsReconciliationWithEvidence` (retry scheduling, recovery) are not changed, so a superseded run still cannot be retried automatically. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Claude Code agent with tool use and code execution. ## 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>
Feature modules
A feature module under server/src/modules/<name>/ uses three layers. Each
layer has one rule: which layer below it, it may import from.
adapters → application → domain
domain/holds pure business rules. A domain file takes plain data in and returns plain data out. A domain file must not importdrizzle-orm,@paperclipai/db, a service underserver/src/services/, a route underserver/src/routes/, or a Node.js I/O module (node:child_process,node:fs,node:net). A domain function must not read the system clock; the caller passesnowas an explicitDatevalue.application/holds use cases and the ports they need. A use case takes its ports as constructor arguments and calls domain functions for policy decisions. An application file must not importdrizzle-orm, a SQL client, a concrete adapter, or the server's HTTP error helpers. The outer service or route translates application errors into transport responses.adapters/holds the concrete implementations of the ports: Postgres queries, transactions, and process control. An adapter file may importdrizzle-orm,@paperclipai/db, and Node.js I/O modules.
A module exposes its commands through index.ts, which composes the adapters
and the use cases behind a factory function. Code outside the module imports
that entry point, never a file inside domain/, application/, or
adapters/ directly.
pnpm check:module-boundaries enforces these rules for production source
files. It also checks access to the company deletion entry point below.
Company deletion
The existing company deletion service owns the database transaction and deletion
order. A module can expose a separate company-deletion.ts entry point.
Only services/company-deletion.ts can import this entry point.
The entry point exports an implementation of CompanyDeletionParticipant from
lib/company-deletion.ts. Do not export it through the normal module index.
The service must complete external cleanup before it starts the transaction. It must lock the company before it deletes dependent records or calls a module. Creation commands must use the same company lock. The service removes dependent records before it calls the module. The module checks its deletion conditions and deletes the records it owns. Use the supplied transaction. Do not start another transaction or call external systems. Throw an error if deletion cannot proceed. An error must roll back all database changes in the deletion transaction.
Call each module explicitly in dependency order. No module registry is required.
The agent lifecycle module also has a restricted configuration.ts entry point.
It saves configuration and invalidates verification in the caller's transaction.
The lifecycle guide lists its permitted callers.
Ordinary configuration updates use the root lifecycle command.
The agent lifecycle module owns agent creation, pause, resume, and termination. Use its commands for these changes.
The execution admission module owns project task-execution policy and the
durable admission records that charge project capacity. Today it exposes only
internal policy commands and the deletion guards that project, agent, and
company deletion call. Settlement releases active charges but keeps each
admission's complete project set for later retained-session resolution.
Execution claims still belong to services/heartbeat/queue.ts and native
review dispatch. See execution admission accounting.