Real settle teardown, and peer settle-tuple reconciliation (settle teardown, step 3) (#1076)

* feat: attach real settle teardown, and reconcile peer settle-tuple writes

Step 3 of the settle-teardown design.

The seam is async now. Step 2 shipped a branded synchronous return type that
made an awaited teardown a compile error; real stops are async, so that guard
had to go. It was a tripwire, not an obstacle: it existed because bolting a
deferred teardown onto a synchronous write is what produced a P1 in each of
#1059's six rounds, and what changed is the machinery under it. The settling
window is exclusive, abortable and in-memory, which is exactly what makes it
safe to HOLD across an await — the revision re-check and abort check after the
await are the suspension-point guards, and the race matrix covers both.

Teardown (sessionSettleTeardown.ts) reuses stopLaneRuntimeWork's SHAPE, not its
body: that function disposes chat sessions because it serves lane deletion, and
a settle must leave the session usable. Terminals are never touched. Abort is
checked before each step, so a turn that wins the race keeps its work.

R5 lands as 3d option 3: an unconfirmed stop still settles, with residue
recorded — coarse reason, reapable flag, local-only table, cleared implicitly
when the session is reactivated — plus one bucketed analytics event per settle.
Never silent.

Peer tuple writes (R7 + the unsettle mirror) are fixed by finishing host
authority, not by adding consensus. db.sync.applyChanges is the one place both
the host and peer paths funnel through, so settle-tuple changes are held out of
the raw apply and replayed through the chokepoint, gaining the revision and
window semantics. Held rather than dropped: a paired desktop's decision is
legitimate, it just has to come through the front door. No peer-visible token
was built; onRemoteSettleWrite is the telemetry that decides whether one is
ever justified.

R7/R7b keep their raw db.run bypass and are annotated as to why: they pin the
property that motivates the interception.

* test: cover the residue table in the CRR-exclusion invariant

Step 3 adds a second host-local settle table, so the exclusion test that
guards the revision table now guards both. The positive control on
terminal_sessions is what keeps the assertion falsifiable.

* fix: quality dual-review findings, including two blockers

Track A found two blockers, both real.

1. The brain never wired any of this. apps/ade-cli/src/bootstrap.ts built its
   sessionService with no teardown seam and never registered the apply-layer
   handler — and in a normal install the brain, not the desktop, is what
   applies changesets and serves phone sync, remote commands and the PR-merge
   poller. Teardown was a no-op for almost every settle a user can actually
   trigger. Both processes now build their hooks from one
   createSettleTeardownWiring factory so they cannot drift.

2. Holding settle-tuple rows out of crsql_changes breaks LWW convergence. The
   reviewer proved it against the vendored cr-sqlite build: a column that never
   enters crsql_changes never raises the local col_version, so this host stays
   behind the peer permanently and its NEXT genuine decision loses every merge.
   Two hosts then disagree forever — strictly worse than the bypass being
   fixed. Reversed: CRR now owns the values and the chokepoint owns the
   revision, via an observeRemote intent that self-assigns (matches the row, so
   the revision bumps; changes nothing, so no new column version and no echo).
   This also dissolves the composed-intent and lost-batch findings, since no
   intent is reconstructed and nothing is held.

Also fixed: stop_and_clear was destroying the user's queued turns on every
settle (now stop_only — 3c says losing a settle costs a click, losing the
user's work does not); both new analytics properties were silently dropped by
the sanitizer, so the telemetry the design leans on did not work, now pinned by
a test; unbounded provider awaits could hold the settling window open forever
and leave a row permanently unsettleable; count_bucket measured a value that
was always 1; session_settle_residue leaked past deleteSession; residue
analytics fired for settles that never landed; the settling window could be
closed by an owner that no longer held it.

Track B: settleSession now delegates to the typed form instead of duplicating
it, the provider stop-control fact moved to subagentCapabilities, dead fields
(stopped, scheduled_work, reapable) removed, two orphaned JSDoc blocks
reattached, stale test title and a dangling comment asserting the opposite of
the design deleted, and residue got a read path via the action registry —
'discoverable' was a condition of 3d option 3, not a nice-to-have.

* fix: second-round review findings across teardown, reconcile and latency

Track A verified two load-bearing claims empirically against the vendored
cr-sqlite: the observeRemote self-assignment bumps sqlite3_changes without
touching the clock (no echo), and stop_only really does stop background work.
The design holds. What it found on top:

- session.getSettleResidue was added to CTO_ONLY but not the allowlist, so
  every call was refused. The read path 3d option 3 was signed off on did not
  actually exist.
- Stale residue survived a clean re-settle: nothing cleared the row when a
  later teardown confirmed everything, so it kept reporting an old failure
  with an old timestamp.
- A peer write bumped the revision but never tripped the abort. The revision is
  only re-read AFTER teardown, so teardown ran to completion and interrupted a
  turn the user had just started on the other device — losing the work AND the
  settle, which is exactly the R2 shape 3c exists to prevent.
- The reconcile handler fired on changes  had discarded, so a
  re-delivered batch abandoned an in-flight settle over a duplicate packet.
- A timed-out liveness read was indistinguishable from 'not a chat session', so
  a slow host settled while claiming a clean teardown — the one outcome residue
  exists to prevent.
- settle_remote_write_reconciled fired on the NORMAL desktop-peer path, one
  event per session. 'Expected zero' was wrong: a paired desktop replicating its
  own settles belongs here. Now one batched event per changeset, framed as a
  rate signal.
- Bulk settle was serial, and per session now costs up to 15s. iOS allows 30s
  for the whole command, so three busy sessions was a guaranteed timeout. Now
  bounded-concurrent, results reassembled in the caller's order.
- Leaked ~50 unref'd timers per settling session; 10Hz polling of an expensive
  read; lmstudio missing from the provider dimension.

Track B: restored the settle methods' locality after my own earlier repair
scattered them, put back two invariant comments that repair dropped, moved the
duplicated analytics envelope into the shared factory, made residue report a
surviving turn separately from surviving jobs, and covered the hand-rolled
cr-sqlite pk decoder — the riskiest code in the diff — with a test that drives
the real applyChanges path.

* fix: third-round review — the dedup guard was inert, and residue could be erased

Track A proved my `result.changes > 0` guard does nothing. `crsql_changes` is
a VIRTUAL table, so SQLite counts the xUpdate call whether or not cr-sqlite
discarded the row as a losing merge — `insert or ignore` never engages, and a
re-applied identical changeset still reports one change. Worse, round 2 had
just made reconciliation trip the abort, so a duplicate packet (the peer's
outbound cursor only advances on an ok ack, so a dropped ack re-sends the same
range) would have killed a user's in-flight settle while carrying no new
information. Replaced with a real value comparison: capture the column before
the apply, report only if it actually moved. The kvDb test now applies the same
changeset twice and asserts nothing is reported the second time — it fails
against the old guard, which is how the inertness reproduces.

Track A also found clearSettleResidue treating 'could not check' as 'confirmed
clean'. An empty residue array is also what you get before the chat service
exists and when the confirmation read times out, so a settle that verified
nothing was deleting an accurate report of work still running. Teardown now
returns an explicit `confirmed` flag and only a confirmed-clean settle may
erase. The no-op fallbacks in both processes return confirmed: false.

Same class, second site: the read-timeout rule was enforced after the first
read but not on the confirmation read, so a hung confirm still returned clean.
readWork is now a discriminated result, which makes the compiler force both
call sites to decide.

Track B: replaced the worker pool with chunking — order is preserved for free,
and perSession, the queue and the reassembly loop all disappear; hoisted the
concurrency constant to module scope; fixed three docblocks my own insertions
had detached from their functions; typed ACTIVITY_ABORTS so a future abort
reason cannot be silently mis-bucketed; restored the items[0] guard; renamed
sessionCount to changesetSessionCount since it counts the changeset, not the
reconciliation; made the concurrency test fail by assertion instead of by
vitest timeout; and pinned action reachability, which is what H1 slipped
through.

Not changed: Track B read the settle methods as still scattered. Verified
against main — the method order is byte-identical to base, so the interleaving
is the pre-existing layout, not damage. Left alone rather than risk a third
structural move in this file.

* docs: correct settle claims that step 3 made false

The terminals README still said settle 'deliberately does NOT stop the
session's background work' and that a peer's CRR write is outside the
revision's scope. Both were true when written and are not now. Replaced with
what actually happens, including why the ordering of steps 0-3 was the thing
that made it work.

The sync docs were accurate about the phone-only column filter but silent on
the desktop-peer path, which is the one a reader would now come looking for.

* docs: record the sync bulk-settle shape as an open wire decision

3c's table says the sync entry point should carry the typed outcome
additively; it still answers with a bare changed-id array, so an aborted id is
indistinguishable from an ineligible one. Not a regression and not silently
wrong — iOS's local overlay expires on its own rather than showing a settled
row — but step 3 makes aborts likelier, and the fix is a wire-compatibility
call that needs the mobile side, so it is written down rather than guessed at.

* fix: fourth-round findings — restore the worker pool, and stop over-claiming confirmation

Track A verified the value-based dedup guard against the real cr-sqlite across
nine scenarios, including the one that actually matters: an exact duplicate
arriving in a LATER applyChanges call is not reported, while a genuinely new
change still is. It also confirmed the snapshot placement, the absence of SQL
injection (the column is narrowed by the type guard before interpolation), and
that a numeric val is safe under TEXT affinity.

Four fixes from that pass:

- Reverted chunking back to the worker pool. I took that simplification last
  round and it cost real throughput: a chunk barrier idles the other workers
  until its slowest member finishes, and 'every teardown is bounded' is not
  'every teardown takes the same time'. Measured at roughly 65s versus 20s for
  a 50-session sweep with a quarter of the rows unstoppable — aimed straight at
  the 30s iOS budget the concurrency exists to protect. The perSession map
  already gave request order, so the simplification bought nothing.
- An abort during the confirmation loop returned confirmed: true. Nothing was
  confirmed and the work was still running, which is precisely the shape the
  flag was added to make impossible — one refactor away from erasing an
  accurate residue record.
- A confirmation-read timeout discarded a provider it had already read, losing
  the analytics dimension for the residue most worth attributing.
- The value guard read blobs as null, so a blob that changed looked unchanged.
  Out-of-contract for any real writer, but the guard it replaced did report it.

Both new tests were probed and both initially failed to be meaningful: the
provider test was hitting a microtask race where the immediate expire won the
FIRST read, and the confirmation test tripped the abort before the loop it was
meant to exercise, so it passed against the bug. Fixed both, then re-probed —
they now fail against the pre-fix code.

* fix: stop the settle pool when a persistence failure propagates

CodeRabbit, and it is a failure mode this branch introduced: before step 3,
settleMany was one statement for the whole batch, so there was no partial state
to lose. Now each session settles individually, and a SQLite lock thrown from
one of them rejected Promise.all while the other workers kept shifting the
queue — settling sessions the caller had already given up on.

The queue is drained on the first failure so no NEW work starts, the sessions
already in flight finish rather than being abandoned half-written, and the
error is rethrown only once every worker has stopped. Persistence failures
still propagate rather than being dressed up as a settle outcome — that
distinction was an earlier review finding and it stands. What did settle is
durable, and settle is idempotent, so the caller's retry re-reports it instead
of double-filing.

* fix: honor stop_only everywhere, and see background jobs that outlived a restart

Two from Codex, both real, both undermining the point of the feature.

stop_only was only honored on the Claude path. The OpenCode, Cursor, Pi and
Droid branches of interrupt call cancelQueuedSteers unconditionally and return
before the mode is ever consulted — so a settle on those providers silently
deleted the user's queued prompts, which is exactly the unrecoverable loss the
mode was added to prevent. Gated every one of them. The default is
stop_and_clear, so the Stop button is untouched; only teardown asks for
stop_only.

activeBackgroundTaskCount is derived from the LIVE managed runtime, so a Claude
--bg job that survives a brain or app restart reads as zero. Teardown saw a
quiet session, skipped interrupt entirely, and filed the row as settled while
the daemon job kept running — the precise bug this whole feature exists to fix,
reintroduced through a liveness read. The summary already resolved the
persisted job for other consumers; it is now on the type and counted as work.

Both pinned by tests probed against the pre-fix code. Not fixed: CodeRabbit
re-posted the queue-drain comment against the previous head; the drain landed
in d499220. Its second half — surfacing the partial outcome instead of
throwing — is deliberate: a SQLite lock is not a settle outcome, and settle is
idempotent, so the caller's retry re-reports what landed.

* fix: gate the persisted background job on daemon liveness

Codex, and it is a defect my own previous fix created. claudeBackgroundJobShort
is a RECORD, not a liveness signal — it survives the job finishing and survives
teardown stopping it. Counting it unconditionally meant every later settle on
that session would spend the full confirmation budget and then report residue
for a job that no longer exists, while trying to stop it again each time.

Now the daemon is asked, through a narrow hasLiveClaudeBackgroundJob exported
from agentChatService, and only when the live count already says quiet AND a
job is on record — the restart case. That keeps the round-trip off the hot read
while still closing the hole where a job outlives its runtime.

Also documented, not fixed: a provider stop that overruns its 10s ceiling keeps
running, because interrupt takes no abort signal, so a late session-scoped
abort could stop a turn the user started after the settle was abandoned.
Removing the ceiling is a certain wedge; keeping it is a narrow race needing a
10s+ hang, a new turn inside that window, and the abort still applying. Written
up in the design doc (6c-ii) rather than silently traded.

Two other comments on this head are stale re-posts: the stop_only gating landed
in 86c4c5c (verified present in all seven provider branches), and the
queue-drain in d499220.

* fix: make background-job liveness required and tri-state

Both from this round's review, and both are defects my own liveness fix
introduced one commit earlier.

hasLiveClaudeBackgroundJob was optional, so a wiring that omitted it read a
recorded job as absent and confirmed a clean teardown over work still running —
reopening the exact hole the callback was added to close. Now required.

And it returned a boolean, which collapsed "the daemon says the job is gone"
into the same answer as "the daemon could not be reached"
(getLiveClaudeBackgroundSocket catches socket and request failures and returns
null). Guessing "finished" is the guess that settles over a running job — the
same shape as treating a timed-out liveness read as an idle session, which this
branch has now had to fix three times in three places. It returns
alive / gone / unknown, and only a definite "gone" counts as no work.

Also pinned: interrupt's daemon stop branch is gated on there being no resident
Claude runtime, so a resumed session with a live --bg job takes the SDK branch
and the job survives. Teardown does not claim that as clean — the confirmation
loop still sees the job and reports residue — and there is now a test saying so.
Changing that gate would change what the Stop button does, which is not this
branch's call.

Restored the activeBackgroundTaskCount JSDoc my insertion had detached.

* fix: scope the abort check to the window the teardown actually owns

Codex, and it is the mirror of a fix already made for closing the window.
`end(id, token)` refuses to close a window it does not own, but the abort check
still read `abortedBy(id)` — whatever entry currently occupies the id. When
`deleteSession` runs mid-teardown, `forget` force-closes the entry; if the id is
then recreated and a new settle opens a fresh window, the stale teardown reads
the REPLACEMENT, sees "not aborted", and keeps issuing provider stops against
the new session's work.

`abandoned(id, token)` treats a missing or mismatched entry as abandoned, and
both the in-flight check and the post-await check use it. A settle that no
longer owns its window must stop as surely as one that was aborted.

The other seven comments on this head are threads GitHub re-anchored: stop_only
gating (86c4c5c, verified in all seven provider branches), the queue drain
(d499220), persisted-job liveness and unknown-as-residue (df2aa0a), the
JSDoc association (df2aa0a), the resident-runtime daemon job (pinned as
residue rather than silently clean, with a test), and the un-cancellable
timed-out interrupt, which is documented as a known limitation in 6c-ii because
removing the ceiling trades a narrow race for a certain wedge.

* fix: a hung provider stop is a timeout, not a rejection

Codex. The 10s ceiling set `stopRejected`, so a provider that never answered
was filed identically to one that explicitly refused — in the residue the user
reads AND in the settle_teardown_residue analytics dimension. That conflation
is precisely what the reason field exists to prevent, and it would have made
"how often do stops actually fail in the field" unanswerable, which is the
question 3d option 3 added the event to answer.

Two existing assertions had encoded the bug rather than catching it: both said
a never-resolving interrupt should read "rejected". Corrected, and the fix was
probed against them.

Author: arul28

apps/ade-cli/src/bootstrap.ts

@@ -26,6 +26,12 @@ import {
   createSessionService,
   STALE_RUNNING_SESSION_FRESH_ACTIVITY_GRACE_MS,
 } from "../../desktop/src/main/services/sessions/sessionService";
+import { createSettleTeardownWiring } from "../../desktop/src/main/services/sessions/settleTeardownWiring";
+import type {
+  SettleResidueItem,
+  SettleTeardownContext,
+  SettleTeardownOutcome,
+} from "../../desktop/src/main/services/sessions/sessionSettleTeardown";
 import { createProjectConfigService } from "../../desktop/src/main/services/config/projectConfigService";
 import { createConflictService } from "../../desktop/src/main/services/conflicts/conflictService";
 import { createGitOperationsService } from "../../desktop/src/main/services/git/gitOperationsService";
@@ -755,7 +761,30 @@ export async function createAdeRuntime(args: {
   // services. Session changes still use it once publishing is attached.
   let pushPublisherForPtySignals: PushPublisherService | null = null;
   let ptyServiceForSessionChanges: ReturnType<typeof createPtyService> | null = null;
-  const sessionService = createSessionService({ db });
+  // Late-bound: the chat service that owns the work is constructed further
+  // down. Without this the brain — which owns phone sync, remote commands and
+  // the PR-merge poller in a normal install — would settle sessions while
+  // stopping nothing.
+  const settleTeardownRef: {
+    run: ((sessionId: string, ctx: SettleTeardownContext) => Promise<SettleTeardownOutcome>) | null;
+    report: ((args: { columns: string[]; changesetSessionCount: number }) => void) | null;
+    residue: ((args: { provider: string | null; items: SettleResidueItem[] }) => void) | null;
+  } = { run: null, report: null, residue: null };
+  const sessionService = createSessionService({
+    db,
+    runSettleTeardown: async (sessionId, ctx) =>
+      settleTeardownRef.run ? await settleTeardownRef.run(sessionId, ctx) : { residue: [], confirmed: false },
+    onRemoteSettleWrite: (args) => settleTeardownRef.report?.(args),
+    onSettleResidue: (args) => settleTeardownRef.residue?.(args),
+  });
+  // Inbound settle-tuple writes get this host's lifecycle revision, so an
+  // in-flight settle can see a peer's decision and abandon rather than
+  // overwrite it. Registered here because the DB layer must not know what a
+  // settle means — and because the brain, not the desktop, is where changesets
+  // are actually applied in a normal install.
+  db.sync.setRemoteSettleTupleHandler((changes) => {
+    sessionService.reconcileRemoteSettleTuple(changes);
+  });
   sessionService.onChanged((event) => {
     pushEvent("runtime", { type: "terminal_session_changed", event });
     const session = sessionService.get(event.sessionId);
@@ -1249,6 +1278,16 @@ export async function createAdeRuntime(args: {
       countActiveForLane: (laneId) => agentChatService.countActiveForLane(laneId),
       disposeForLane: (laneId) => agentChatService.disposeForLane(laneId),
     };
+    const settleWiring = createSettleTeardownWiring({
+      agentChatService,
+      logger,
+      analytics: productAnalyticsService ?? null,
+      // The brain is the non-GUI runtime surface, matching its other analytics.
+      surface: "api",
+    });
+    settleTeardownRef.run = settleWiring.runSettleTeardown;
+    settleTeardownRef.report = settleWiring.onRemoteSettleWrite;
+    settleTeardownRef.residue = settleWiring.onSettleResidue;
   }
   autoRebaseActivityReady = true;
   void autoRebaseService

apps/desktop/src/main/main.ts

@@ -85,6 +85,8 @@ import { releaseLaneRuntimeResources } from "./services/lanes/laneRuntimeLifecyc
 import { createOAuthRedirectService } from "./services/lanes/oauthRedirectService";
 import { createRuntimeDiagnosticsService } from "./services/lanes/runtimeDiagnosticsService";
 import { createSessionService } from "./services/sessions/sessionService";
+import type { SettleResidueItem, SettleTeardownContext, SettleTeardownOutcome } from "./services/sessions/sessionSettleTeardown";
+import { createSettleTeardownWiring } from "./services/sessions/settleTeardownWiring";
 import { createSessionDeltaService } from "./services/sessions/sessionDeltaService";
 import { createPtyService } from "./services/pty/ptyService";
 import { createSupervisedPtyLoader } from "./services/pty/supervisedPtyHost";
@@ -2870,10 +2872,34 @@ app.whenReady().then(async () => {
         emitProjectEvent(projectRoot, IPC.lanesEnvEvent, ev),
     });
 
-    const sessionService = createSessionService({ db });
+    // Late-bound: the chat service that owns the work does not exist yet at
+    // this point, and the settle path must not depend on construction order.
+    const settleTeardownRef: {
+      run: ((sessionId: string, ctx: SettleTeardownContext) => Promise<SettleTeardownOutcome>) | null;
+      report: ((args: { columns: string[]; changesetSessionCount: number }) => void) | null;
+      residue: ((args: { provider: string | null; items: SettleResidueItem[] }) => void) | null;
+    } = { run: null, report: null, residue: null };
+    const sessionService = createSessionService({
+      db,
+      onRemoteSettleWrite: (args) => settleTeardownRef.report?.(args),
+      onSettleResidue: (args) => settleTeardownRef.residue?.(args),
+      runSettleTeardown: async (sessionId, ctx) =>
+        settleTeardownRef.run
+          ? await settleTeardownRef.run(sessionId, ctx)
+          // Before the chat service is up there is no background work to stop,
+          // so an empty teardown is the honest answer, not a skipped one.
+          : { residue: [], confirmed: false },
+    });
     sessionService.onChanged((event) => {
       emitProjectEvent(projectRoot, IPC.sessionsChanged, event);
     });
+    // Inbound settle-tuple writes go through the chokepoint instead of landing
+    // raw, so a peer's decision gains this host's revision, settling window and
+    // abort semantics (R7). Registered here because the DB layer must not know
+    // what a settle means.
+    db.sync.setRemoteSettleTupleHandler((changes) => {
+      sessionService.reconcileRemoteSettleTuple(changes);
+    });
     const processRegistry = createProcessRegistryService({
       db,
       logger,
@@ -3600,6 +3626,17 @@ app.whenReady().then(async () => {
       countActiveForLane: (laneId) => agentChatService.countActiveForLane(laneId),
       disposeForLane: (laneId) => agentChatService.disposeForLane(laneId),
     };
+    {
+      const wiring = createSettleTeardownWiring({
+        agentChatService,
+        logger,
+        analytics: productAnalyticsService ?? null,
+        surface: "desktop",
+      });
+      settleTeardownRef.run = wiring.runSettleTeardown;
+      settleTeardownRef.report = wiring.onRemoteSettleWrite;
+      settleTeardownRef.residue = wiring.onSettleResidue;
+    }
     autoRebaseActivityReady = true;
     void autoRebaseService
       .refreshActiveRebaseNeeds("activity_services_ready")

apps/desktop/src/main/services/adeActions/registry.test.ts

@@ -75,6 +75,11 @@ describe("isAllowedAdeAction", () => {
     expect(isAllowedAdeAction("session", "requestSessionAttention")).toBe(true);
     expect(isAllowedAdeAction("session", "setSessionStatusNote")).toBe(true);
     expect(isAllowedAdeAction("session", "settleSession")).toBe(true);
+    // The residue read path. It was added to the CTO-only list but NOT to the
+    // allowlist, which silently refused every call — and left the settle design
+    // claiming a user-visible guarantee ("settled never quietly means something
+    // is still running") that nothing could actually reach.
+    expect(isAllowedAdeAction("session", "getSettleResidue")).toBe(true);
     expect(isAllowedAdeAction("session", "unsettleSession")).toBe(true);
     expect(isCtoOnlyAdeAction("session", "settleSession")).toBe(true);
     expect(isCtoOnlyAdeAction("session", "unsettleSession")).toBe(true);

apps/desktop/src/main/services/adeActions/registry.ts

@@ -734,6 +734,7 @@ export const ADE_ACTION_ALLOWLIST: Partial<Record<AdeActionDomain, readonly stri
     "get",
     "getDelta",
     "getLifecycleSettings",
+    "getSettleResidue",
     "list",
     "readTranscriptTail",
     "requestSessionAttention",
@@ -2193,6 +2194,20 @@ function buildSessionDomainService(runtime: AdeRuntime): OpaqueService | null {
       sessionService.unsettleSessions(sessionIds);
       return { ok: true };
     },
+    /**
+     * Work a settle could not confirm it stopped (design 3d option 3).
+     *
+     * Read-only, and the reason it exists: option 3 was signed off on the
+     * condition that the residue stay DISCOVERABLE rather than merely recorded.
+     * Without a read path, "settled" would quietly mean "and something may still
+     * be running" — the exact outcome the option was chosen to avoid.
+     */
+    getSettleResidue: (args?: unknown) => {
+      const record = readObjectActionArg(args, "session.getSettleResidue");
+      const sessionId = typeof record.sessionId === "string" ? record.sessionId : "";
+      if (!sessionId) throw new Error("session.getSettleResidue requires sessionId.");
+      return sessionService.getSettleResidue(sessionId) ?? { recordedAt: null, items: [] };
+    },
     // -----------------------------------------------------------------------
     // Snooze / wake / settle-override. Snooze is a synced VISIBILITY overlay:
     // it hides a row until its deadline without touching lifecycle columns, so

apps/desktop/src/main/services/ai/tools/ctoOperatorTools.ts

@@ -554,7 +554,7 @@ export function createCtoOperatorTools(deps: CtoOperatorToolDeps): Record<string
     }),
     execute: async ({ sessionId, outcome }) => {
       try {
-        const result = deps.sessionService.settleSessionReportingAbort(sessionId, {
+        const result = await deps.sessionService.settleSessionReportingAbort(sessionId, {
           ...(outcome ? { outcome } : {}),
           source: "operator",
         });

apps/desktop/src/main/services/analytics/productAnalyticsPolicy.ts

@@ -93,7 +93,7 @@ const STRING_PROPERTIES = new Set([
   "duration_bucket", "error_kind", "route_kind", "connection_state", "drop_reason", "source", "mode",
   "entry_point", "release_channel", "summary_kind", "reason", "last_command", "leg", "code",
   "escalation_reason", "install_source", "trigger", "from_version", "to_version", "user_action",
-  "tool_error_kind", "crash_reason",
+  "tool_error_kind", "crash_reason", "count_bucket",
 ]);
 const NUMBER_PROPERTIES = new Set([
   "sent_count", "dropped_count", "interaction_count", "session_count", "chat_session_count",
@@ -120,6 +120,10 @@ const ANALYTICS_ONLY_ACTIONS = new Set([
   "mention_expanded",
   "transaction_failed",
   "scope_selected",
+  // Settle teardown: work a settle could not confirm it stopped, and a peer
+  // settle-tuple write that had to be reconciled through the chokepoint.
+  "settle_teardown_residue",
+  "settle_remote_write_reconciled",
 ]);
 
 const EVENT_PROPERTY_KEYS: Record<ProductAnalyticsEventName, ReadonlySet<string>> = {
@@ -132,7 +136,7 @@ const EVENT_PROPERTY_KEYS: Record<ProductAnalyticsEventName, ReadonlySet<string>
   ade_project_opened: new Set(["route_kind", "source", "mode", "connection_state"]),
   ade_feature_used: new Set([
     "feature", "action", "outcome", "source", "mode", "provider", "model_family", "duration_bucket", "connection_state",
-    "bytes_freed", "files_compressed",
+    "bytes_freed", "files_compressed", "count_bucket",
   ]),
   ade_work_session_started: new Set(["feature", "action", "outcome", "source", "mode", "provider"]),
   ade_work_session_completed: new Set([
@@ -183,6 +187,9 @@ const SAFE_STRING_VALUES: Partial<Record<string, ReadonlySet<string>>> = {
   outcome: new Set([
     "success", "started", "completed", "failure", "timeout", "opened", "cancelled", "approved", "denied",
     "partial", "failed", "idle_only", "immediate",
+    // Settle teardown could not confirm a stop (design 3d). `timeout` above
+    // covers the third case. Coarse on purpose: never the task or its error.
+    "no_stop_control", "rejected",
     // Which half of a post-update transaction did not land. `swap` is
     // deliberately absent: the app half is already reported by
     // `ade_update_install_did_not_land`, so only the brain half is new signal.
@@ -194,12 +201,15 @@ const SAFE_STRING_VALUES: Partial<Record<string, ReadonlySet<string>>> = {
     // widened, so the scope control can never carry free text.
     "machine", "project", "account",
   ]),
-  provider: new Set(["codex", "openai", "claude", "cursor", "droid", "opencode", "pi", "gemini", "local", "other"]),
+  provider: new Set(["codex", "openai", "claude", "cursor", "droid", "opencode", "pi", "gemini", "lmstudio", "local", "other"]),
   model_family: new Set([
     "gpt_5", "openai_reasoning", "claude_sonnet", "claude_opus", "claude_haiku", "cursor", "gemini",
     "grok", "local", "other",
   ]),
   duration_bucket: new Set(["under_10s", "under_1m", "under_5m", "under_30m", "under_2h", "over_2h"]),
+  // Bucketed, never a raw count: a fleet that fails to stop must not become a
+  // high-cardinality dimension.
+  count_bucket: new Set(["1", "2_5", "6_plus"]),
   route_kind: new Set(["desktop", "web"]),
   connection_state: new Set(["connected", "disconnected", "pairing", "direct", "relay", "error"]),
   drop_reason: new Set([

apps/desktop/src/main/services/analytics/productAnalyticsService.test.ts

@@ -1213,6 +1213,42 @@ describe("product analytics producers", () => {
     })).toMatchObject({ provider: "pi" });
   });
 
+  it("keeps the settle-teardown properties through the sanitizer", () => {
+    // Both of these were silently dropped when first added: `action` is
+    // allowlisted separately from the event's key list, and `count_bucket` was
+    // registered in the key list and the value allowlist but never in the
+    // string-dispatch set, so it never reached either. The event still shipped,
+    // just anonymous — which is worse than not shipping, because the dashboard
+    // looks populated.
+    expect(sanitizeProductAnalyticsProperties("ade_feature_used", {
+      feature: "work",
+      action: "settle_teardown_residue",
+      outcome: "no_stop_control",
+      provider: "codex",
+      count_bucket: "2_5",
+    })).toEqual({
+      feature: "work",
+      action: "settle_teardown_residue",
+      outcome: "no_stop_control",
+      provider: "codex",
+      count_bucket: "2_5",
+    });
+
+    expect(sanitizeProductAnalyticsProperties("ade_feature_used", {
+      feature: "work",
+      action: "settle_remote_write_reconciled",
+      outcome: "partial",
+    })).toMatchObject({ action: "settle_remote_write_reconciled" });
+
+    // The bucket is still a closed set: a raw count must not slip through and
+    // widen the dimension.
+    expect(sanitizeProductAnalyticsProperties("ade_feature_used", {
+      feature: "work",
+      action: "settle_teardown_residue",
+      count_bucket: "37",
+    })).not.toHaveProperty("count_bucket");
+  });
+
   it("maps automation completion and failed chat turns into canonical bounded outcomes", () => {
     const captures: ProductAnalyticsCapture[] = [];
     const analytics = settledAnalytics(captures);

apps/desktop/src/main/services/chat/agentChatService.ts

@@ -37495,7 +37495,13 @@ export function createAgentChatService(args: {
       } catch {
         // Ignore provider abort failures; SSE cancellation still tears the turn down.
       }
-      cancelQueuedSteers(managed, managed.runtime, "interrupted");
+      // `stop_only` exists so settle teardown can stop a turn WITHOUT
+      // discarding the user's queued follow-ups. Only the Claude path honoured
+      // it, so a settle on these providers silently deleted queued prompts —
+      // unrecoverable, and the opposite of the rule that losing a settle costs
+      // one click while losing the user's work does not. Default is
+      // `stop_and_clear`, so the Stop button is unaffected.
+      if (mode === "stop_and_clear") cancelQueuedSteers(managed, managed.runtime, "interrupted");
       persistChatState(managed);
       for (const pending of managed.runtime.pendingApprovals.values()) {
         managed.runtime.handle.client.postSessionIdPermissionsPermissionId({
@@ -37541,7 +37547,7 @@ export function createAgentChatService(args: {
         cancelCursorPermissionWaiter(w, "Cursor tool approval was cancelled because the turn was interrupted.");
       }
       rt.permissionWaiters.clear();
-      cancelQueuedSteers(managed, rt, "interrupted");
+      if (mode === "stop_and_clear") cancelQueuedSteers(managed, rt, "interrupted");
       return result;
     }
 
@@ -37554,15 +37560,17 @@ export function createAgentChatService(args: {
       } catch {
         // ignore
       }
-      cancelQueuedSteers(managed, rt, "interrupted");
+      if (mode === "stop_and_clear") cancelQueuedSteers(managed, rt, "interrupted");
       cancelPendingPiInputs(managed);
       persistChatState(managed);
       return result;
     }
 
     if (managed.session.provider === "pi") {
       piRuntimeSetupInterruptRequested.set(managed, true);
-      cancelQueuedSteers(managed, { pendingSteers: [], activeTurnId: null }, "interrupted");
+      if (mode === "stop_and_clear") {
+        cancelQueuedSteers(managed, { pendingSteers: [], activeTurnId: null }, "interrupted");
+      }
       setSessionIdle(managed);
       persistChatState(managed);
       return result;
@@ -37580,20 +37588,24 @@ export function createAgentChatService(args: {
         cancelDroidPermissionWaiter(w, "Droid tool approval was cancelled because the turn was interrupted.");
       }
       rt.permissionWaiters.clear();
-      cancelQueuedSteers(managed, rt, "interrupted");
+      if (mode === "stop_and_clear") cancelQueuedSteers(managed, rt, "interrupted");
       return result;
     }
 
     if (managed.session.provider === "droid") {
       droidRuntimeSetupInterruptRequested.set(managed, true);
-      cancelQueuedSteers(managed, { pendingSteers: [], activeTurnId: null }, "interrupted");
+      if (mode === "stop_and_clear") {
+        cancelQueuedSteers(managed, { pendingSteers: [], activeTurnId: null }, "interrupted");
+      }
       persistChatState(managed);
       return result;
     }
 
     if (managed.session.provider === "cursor") {
       cursorRuntimeSetupInterruptRequested.set(managed, true);
-      cancelQueuedSteers(managed, { pendingSteers: [], activeTurnId: null }, "interrupted");
+      if (mode === "stop_and_clear") {
+        cancelQueuedSteers(managed, { pendingSteers: [], activeTurnId: null }, "interrupted");
+      }
       persistChatState(managed);
       return result;
     }
@@ -44283,6 +44295,34 @@ export function createAgentChatService(args: {
     dispatchSteer,
     cancelDispatchedSteer,
     interrupt,
+    /**
+     * Is a persisted Claude `--bg` job actually still running?
+     *
+     * `claudeBackgroundJobShort` is a RECORD, not a liveness signal — it stays
+     * on the session after the job finishes or is stopped. Settle teardown has
+     * to distinguish the two: counting a finished job as work makes every later
+     * settle spend the confirmation budget and then report residue that does
+     * not exist.
+     */
+    hasLiveClaudeBackgroundJob: async (
+      short: string | null | undefined,
+    ): Promise<"alive" | "gone" | "unknown"> => {
+      const normalized = normalizeClaudeBackgroundShort(short);
+      if (!normalized) return "gone";
+      const socketPath = await resolveClaudeDaemonControlSocket();
+      // No daemon socket, or a request that failed: we do not KNOW the job is
+      // gone. Collapsing that to "gone" is how a settle confirms a clean
+      // teardown over a job that is still running — the same mistake as
+      // treating a timed-out liveness read as an idle session.
+      if (!socketPath) return "unknown";
+      try {
+        const response = await sendClaudeDaemonRequest(socketPath, { op: "has", short: normalized });
+        if (response.ok !== true) return "unknown";
+        return response.alive === true || response.present === true ? "alive" : "gone";
+      } catch {
+        return "unknown";
+      }
+    },
     restoreCancelledQueue,
     recoverTurn,
     recoverCodexTurn,

apps/desktop/src/main/services/history/operationService.test.ts

@@ -87,6 +87,7 @@ function createInMemoryAdeDb(): { db: AdeDb; raw: Database } {
           rebuiltFts: false,
         }),
         discardUnpublishedChangesForTables: () => {},
+        setRemoteSettleTupleHandler: () => {},
       },
       flushNow: () => undefined,
       close: () => raw.close(),