[Mjones13]

Problem

queueHeld on a V2 run is a bare boolean with no reason or time. Restart holds never end: a restart continuation that finishes does not release the messages held by the restart. Only Resume, a selected send, or a recovered preparation failure clears a hold. On the owner's environment, 146 held runs piled up for weeks (historical count from 2026-11-10, not re-read). 145 of them were machine-made: monitor, background-task, MCP and peer notifications.

Design

• Hold records in a Jones table. The reason (stop | restart | provider_failure | inherited) and hold time live in jones_queue_holds (Jones migration 147, apps/server/src/jones/persistence/Migrations/147_JonesQueueHolds.ts).
  • The table is keyed by upstream run ID, with a thread index, no foreign keys and no triggers.
  • A row exists only while Jones has recorded a hold. Upstream run payloads, events, columns and contracts keep their upstream shape.
  • A missing table or row reads as a hold recorded before reasons existed.
• Written inside the accepting transaction. EventSink.applyStoredEvents (accepted-shared) calls acceptQueueHoldEvents once per write, after projections, in the same SQLite transaction as the event append and receipt. There is no window between the event and the row, and a duplicate command writes nothing at its receipt.
  • Projection rebuilds do not touch the rows.
  • classifyQueueHoldEvents (apps/server/src/jones/orchestration/QueueHoldStore.ts) is pure and issues no SQL unless an event matches. It records:
    • run.created queued behind held work → inherited;
    • a held queued run.updated under provider-runtime.reconcile → restart, which is startup recovery's one hold site;
    • a held queued run.updated under thread.stop or run.interrupt → stop;
    • a provider failure or missing worktree in startNextQueuedRun passes an explicit queueHold intent on its system write → provider_failure. The intent names only runs not already held, so an earlier hold keeps its reason and time.
  • Releasing a queued run (queueHeld: false), a held run leaving the queue (for example by cancel or expiry), and thread.deleted delete rows by key.
• Stop replaces a restart hold. Stop reads the recorded holds of its thread's held queued runs by primary key. A run held for restart is re-emitted unchanged, and the hook replaces its row with stop. A continuation that completes after the user pressed Stop therefore releases nothing the user stopped.
• Restart release. When the queue reactor sees a completed run whose message ID starts with message:restart-continuation:, startNextQueuedRun first releases that thread's recorded restart holds from no later than the continuation's completion, then drains as usual.
  • Stop, inherited and provider-failure holds stay. Holds with no recorded reason stay.
  • A failed or interrupted continuation releases nothing, and a hold from a later restart waits for its own continuation.
  • A thread whose queue a planned update's continuity owns (PlannedUpdateContinuity) is left to that owner.
• Held queue expiry (apps/server/src/jones/orchestration/HeldQueueExpiry.ts). The sweep is registered with the server Scheduler, so it first runs after startup recovery and then at most hourly.
  • It reads held queued runs through the partial (status, thread_id) recovery index and each message by primary key, then merges recorded holds by run ID.
  • It cancels a held run when both are true:
    • its age is at least T3CODE_HELD_QUEUE_EXPIRY_HOURS (default 24), measured from the recorded hold time or else requestedAt;
    • its message is automatic.
  • The cancel goes through the existing queued-run.cancel path with command ID command:held-queue-expiry:<runId>. The sweep logs jones.held-queue-expiry.cancelled with run IDs, thread IDs, reasons and ages, and no message text.
  • Automatic means a positive machine marker:
    • a notification, delegated completion, sender thread, scheduled task, idle compaction, or a restart-continuation ID;
    • a role other than user, or createdBy other than user;
    • a creation source other than web or mobile.
  • Human-typed messages, and messages that cannot be read, never expire.
• Unchanged. A new message still does not release holds, and fix(queue): let new thread messages pass historical holds #284's QueueHold.test.ts behaviour is kept.

queued-run.cancel (dispatchQueuedRunCancel) writes events only on the cancelled run's own thread. It emits no events or effects on a sender's thread.

Database boundary

An earlier head of this PR added queueHeldAt and queueHeldReason to the upstream OrchestrationV2Run payload, against the Jones database boundary. This head removes them.

• The contract fields, packages/contracts/src/jones/queueHold.ts and its test are gone.
• ProviderRuntimeRecoveryService.ts and runtimeLayer.test.ts are back to their base form.
• The fields were never merged or released.
• A development database that ran the earlier head keeps those extra keys in a few run payloads. Nothing reads them, so struct decoding drops them and those runs behave as legacy holds.

Deployment note

