@gotcos/glasses-server 6.53.1 → 6.53.4

package/server/lib/claude-hooks-installer.ts

@@ -284,6 +284,64 @@ export function hookStatus(paths: { settingsPath?: string; scriptPath?: string;
   return { state, installed: state === 'installed', settingsPath, scriptPath, scriptSha, packageScriptSha, ...events, tokenPresent }
 }
 
+/**
+ * 6.53.3: sha256 of every EARLIER script that already carries the halt check. 6.53.3
+ * rewrote the script for speed (review A, option a), so an install that has not run Install
+ * hooks since reads `script_outdated` and Control shows its banner. Those scripts still stop
+ * a desk run exactly as before, though, so a desk cancel is not refused `hooks_outdated` in
+ * the meantime (`hookHaltReady`). A script older than 6.53.0 has no halt check and never
+ * qualifies.
+ *   - 1158bb06...: the one script 6.53.0, 6.53.1 and 6.53.2 all shipped.
+ *   - c0b41bf8...: the 6.53.3 script as first built, before its /qa round made every event
+ *     drain stdin. Never published, but installable from a local build of that commit
+ *     (7433b7f), and it carries the same halt check.
+ * Each is pinned against its bytes in `server/lib/__fixtures__/`.
+ */
+export const HALT_CAPABLE_PRIOR_SCRIPT_SHAS: readonly string[] = [
+  '1158bb06297550128f01fc47caa68806a5287d6da2d05b0d1c812e8ae20764e7',
+  'c0b41bf8581cfea498e1e1ac5220fe4e148bd97448d13b60a88879ee5992cc51',
+]
+
+/**
+ * 6.53.3: can the hooks on this Mac stop a desk Claude run now? `installed`, or the only
+ * difference is a halt-capable earlier script (above). What the cancel route's
+ * `hooksReady` and `/api/health` `features.sessionCancel.deskClaude` read.
+ */
+export function hookHaltReady(status: Pick<HookStatus, 'installed' | 'state' | 'scriptSha'>): boolean {
+  if (status.installed === true) return true
+  return status.state === 'script_outdated' && typeof status.scriptSha === 'string'
+    && HALT_CAPABLE_PRIOR_SCRIPT_SHAS.includes(status.scriptSha)
+}
+
+const INSTALL_COMMAND = 'npx --yes @gotcos/glasses-server@latest --hooks install'
+
+/**
+ * 6.53.3: one plain sentence for `--hooks status` saying what the state means and what fixes
+ * it. Null when installed. Carries no path: the status JSON beside it already names them.
+ */
+export function hookStatusAdvice(status: Pick<HookStatus, 'installed' | 'state' | 'scriptSha' | 'packageScriptSha'>): string | null {
+  const short = (sha: string | null): string => (sha ? sha.slice(0, 12) : 'none')
+  switch (status.state) {
+    case 'installed':
+      return null
+    case 'script_outdated':
+      return `The installed hook script is older than this package's (installed ${short(status.scriptSha)}, package ${short(status.packageScriptSha)}). `
+        + 'Every Claude session keeps running the old script until the hooks are reinstalled: '
+        + `run \`${INSTALL_COMMAND}\`, or press Install hooks in COS Control. `
+        + (hookHaltReady(status)
+          ? 'Cancel from the lens still stops desk runs with the installed script meanwhile.'
+          : 'Until then a desk run cannot be cancelled from the lens.')
+    case 'drift':
+    case 'missing':
+      return `The hook subscriptions in the Claude settings file are ${status.state === 'missing' ? 'not installed' : 'not the ones this package installs'}. `
+        + `Run \`${INSTALL_COMMAND}\`, or press Install hooks in COS Control.`
+    case 'disabled_by_settings':
+      return 'The Claude settings file sets disableAllHooks: no hook runs, installed or not.'
+    default:
+      return 'The Claude settings file could not be read as it is; nothing was changed. Fix or restore the file, then install again.'
+  }
+}
+
 export interface InstallOptions {
   settingsPath?: string
   scriptPath?: string

package/server/lib/fence-liveness.ts

@@ -27,6 +27,9 @@
 // human deciding whether to release; an over-confident `none_running` is worse than
 // admitting the probe could not see.
 
+import { execFileSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+
 /** Recorded spawn: a pid and the start COS measured when it created the child. */
 export interface RecordedSpawn {
   pid: number
@@ -55,7 +58,7 @@ export interface FenceLiveness {
 }
 
 export interface FenceLivenessDeps {
-  /** Epoch ms at which `pid` started, or null when it is not running.
+  /** Epoch ms at which `pid` started, or null ONLY when it is provably not running.
    *  MAY THROW; a throwing probe is not an answer and resolves to `unknown`. */
   pidStartMs: (pid: number) => number | null
 }
@@ -116,7 +119,9 @@ export function makePidStartProbe(
     const raw = run(pid)
     if (raw === null) return null
     const text = raw.trim()
-    if (!text) return null
+    // A clean exit that printed nothing is not "not running" (only the runner's null is):
+    // throw, so it is counted unverifiable.
+    if (!text) throw new Error('empty process start from ps')
     const parsed = Date.parse(text)
     // Unparseable is NOT "not running" -- throw so the caller counts it
     // unverifiable rather than silently reading a live child as gone.
@@ -124,3 +129,72 @@ export function makePidStartProbe(
     return parsed
   }
 }
+
+/** What this module reads off the error `execFileSync` throws. */
+export interface ExecFailureLike {
+  status?: unknown
+  signal?: unknown
+  killed?: unknown
+  code?: unknown
+  error?: unknown
+  stdout?: unknown
+  stderr?: unknown
+}
+
+/** The slice of `execFileSync` the probe calls. Injectable so a test can throw every error
+ *  shape Node produces without spawning anything. */
+export type PsExec = (file: string, args: readonly string[], options: { encoding: 'utf8'; timeout: number }) => string
+
+/** How long one `ps` may take before Node kills it (the kill is NOT an answer). */
+export const PS_PROBE_TIMEOUT_MS = 2_000
+
+const PS_BIN = existsSync('/bin/ps') ? '/bin/ps' : 'ps'
+
+const emptyOutput = (value: unknown): boolean =>
+  (typeof value === 'string' && value.trim() === '') || (Buffer.isBuffer(value) && value.length === 0)
+
+/**
+ * 6.53.3 /qa BLOCKER: is this `execFileSync` failure `ps -p` saying "no such process"?
+ *
+ * THE ONE ANSWER THAT MEANS GONE. `ps -p <pid>` for a pid that is not running exits 1 on its
+ * own and prints nothing on either stream (measured, macOS 26 and node 24: `{status: 1,
+ * signal: null, stdout: '', stderr: ''}` with no `code` and no `error`). Everything else is
+ * ps failing to answer, and says nothing about the child: a kill at the timeout (`ETIMEDOUT`,
+ * SIGTERM), a fork that failed (`EAGAIN`), no binary (`ENOENT`), a signal, output on stdout or
+ * a complaint on stderr, any other status. Until 6.53.3's QA every one of those read as gone,
+ * and gone is `none_running`, which releases a cancel fence (`releaseSettledCancelFences`) on a
+ * child that may still be writing.
+ */
+export function psSaysNoSuchProcess(error: unknown): boolean {
+  if (error === null || typeof error !== 'object') return false
+  const e = error as ExecFailureLike
+  return e.status === 1
+    && (e.signal === null || e.signal === undefined)
+    && e.killed !== true
+    && (e.code === null || e.code === undefined)
+    && (e.error === null || e.error === undefined)
+    && emptyOutput(e.stdout)
+    && emptyOutput(e.stderr)
+}
+
+/**
+ * The production runner: `ps -p <pid> -o lstart=`'s stdout, or null ONLY when ps said the
+ * process does not exist (`psSaysNoSuchProcess`). Any other failure THROWS, which
+ * `fenceLiveness` counts unverifiable, so the fence stays.
+ */
+export function psLstartRunner(exec: PsExec = execFileSync as unknown as PsExec): (pid: number) => string | null {
+  return (pid: number) => {
+    try {
+      return exec(PS_BIN, ['-p', String(pid), '-o', 'lstart='], { encoding: 'utf8', timeout: PS_PROBE_TIMEOUT_MS })
+    } catch (error) {
+      if (psSaysNoSuchProcess(error)) return null
+      const e = (error ?? {}) as ExecFailureLike
+      throw new Error(`ps could not answer for pid ${pid} (status=${String(e.status ?? null)} signal=${String(e.signal ?? null)} code=${String(e.code ?? 'none')})`)
+    }
+  }
+}
+
+/** The probe the fence routes use in production. */
+export function defaultPidStartProbe(exec?: PsExec): (pid: number) => number | null {
+  return makePidStartProbe(psLstartRunner(exec))
+}

package/server/lib/queue-turn-evidence.ts

@@ -0,0 +1,137 @@
+// The thread-turn queue's two turn questions, `turnEnded` and `turnOpen` (6.53.3).
+//
+// Moved out of the composition root (index.ts) unchanged in shape, so the one rule that
+// changed in 6.53.3 can be driven by a test against the real `drainDecision`: WHAT a
+// cancel on the thread may conclude about a turn that still reads open depends on what the
+// cancel was aimed at (review A1, `cancelVoidsOpenTurn` in session-cancel.ts).
+//
+//   cos_turn   COS killed its own child: nothing written since the cancel ends the turn.
+//   desk_run   the run stops at its NEXT tool call, so the hooks' and the transcript's
+//              open-turn evidence stands until the desk's own engine says the run is over
+//              at or after the cancel (a Stop, StopFailure or SessionEnd, or the registry's
+//              idle flip). Until 6.53.2 a desk run inside a long tool read "over" 30 s after
+//              the cancel, and a parked follow-up was delivered live into it.
+//
+// Every read is injected; index.ts wires the real ones. Both answers refuse on doubt: a
+// throw is `false` for each, which is what the composition root did before the move.
+
+import { cancelVoidsOpenTurn, type ThreadCancel } from './session-cancel.js'
+
+/** The hook signal fields these questions read (a `SessionSignal` satisfies it). */
+export interface TurnEvidenceSignal {
+  turnOpen: boolean
+  lastEvent: string
+  lastEventAt: number
+  turnStartedAt: number | null
+  stopAt: number | null
+  subagentsOpen: number
+}
+
+/** The transcript tail's own verdict (`transcriptTurnVerdict`). */
+export interface TurnEvidenceVerdict {
+  ended: boolean
+  reason?: string | null
+}
+
+export interface QueueTurnEvidenceDeps {
+  /** The hooks' signal for a Claude session; undefined when the hooks are off or silent. */
+  signalFor: (threadId: string) => TurnEvidenceSignal | undefined
+  /** `registryIdleAfterStop`: true only when the live record flipped idle at or after `stopAt`. */
+  registryIdleAfterStop: (threadId: string, stopAt: number) => boolean | null
+  /** `deskTurnEndedAt`: when the desk session's engine said its run is over, as it stands now. */
+  deskEndedAt: (threadId: string) => number | null
+  /** The transcript's mtime, or null when unmeasurable. */
+  transcriptMtimeMs: (provider: string, threadId: string) => number | null
+  /** The transcript tail's verdict, or null when unreadable. */
+  transcriptVerdict: (provider: string, threadId: string) => TurnEvidenceVerdict | null
+  /** The cancel on record for the thread (`threadCancel`). */
+  threadCancel: (provider: string, threadId: string) => ThreadCancel | null
+  /** Past this age a signal or a tail is not evidence any more (OPEN_TURN_CEILING_MS). */
+  openTurnCeilingMs: number
+  now: () => number
+}
+
+export interface QueueTurnEvidence {
+  turnEnded: (provider: string, threadId: string) => boolean
+  turnOpen: (provider: string, threadId: string) => boolean
+}
+
+export function makeQueueTurnEvidence(deps: QueueTurnEvidenceDeps): QueueTurnEvidence {
+  const mtime = (provider: string, threadId: string): number | null => {
+    const value = deps.transcriptMtimeMs(provider, threadId)
+    return typeof value === 'number' && Number.isFinite(value) ? value : null
+  }
+  /** Read once per question, and only when a cancel is on record (it scans the registry). */
+  const deskEnded = (provider: string, threadId: string): (() => number | null) => {
+    let cached: number | null | undefined
+    return () => {
+      if (cached === undefined) cached = provider === 'claude' ? deps.deskEndedAt(threadId) : null
+      return cached
+    }
+  }
+
+  const turnEnded = (provider: string, threadId: string): boolean => {
+    if (provider !== 'claude' && provider !== 'codex') return false
+    try {
+      const signal = provider === 'claude' ? deps.signalFor(threadId) : undefined
+      // 6.53.0: a cancel ends the turn when nothing was written since it (a killed COS
+      // child leaves its last tool_use unanswered, and no Stop or terminal record follows).
+      // 6.53.3: only a cos_turn cancel concludes that; a desk_run cancel needs the desk's
+      // own end, stamped at or after the cancel.
+      const cancel = deps.threadCancel(provider, threadId)
+      if (cancel !== null && cancelVoidsOpenTurn({
+        cancel,
+        lastActivityAt: mtime(provider, threadId),
+        turnStartedAt: signal?.turnStartedAt ?? null,
+        deskEndedAt: deskEnded(provider, threadId)(),
+      })) return true
+      // 6.48.1: the engine's own end of turn: a Stop hook newer than the turn's prompt
+      // AND the registry flipped idle after it (the Stop hooks have returned; a prompt
+      // typed during them is queued and dequeues only then). The transcript tail
+      // answers for everything the hooks did not see. Both refuse on doubt.
+      if (provider === 'claude') {
+        if (signal && !signal.turnOpen && signal.lastEvent === 'Stop' && typeof signal.stopAt === 'number'
+          && signal.stopAt >= (signal.turnStartedAt ?? 0) && signal.subagentsOpen === 0
+          && deps.registryIdleAfterStop(threadId, signal.stopAt) === true) return true
+      }
+      return deps.transcriptVerdict(provider, threadId)?.ended === true
+    } catch {
+      return false
+    }
+  }
+
+  // 6.48.1: positive evidence the holder's turn is OPEN, which outranks the 30 s idle
+  // backstop (a long tool leaves the transcript untouched while it runs). Bounded: a
+  // signal or a tail older than the ceiling is not evidence any more, so a crashed
+  // mid-tool session still drains by the backstop rather than holding for the TTL.
+  const turnOpen = (provider: string, threadId: string): boolean => {
+    if (provider !== 'claude' && provider !== 'codex') return false
+    try {
+      const now = deps.now()
+      const cancel = deps.threadCancel(provider, threadId)
+      const ended = deskEnded(provider, threadId)
+      if (provider === 'claude') {
+        const signal = deps.signalFor(threadId)
+        if (signal && signal.turnOpen && now - signal.lastEventAt <= deps.openTurnCeilingMs
+          && !(cancel !== null && cancelVoidsOpenTurn({
+            cancel,
+            lastActivityAt: signal.lastEventAt,
+            turnStartedAt: signal.turnStartedAt,
+            deskEndedAt: ended(),
+          }))) return true
+      }
+      const verdict = deps.transcriptVerdict(provider, threadId)
+      if (!verdict || verdict.ended) return false
+      if (verdict.reason !== 'tool_pending' && verdict.reason !== 'prompt_open') return false
+      const last = mtime(provider, threadId)
+      // 6.53.0 / 6.53.3: a cos_turn cancel with nothing written since discounts a dangling
+      // tool_use (the killed child's); a desk_run cancel only once the desk said it ended.
+      if (cancel !== null && cancelVoidsOpenTurn({ cancel, lastActivityAt: last, turnStartedAt: null, deskEndedAt: ended() })) return false
+      return last !== null && now - last <= deps.openTurnCeilingMs
+    } catch {
+      return false
+    }
+  }
+
+  return { turnEnded, turnOpen }
+}

package/server/lib/session-cancel.ts

@@ -104,30 +104,47 @@ export const CANCEL_QUEUE_HOLD_MS = 2 * 60_000
 export const CANCEL_MEMORY_MS = 60 * 60_000
 const MAX_REMEMBERED_CANCELS = 256
 
+/**
+ * One cancel on record for a thread (6.53.3): WHEN, and WHAT it was aimed at. The target
+ * decides what the cancel may conclude about a turn that still reads open (see
+ * `cancelVoidsOpenTurn`). Null is an older caller that did not say; it is read as a desk
+ * run, the reading that concludes the least.
+ */
+export interface ThreadCancel {
+  at: number
+  target: CancelTarget | null
+}
+
 // In memory on purpose: every reader is a hold of minutes, and a restart that forgets
 // one lets the queue drain by the gate's ordinary rules, which is the pre-6.53 behaviour.
-const cancelledAtByThread = new Map<string, number>()
+const cancelsByThread = new Map<string, ThreadCancel>()
 const cancelKey = (provider: string, threadId: string) => `${provider}:${threadId.toLowerCase()}`
 
-export function noteThreadCancelled(provider: string, threadId: string, at: number): void {
+export function noteThreadCancelled(provider: string, threadId: string, at: number, target: CancelTarget | null = null): void {
   if (!Number.isFinite(at)) return
   const key = cancelKey(provider, threadId)
-  cancelledAtByThread.delete(key)
-  cancelledAtByThread.set(key, at)
-  if (cancelledAtByThread.size > MAX_REMEMBERED_CANCELS) {
-    for (const [k, when] of cancelledAtByThread) {
-      if (at - when > CANCEL_MEMORY_MS) cancelledAtByThread.delete(k)
+  cancelsByThread.delete(key)
+  cancelsByThread.set(key, { at, target })
+  if (cancelsByThread.size > MAX_REMEMBERED_CANCELS) {
+    for (const [k, when] of cancelsByThread) {
+      if (at - when.at > CANCEL_MEMORY_MS) cancelsByThread.delete(k)
     }
-    while (cancelledAtByThread.size > MAX_REMEMBERED_CANCELS) {
-      const oldest = cancelledAtByThread.keys().next()
+    while (cancelsByThread.size > MAX_REMEMBERED_CANCELS) {
+      const oldest = cancelsByThread.keys().next()
       if (oldest.done) break
-      cancelledAtByThread.delete(oldest.value)
+      cancelsByThread.delete(oldest.value)
     }
   }
 }
 
 export function threadCancelledAt(provider: string, threadId: string): number | null {
-  return cancelledAtByThread.get(cancelKey(provider, threadId)) ?? null
+  return cancelsByThread.get(cancelKey(provider, threadId))?.at ?? null
+}
+
+/** 6.53.3: the cancel on record for the thread, with its target; null when none. A copy. */
+export function threadCancel(provider: string, threadId: string): ThreadCancel | null {
+  const found = cancelsByThread.get(cancelKey(provider, threadId))
+  return found ? { at: found.at, target: found.target } : null
 }
 
 /** Until when the thread's parked turns hold, or null when no cancel is on record. */
@@ -151,8 +168,49 @@ export function cancelEndsTurn(cancelledAt: number | null, lastRowAt: number | n
   return cancelledAt >= lastRowAt
 }
 
+/** What `cancelVoidsOpenTurn` weighs for one piece of open-turn evidence. */
+export interface OpenTurnEvidence {
+  /** The cancel on record for the thread (`threadCancel`), or null. */
+  cancel: ThreadCancel | null
+  /** When the evidence was last written: the hook's newest event, or the transcript mtime. */
+  lastActivityAt: number | null
+  /** When the turn the evidence belongs to STARTED (the hook's UserPromptSubmit); null when unknown. */
+  turnStartedAt: number | null
+  /**
+   * When the desk session's own engine said the run is over, as it stands NOW: the
+   * registry's `idle` flip (`statusUpdatedAt`), or the hooks' Stop / StopFailure /
+   * SessionEnd while no turn is open. Null when nothing says so.
+   */
+  deskEndedAt: number | null
+}
+
+/**
+ * 6.53.3 (review A1): may the cancel on record discount evidence that the thread's turn
+ * is still OPEN?
+ *
+ *   cos_turn   COS killed its own child. Nothing written since the cancel means the turn
+ *              is over: the dangling `tool_use` is the dead child's (6.53.0, `cancelEndsTurn`).
+ *   desk_run   A halt marker stops a desk run only at its NEXT tool call, so a run inside a
+ *              long tool writes nothing for minutes and is still running. Silence proves
+ *              nothing here. Only the engine's own end, stamped at or after the cancel and
+ *              after the turn began, closes it. Until 6.53.2 the cos_turn rule applied to
+ *              both, and a turn parked behind a cancelled desk run was delivered live into
+ *              the run the person had just stopped (and its UserPromptSubmit then deleted
+ *              the marker, so the cancel was lost).
+ *   null       An older caller that did not say: read as desk_run, which concludes least.
+ */
+export function cancelVoidsOpenTurn(evidence: OpenTurnEvidence): boolean {
+  const { cancel } = evidence
+  if (cancel === null || !Number.isFinite(cancel.at)) return false
+  if (cancel.target === 'cos_turn') return cancelEndsTurn(cancel.at, evidence.lastActivityAt)
+  const ended = evidence.deskEndedAt
+  if (ended === null || !Number.isFinite(ended) || ended < cancel.at) return false
+  const started = evidence.turnStartedAt
+  return started === null || !Number.isFinite(started) || ended >= started
+}
+
 export function __resetThreadCancelsForTests(): void {
-  cancelledAtByThread.clear()
+  cancelsByThread.clear()
 }
 
 // ---------------------------------------------------------------------------

package/server/lib/session-halt.ts

@@ -28,12 +28,17 @@
 //   - a sweep deletes anything older than HALT_MARKER_TTL_MS.
 // It is NOT deleted on Stop: a background subagent reports its parent's session id (C8),
 // and it is exactly the work a cancel must also stop.
+//
+// 6.53.3: ONE exception to "a new prompt clears it": a turn COS itself handed into the open
+// session while a cancel was on its way (`haltDeliveredTurn`). That turn's own prompt must
+// not be the one that frees it, so the server writes the marker back, once, when it sees it.
 
 import { mkdirSync, readFileSync, readdirSync, statSync, unlinkSync } from 'node:fs'
 import { join } from 'node:path'
 import { atomicWriteFileSync } from './atomic-fs.js'
 import { dataPath } from './data-dir.js'
 import { isValidNativeThreadId } from './native-thread-id.js'
+import { unwrapPeerMessage } from './session-stream-events.js'
 
 /**
  * How long a marker may outlive its cancel. An hour, not the plan's first 15 minutes: the
@@ -42,6 +47,14 @@ import { isValidNativeThreadId } from './native-thread-id.js'
  */
 export const HALT_MARKER_TTL_MS = 60 * 60_000
 
+/**
+ * 6.53.3 /qa: how long a re-arm waits when the hand-off was NOT verified (`maybe`: the frame
+ * may or may not have reached the session). A verified hand-off keeps the marker's hour; an
+ * unverified one that has not surfaced as a prompt within two minutes most likely never
+ * arrived, and holding it longer only widens the window for an identical desk prompt.
+ */
+export const HALT_REARM_UNVERIFIED_MS = 2 * 60_000
+
 export interface HaltMarker {
   at: number
   clientCancelId: string
@@ -105,6 +118,134 @@ export function clearHaltMarkerOnSessionEnd(sessionId: string, endedAt: number,
   }
 }
 
+// ---------------------------------------------------------------------------
+// 6.53.3 (review A6): a cancel that landed while COS was HANDING a turn to the open session
+// ---------------------------------------------------------------------------
+//
+// The live hop writes the turn into the running session's inbox, where it waits its turn
+// (a busy session) or starts at once (an idle one). Once it has landed, the only stop is
+// this marker. But the hook deletes the marker on UserPromptSubmit, and the delivered
+// turn's OWN UserPromptSubmit may come after the marker is written: a busy session takes
+// the message only when its current run ends (which the marker itself brings about). A
+// plain write would then be deleted by the very turn it was written to stop.
+//
+// So the marker is written, and when the delivered turn has not visibly started yet, it is
+// written AGAIN, once, on the first UserPromptSubmit for that session AFTER the send, if that
+// prompt IS the delivered one. The window is the marker's own hour (two minutes for an
+// unverified hand-off); SessionEnd drops it. In memory on purpose: a restart forgets it, like
+// every other hold here.
+//
+// 6.53.3 /qa (Skeptic W1): the first cut matched `prompt.includes(<first 120 characters>)`.
+// A short COS prompt ("yes") is inside most desk prompts, so the person's own next prompt
+// re-armed the marker: THEIR run was denied "Cancelled from COS", and the delivered turn's
+// own prompt, finding nothing pending, then ran the cancelled turn. Now:
+//   - EXACT: the delivered words and the prompt's words are equal once whitespace runs are
+//     collapsed and Claude Code's peer wrapper ("Another Claude session sent a message: ...",
+//     which a live Continue arrives in) is taken off. The frame carries no id of its own and
+//     its text is not changed to add one.
+//   - FIRST PROMPT DECIDES: the first prompt after the send spends the re-arm whether or not
+//     it matches. A non-match is logged (never the prompt). This gives up the cancel when
+//     the person's own prompt reaches the session first, rather than risk halting their run:
+//     a halted desk run is the worse error, and the lens already said "at its next step".
+//   - LIMIT, stated: a desk prompt with exactly the delivered words, typed after the send and
+//     taken first, is indistinguishable from the delivered turn and re-arms.
+
+interface PendingRearm {
+  marker: HaltMarker
+  /** The delivered prompt's words, whitespace-normalised (`normalizePromptWords`). */
+  words: string
+  /** Prompts submitted before this are someone else's. */
+  after: number
+  until: number
+}
+
+const pendingRearms = new Map<string, PendingRearm>()
+const MAX_PENDING_REARMS = 64
+
+/**
+ * Write the marker for a turn COS just put into the open session. `rearm` is false when
+ * the turn has visibly started already (its UserPromptSubmit ran before this write, so
+ * nothing will delete the marker but the next prompt). False when the write failed; the
+ * caller must then not report the cancel as armed.
+ */
+export function haltDeliveredTurn(
+  sessionId: string,
+  marker: HaltMarker,
+  turn: { prompt: string; after: number; rearm: boolean; now?: number; windowMs?: number },
+  dir = haltDir(),
+): boolean {
+  if (!writeHaltMarker(sessionId, marker, dir)) return false
+  const id = sessionId.toLowerCase()
+  const words = normalizePromptWords(turn.prompt)
+  if (!turn.rearm || words.length === 0) {
+    pendingRearms.delete(id)
+    return true
+  }
+  const now = turn.now ?? Date.now()
+  const windowMs = typeof turn.windowMs === 'number' && Number.isFinite(turn.windowMs) && turn.windowMs > 0
+    ? Math.min(turn.windowMs, HALT_MARKER_TTL_MS)
+    : HALT_MARKER_TTL_MS
+  pendingRearms.delete(id)
+  pendingRearms.set(id, { marker, words, after: turn.after, until: now + windowMs })
+  while (pendingRearms.size > MAX_PENDING_REARMS) {
+    const oldest = pendingRearms.keys().next()
+    if (oldest.done) break
+    pendingRearms.delete(oldest.value)
+  }
+  return true
+}
+
+/** Whitespace runs collapsed to one space, ends trimmed. Non-strings are empty. */
+export function normalizePromptWords(text: unknown): string {
+  return typeof text === 'string' ? text.replace(/\s+/g, ' ').trim() : ''
+}
+
+/**
+ * Is `prompt` (a UserPromptSubmit's `prompt`) the delivered prompt? Equal words, compared
+ * whole, after taking off Claude Code's peer wrapper when the prompt arrived in one.
+ */
+export function isDeliveredPrompt(prompt: unknown, delivered: string): boolean {
+  const want = normalizePromptWords(delivered)
+  if (want.length === 0 || typeof prompt !== 'string') return false
+  return normalizePromptWords(unwrapPeerMessage(prompt) ?? prompt) === want
+}
+
+/**
+ * A UserPromptSubmit from the session itself (never a COS child): the hook has just deleted
+ * the session's marker. The FIRST such prompt after the send spends the pending re-arm: when
+ * it is the delivered turn's own prompt the marker is written back, otherwise the re-arm is
+ * dropped and logged. True when the marker was re-armed.
+ */
+export function rearmHaltOnPrompt(sessionId: string, promptAt: number, prompt: unknown, dir = haltDir(), now = Date.now()): boolean {
+  const id = typeof sessionId === 'string' ? sessionId.toLowerCase() : ''
+  const pending = pendingRearms.get(id)
+  if (!pending) return false
+  if (now > pending.until) {
+    pendingRearms.delete(id)
+    return false
+  }
+  if (!Number.isFinite(promptAt) || promptAt < pending.after) return false
+  pendingRearms.delete(id)
+  if (!isDeliveredPrompt(prompt, pending.words)) {
+    console.warn(`[session-halt] re-arm dropped: the first prompt after the hand-off was not the delivered turn session=${id.slice(0, 8)} clientCancelId=${pending.marker.clientCancelId}`)
+    return false
+  }
+  return writeHaltMarker(id, pending.marker, dir)
+}
+
+/** The session ended: nothing is left to stop. */
+export function dropHaltRearm(sessionId: string): void {
+  if (typeof sessionId === 'string') pendingRearms.delete(sessionId.toLowerCase())
+}
+
+export function hasPendingHaltRearm(sessionId: string): boolean {
+  return typeof sessionId === 'string' && pendingRearms.has(sessionId.toLowerCase())
+}
+
+export function __resetHaltRearmsForTests(): void {
+  pendingRearms.clear()
+}
+
 export function hasHaltMarker(sessionId: string, dir = haltDir()): boolean {
   const path = haltMarkerPath(sessionId, dir)
   if (path === null) return false