The first sweep after an update cancels stale automatic held runs. Human-typed held messages stay held until resumed or cancelled by hand. Migration 147 only creates the empty table, and existing holds read as legacy.

Tests

• QueueHoldReasons.test.ts covers:
  • each hold site recording its reason in the Jones table, and no queueHeld* key appearing in projected run payloads or orchestration_events;
  • inherited holds, and Resume deleting the rows;
  • provider failure keeping an earlier Stop reason;
  • startup recovery's write classifying as restart with an upstream-shaped payload;
  • a completed continuation releasing restart holds in order while the Stop hold stays, and failed or interrupted continuations releasing nothing;
  • Stop during the continuation turning restart holds into Stop holds;
  • classifier cases: other writers record nothing, and the orphaned-records reconcile is not a restart hold;
  • release, cancel and thread-delete cases;
  • store cases: no table, replace, an unknown reason or garbled time ignored, a failed transaction leaving no row, and stale rows on unheld runs releasing nothing.
• HeldQueueExpiry.test.ts covers:
  • cancelling automatic held runs older than 24h, including a legacy run with no row aged from requestedAt;
  • keeping a run requested long ago but held recently, aged from its recorded hold;
  • keeping a 5h-old automatic run and a human-typed run, and never cancelling the human-typed run even 1000h later;
  • the recorded holds of cancelled runs being deleted;
  • a second sweep doing nothing;
  • an expired delegated-completion delivery disposing its cohort.
• UpstreamIsolation.test.ts and Migrations.test.ts include migration 147, and upstream pruning and deletes are not blocked by a jones_queue_holds row.
• Red/green (on the earlier head, behaviour unchanged since): with only the reactor hook disabled, the completed-continuation test failed with expected 'message:free' to equal 'message:first'. The candidate passes it.

Checks run on aa5cef5c2c (plus the fixture-ledger fix in a1f35a9997)

Requalified on 60e4d1a2ad after merging main: 20 files, 454 tests passed. They cover the jones-held-queue-expiry and jones-queue-hold-isolation groups, currentFixtures.test.ts, the migration-list tests and #928's steer tests. Typecheck, strict boundary, migration order and git diff --check also pass.

Local, Node 26.12.1, serial:

Command	Result
jones-held-queue-expiry group (10 files)	325 tests passed
jones-queue-hold-isolation remainder, jones-orphaned-run-records remainder (#913, stacked top), 115_…test.ts, NativeCreationRepositoryMigration.test.ts (16 files)	137 tests passed
vp lint <changed files>	exit 0 (pre-existing upstream warnings only)
vp run --filter t3 typecheck	exit 0
knip --workspace apps/server --exports	exit 0
node scripts/jones/check-boundary.ts --strict	0 violations
node scripts/jones/ci/jones-migration-order.cjs --baseline 3f3328a54c --candidate aa5cef5c2c	accepted, 1 appended identity
git diff --check	exit 0

Head a1f35a9997 adds one line to apps/server/scripts/jones/currentFixtures.test.ts: its strict jones_sql_migrations expectation now lists { id: 147, name: "QueueHolds" }. On aa5cef5c2c, CI Test Server 8 failed only on that assertion, and the same 2 tests failed locally for the same reason. On the clean a1f35a9997 commit the file passes (8 of 8). The harness requires a clean worktree bound to the commit.

CI history: on 3a1bca5, Check passed. The advisory Server parallel (linux) and (macos) jobs failed during dependency install at "Downloading Electron binary..." before any test ran. CI for aa5cef5c2c is on the checks tab.

Overlap

• fix(server): close records left open under ended runs at startup #913 merged as 763a4f538c4. This PR now targets main and includes main at that commit, including fix: preserve inherited steers after prospective model saves #928 and fix(ci): recover signed Ubuntu dependencies during DNS outages #935, through merge 60e4d1a2ad.
• Migration ID collision with Sync upstream 4c924ff4 with Jones composition and current main #929. The upstream-sync branch allocates its own unreleased migrations 147–151, and this PR allocates 147 QueueHolds. main ends at 146, so none of these is released. Per the allocation rule, whichever lands second moves its unreleased IDs above main's maximum and requalifies. The merge order is being coordinated before this PR merges.
• Re-run node scripts/jones/ci/jones-migration-order.cjs against fresh main immediately before merging. On 60e4d1a2ad against 763a4f538c4 it accepts 1 appended identity.
• No other open Jones-Code PR covers held-queue reasons or expiry.

Generated by Claude Opus 5.5 in Claude Code; Jones database boundary repair by Claude Opus 5.5 (Jace Claude) from a Claude Fable 5.2 design review.

🤖 Generated with Claude Code