@humwick/runner 0.0.0-stage → 0.130.1

package/src/test-run-dedup.ts

@@ -0,0 +1,435 @@
+import { relayEnv } from "@humwick/sdk/env";
+// #2142 — per-agent test-run dedup ("latest wins").
+//
+// Workers run `bun run test:affected` after every file change. When a change touches something
+// broad, a single run takes 10-15 minutes — and the agent starts the NEXT run long before the
+// previous one finishes. The stacked runs saturate the host: each one holds a gate slot, forks
+// its own shard processes, and the oldest run's result is thrown away the moment it lands.
+// Instructions don't fix this (an agent rationalizes around them), so the bound has to be
+// structural and live BELOW the agent: the runner watches its own session's process tree and,
+// whenever it sees more than one independent test run, kills every run except the newest.
+//
+// Scoping is per-agent BY CONSTRUCTION: the sweep only ever looks at processes it can PROVE belong
+// to this agent — descendants of this session's provider process (the tmux pane pid / direct child
+// pid the adapter already resolves for busy-liveness), plus processes carrying this agent's
+// AGENT_RELAY_ID in their environment. A sibling agent's runs satisfy neither test, so this can
+// never fratricide the fleet the way a host-wide `pkill -f` would (#753). It is also
+// provider-agnostic — nothing here knows whether the tree belongs to Claude or Codex.
+//
+// #2461 — the env-tag half of that ownership test is new, and it is why this file exists at all
+// after the lease landed. Ancestry ALONE made this a no-op for the case the issue reports: a
+// `relay_run` gate run executes under the ORCHESTRATOR daemon, a tree that shares no ancestor with
+// the provider pane, so a descendant-scoped sweep could never see it. The orchestrator now stamps
+// AGENT_RELAY_ID onto those children, which is what makes them attributable here.
+//
+// This sweep is now the BACKSTOP, not the primary mechanism. Kill-replace happens at LAUNCH, in
+// sdk/src/gate-run-lease.ts, entered from `scripts/gate-slot` and the orchestrator. What is left
+// for the sweep is the residual shape neither front door sees: a gate run started straight from the
+// provider shell in a repo that does not route through `gate.sh`. It is 15s-late by construction —
+// that is the documented coverage gap, tracked for a launch-exact PATH shim in the follow-up issue.
+// When a live lease holder exists it is AUTHORITATIVE: the sweep keeps it and kills the rest, so
+// the two mechanisms can never disagree about which run survives.
+import { execFile } from "node:child_process";
+import { readFileSync, readdirSync } from "node:fs";
+import { promisify } from "node:util";
+import { errMessage } from "@humwick/sdk";
+import { killPid, waitForPidsExit } from "@humwick/sdk/process-utils";
+import { classifyGateRun, isTestRunCommand, type GateRunCommands } from "@humwick/sdk/gate-run-classify";
+import { GATE_RUN_AGENT_ENV } from "@humwick/sdk/gate-run-lease";
+import type { ManagedProcess } from "./adapter";
+
+// Re-exported so the sweep and both lease front doors share ONE definition of "is this a test run".
+// It moved to the sdk in #2461 because the orchestrator (a separate workspace that cannot import
+// runner/) needs the same rule; keeping the name exported here keeps every existing caller intact.
+export { isTestRunCommand };
+
+const execFileAsync = promisify(execFile);
+
+/** How often the runner re-reads the process table looking for stacked runs. A stale run is
+ *  therefore killed within a sweep of the new one starting — the waste this bounds is measured
+ *  in minutes, so paying one `ps -e` per agent per sweep to catch it is a good trade. */
+export const TEST_RUN_DEDUP_SWEEP_MS = 15_000;
+
+/** Hard bound on the `ps` read, mirroring the sdk's process-table sweep: a hung `ps` must never
+ *  suspend the runner's maintenance timers. `execFile` SIGKILLs at the deadline and rejects,
+ *  which the caller treats as "no table this sweep". */
+const PROCESS_TABLE_TIMEOUT_MS = 10_000;
+
+/** `ps -eo args=` on a host with many agents produces a large table; the node default (1MB)
+ *  would truncate it into a parse error rather than a partial read. */
+const PROCESS_TABLE_MAX_BUFFER = 8 * 1024 * 1024;
+
+/** Grace given to a SIGTERM'd run's tree before the sweep escalates to SIGKILL. `bun test`
+ *  handles SIGTERM promptly; a wedged shard must not be allowed to keep its gate slot. */
+const KILL_GRACE_MS = 3_000;
+
+export interface ProcessRow {
+  pid: number;
+  ppid: number;
+  /** Seconds since the process started (`ps etime`). LOWER means NEWER. */
+  elapsedSeconds: number;
+  /** Full argv joined by spaces (`ps args`). */
+  args: string;
+}
+
+function validPid(pid: unknown): pid is number {
+  return typeof pid === "number" && Number.isInteger(pid) && pid > 1;
+}
+
+/**
+ * Pick the process tree which actually executes this session's shell commands.
+ *
+ * Most providers expose that child as both `process.pid` and `pid`. Interactive
+ * Codex is intentionally different: `pid` is the visible remote TUI, while
+ * `process` is the App Server that owns Codex turns and their command children.
+ * Rooting at the TUI made #2142 a no-op for exactly those Codex sessions. Prefer
+ * the runner-owned execution child, then retain the historical managed-pid and
+ * adapter-specific fallbacks for tmux-backed providers.
+ */
+export function resolveTestRunRootPid(
+  managedProcess: ManagedProcess | undefined,
+  resolveBusyPid?: (process: ManagedProcess) => number | undefined,
+): number | undefined {
+  const executionPid = managedProcess?.process?.pid;
+  if (validPid(executionPid)) return executionPid;
+  if (validPid(managedProcess?.pid)) return managedProcess.pid;
+  const fallbackPid = managedProcess ? resolveBusyPid?.(managedProcess) : undefined;
+  return validPid(fallbackPid) ? fallbackPid : undefined;
+}
+
+/** Parse `ps` `etime` (`[[dd-]hh:]mm:ss`) into seconds. Returns null when unparseable so the
+ *  caller can drop the row rather than invent an age and mis-rank which run is newest. */
+export function parseElapsedSeconds(etime: string): number | null {
+  const trimmed = etime.trim();
+  const match = trimmed.match(/^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)$/);
+  if (!match) return null;
+  const days = Number(match[1] ?? 0);
+  const hours = Number(match[2] ?? 0);
+  const minutes = Number(match[3]);
+  const seconds = Number(match[4]);
+  if (![days, hours, minutes, seconds].every(Number.isFinite)) return null;
+  return days * 86_400 + hours * 3_600 + minutes * 60 + seconds;
+}
+
+/** Parse the output of `ps -eo pid=,ppid=,etime=,args=`. Unparseable lines are skipped: a
+ *  partial table still lets the sweep act on the runs it CAN see, and a row it cannot age is
+ *  exactly the row it must not rank. */
+export function parseProcessTable(text: string): ProcessRow[] {
+  const rows: ProcessRow[] = [];
+  for (const line of text.split("\n")) {
+    const match = line.match(/^\s*(\d+)\s+(\d+)\s+(\S+)\s+(.+?)\s*$/);
+    if (!match) continue;
+    const pid = Number(match[1]);
+    const ppid = Number(match[2]);
+    const elapsedSeconds = parseElapsedSeconds(match[3] ?? "");
+    const args = match[4];
+    if (!Number.isFinite(pid) || !Number.isFinite(ppid) || elapsedSeconds === null || args === undefined) continue;
+    rows.push({ pid, ppid, elapsedSeconds, args });
+  }
+  return rows;
+}
+
+/**
+ * Pids whose ENVIRONMENT names `agentId` as their owner — the half of ownership that ancestry
+ * cannot express (#2461). A `relay_run` gate run is a child of the orchestrator daemon, not of this
+ * agent's provider pane, so it is reachable only through the tag the orchestrator stamps on it.
+ *
+ * Linux reads `/proc/<pid>/environ` directly: no subprocess, and unreadable entries (another user's
+ * process, a pid that exited mid-scan) are simply skipped. macOS has no /proc, so it takes ONE bulk
+ * `ps -E` — the environment is appended to the command column for processes this user owns, which
+ * is exactly the set that could be ours. Both paths fail CLOSED: an unreadable table yields no
+ * tagged pids, which narrows the sweep's scope rather than widening it.
+ */
+export async function collectAgentTaggedPids(agentId: string, platform: string = process.platform): Promise<number[]> {
+  if (!agentId) return [];
+  const needle = `${GATE_RUN_AGENT_ENV}=${agentId}`;
+  if (platform === "linux") {
+    const pids: number[] = [];
+    let entries: string[];
+    try { entries = readdirSync("/proc"); } catch { return []; }
+    for (const entry of entries) {
+      const pid = Number(entry);
+      if (!Number.isInteger(pid) || pid <= 1) continue;
+      try {
+        // NUL-separated KEY=VALUE pairs; the tag must match a WHOLE entry, so a different agent id
+        // that merely has ours as a prefix can never be mistaken for it.
+        const environ = readFileSync(`/proc/${pid}/environ`, "utf8");
+        if (environ.split("\0").includes(needle)) pids.push(pid);
+      } catch {}
+    }
+    return pids;
+  }
+  try {
+    const { stdout } = await execFileAsync("ps", ["-E", "-ww", "-o", "pid=,command="], {
+      encoding: "utf8",
+      timeout: PROCESS_TABLE_TIMEOUT_MS,
+      killSignal: "SIGKILL",
+      maxBuffer: PROCESS_TABLE_MAX_BUFFER,
+    });
+    const pids: number[] = [];
+    for (const line of stdout.split("\n")) {
+      const match = line.match(/^\s*(\d+)\s+(.*)$/);
+      if (!match) continue;
+      // `ps -E` renders the environment space-separated, so a whole-token test is the analogue of
+      // the NUL split above: `AGENT_RELAY_ID=x` must not match agent `xy`.
+      if (!match[2]!.split(/\s+/).includes(needle)) continue;
+      const pid = Number(match[1]);
+      if (Number.isInteger(pid) && pid > 1) pids.push(pid);
+    }
+    return pids;
+  } catch {
+    return [];
+  }
+}
+
+export interface TestRunDedupPlan {
+  /** The surviving (newest) run's root pid, when a stale run was found. */
+  keptPid?: number;
+  /** Root pids of the runs to kill — every run strictly older than the newest. */
+  staleRoots: number[];
+  /** Every pid to signal, the stale roots plus their descendants, deepest-first. */
+  killPids: number[];
+}
+
+const EMPTY_PLAN: TestRunDedupPlan = { staleRoots: [], killPids: [] };
+
+/**
+ * Decide which test runs to kill inside `rootPid`'s process tree. Pure, so the whole "latest
+ * wins" decision is testable without a real process tree.
+ *
+ * Two properties do the safety work here:
+ *  - only STRICT descendants of `rootPid` are ever considered, so the blast radius is one agent;
+ *  - a matching process that has a matching ANCESTOR is not a run root, it is a step INSIDE one
+ *    (`bun run test:affected` → `bun run scripts/test-affected.ts` → `bun test <shard>`), so a
+ *    single healthy run presents exactly one root and is never touched.
+ */
+export interface TestRunDedupScope {
+  /** Pids proven to belong to this agent by their ENVIRONMENT rather than by ancestry (#2461).
+   *  These extend the scope; they are never used as tree roots, because a tagged process is
+   *  usually INSIDE the run rather than above it. */
+  ownedPids?: readonly number[];
+  /** The live gate-run lease holder, when there is one. AUTHORITATIVE: the sweep keeps this run and
+   *  kills the rest, so the launch-time lease and this backstop can never disagree about which run
+   *  survives. Absent ⇒ fall back to newest-wins. */
+  keepPid?: number | undefined;
+  /** Classifier override. Defaults to the argv-shape heuristic; the sweep passes a classifier bound
+   *  to the repo's CONFIGURED gate commands so a foreign runner (`pnpm tier:run …`) is matched too. */
+  isGateRun?: (args: string) => boolean;
+}
+
+export function planTestRunDedup(
+  rows: ProcessRow[],
+  rootPid: number,
+  protectedPids: number[] = [],
+  scope: TestRunDedupScope = {},
+): TestRunDedupPlan {
+  const rootValid = Number.isInteger(rootPid) && rootPid > 1;
+  const owned = (scope.ownedPids ?? []).filter((pid) => Number.isInteger(pid) && pid > 1);
+  const isGateRun = scope.isGateRun ?? isTestRunCommand;
+  if (!rootValid && owned.length === 0) return EMPTY_PLAN;
+  const byPid = new Map<number, ProcessRow>();
+  const childrenByParent = new Map<number, number[]>();
+  for (const row of rows) {
+    byPid.set(row.pid, row);
+    const siblings = childrenByParent.get(row.ppid) ?? [];
+    siblings.push(row.pid);
+    childrenByParent.set(row.ppid, siblings);
+  }
+  const ownedInTable = owned.filter((pid) => byPid.has(pid));
+  if (!byPid.has(rootPid) && ownedInTable.length === 0) return EMPTY_PLAN;
+
+  const subtree = (pid: number): number[] => {
+    const seen = new Set<number>();
+    const queue = [pid];
+    while (queue.length > 0) {
+      const current = queue.shift()!;
+      if (seen.has(current)) continue;
+      seen.add(current);
+      for (const child of childrenByParent.get(current) ?? []) queue.push(child);
+    }
+    return [...seen];
+  };
+
+  // Ownership is the UNION of the two proofs: descended from this session's provider process, or
+  // carrying this agent's id in its environment. Neither alone covers both launch paths (#2461).
+  const sessionPids = new Set<number>(byPid.has(rootPid) ? subtree(rootPid) : []);
+  for (const pid of ownedInTable) sessionPids.add(pid);
+  const candidates = new Set<number>();
+  for (const pid of sessionPids) {
+    if (pid === rootPid) continue;
+    const row = byPid.get(pid);
+    if (row && isGateRun(row.args)) candidates.add(pid);
+  }
+  if (candidates.size < 2) return EMPTY_PLAN;
+
+  // A candidate is a run ROOT only when nothing between it and the session root is also a
+  // candidate — i.e. it is the outermost test process of its own run.
+  const runRoots: number[] = [];
+  for (const pid of candidates) {
+    let ancestor = byPid.get(pid)?.ppid;
+    let nested = false;
+    const walked = new Set<number>([pid]);
+    while (ancestor !== undefined && ancestor > 1 && ancestor !== rootPid && !walked.has(ancestor)) {
+      walked.add(ancestor);
+      if (candidates.has(ancestor)) { nested = true; break; }
+      ancestor = byPid.get(ancestor)?.ppid;
+    }
+    if (!nested) runRoots.push(pid);
+  }
+  if (runRoots.length < 2) return EMPTY_PLAN;
+
+  // Lower elapsed = started later = the run the agent actually wants. `ps etime` only has
+  // second precision, though, and a Codex agent can launch two commands within that second.
+  // Pids are allocated in start order within the host pid namespace, so the higher pid is the
+  // newer root for this otherwise-unresolvable tie. Without this deterministic tie-breaker, two
+  // same-second delivery runs remain tied forever and #2142 fails to bound the exact burst it
+  // was added for. The scope is still this session's process tree only.
+  // A live lease holder wins outright — it is the run the launch-time mechanism already chose. Only
+  // when there is none (an ungated run in a repo without gate.sh) does newest-wins decide.
+  const leaseKeep = scope.keepPid !== undefined && runRoots.includes(scope.keepPid) ? scope.keepPid : undefined;
+  const keptPid = leaseKeep ?? runRoots.reduce((newest, pid) => {
+    const candidate = byPid.get(pid)!;
+    const current = byPid.get(newest)!;
+    return candidate.elapsedSeconds < current.elapsedSeconds
+      || (candidate.elapsedSeconds === current.elapsedSeconds && pid > newest)
+      ? pid
+      : newest;
+  });
+  const newestElapsed = byPid.get(keptPid)!.elapsedSeconds;
+  const staleRoots = runRoots
+    // With a lease holder the age comparison is meaningless — the holder may be the OLDER run, and
+    // it still wins. Without one, keep the original guard so a mis-ranked row is never killed.
+    .filter((pid) => pid !== keptPid && (leaseKeep !== undefined || byPid.get(pid)!.elapsedSeconds >= newestElapsed))
+    .sort((a, b) => a - b);
+  if (staleRoots.length === 0) return EMPTY_PLAN;
+
+  const protectedSet = new Set([rootPid, ...protectedPids]);
+  const depthByPid = new Map<number, number>();
+  const killPids: number[] = [];
+  for (const staleRoot of staleRoots) {
+    // Depth-stamped walk so the signal order is deepest-first: killing a shard before its
+    // supervisor stops the supervisor from noticing the gap and starting a replacement.
+    const queue: Array<{ pid: number; depth: number }> = [{ pid: staleRoot, depth: 0 }];
+    while (queue.length > 0) {
+      const { pid, depth } = queue.shift()!;
+      if (depthByPid.has(pid) || protectedSet.has(pid) || pid <= 1) continue;
+      depthByPid.set(pid, depth);
+      killPids.push(pid);
+      for (const child of childrenByParent.get(pid) ?? []) queue.push({ pid: child, depth: depth + 1 });
+    }
+  }
+  killPids.sort((a, b) => (depthByPid.get(b)! - depthByPid.get(a)!) || (b - a));
+
+  return { keptPid, staleRoots, killPids };
+}
+
+/** Read the host process table with pid/ppid/age/argv. Bounded and SIGKILL-on-deadline. */
+export async function readProcessTable(timeoutMs: number = PROCESS_TABLE_TIMEOUT_MS): Promise<string> {
+  const { stdout } = await execFileAsync("ps", ["-eo", "pid=,ppid=,etime=,args="], {
+    encoding: "utf8",
+    timeout: timeoutMs,
+    killSignal: "SIGKILL",
+    maxBuffer: PROCESS_TABLE_MAX_BUFFER,
+  });
+  return stdout;
+}
+
+export interface TestRunDedupDeps {
+  /** Resolve this session's provider pid. undefined ⇒ ancestry proves nothing; the env tag may. */
+  rootPid: () => number | undefined;
+  /** This agent's id, for the env-tag ownership proof (#2461). Absent ⇒ ancestry-only, as before. */
+  agentId?: () => string | undefined;
+  /** The repo's configured gate commands, so a foreign gate runner is classified exactly rather
+   *  than left to the argv-shape heuristic. */
+  gateCommands?: () => GateRunCommands;
+  /** The live lease holder pid, when one exists — authoritative over newest-wins. */
+  leaseHolderPid?: () => number | undefined;
+  collectOwnedPids?: (agentId: string) => Promise<number[]>;
+  readProcessTable?: () => Promise<string>;
+  kill?: (pid: number, signal: "SIGTERM" | "SIGKILL") => void;
+  waitForExit?: (pids: number[], timeoutMs: number) => Promise<boolean>;
+  log: (message: string) => void;
+  /** Pids the sweep must never signal (the runner's own pid, etc.). */
+  protectedPids?: () => number[];
+  killGraceMs?: number;
+}
+
+/** Run one dedup pass. Returns the pids it signalled (empty when there was nothing to dedup). */
+export async function runTestRunDedupSweep(deps: TestRunDedupDeps): Promise<number[]> {
+  const resolvedRoot = deps.rootPid();
+  const rootPid = resolvedRoot !== undefined && Number.isInteger(resolvedRoot) && resolvedRoot > 1 ? resolvedRoot : 0;
+  const agentId = deps.agentId?.() ?? "";
+  // #2461 — either proof of ownership is enough, but at least one is required. With neither, the
+  // sweep cannot show any process is ours and must do nothing at all.
+  const ownedPids = agentId ? await (deps.collectOwnedPids ?? collectAgentTaggedPids)(agentId) : [];
+  if (rootPid === 0 && ownedPids.length === 0) return [];
+
+  let table: string;
+  try {
+    table = await (deps.readProcessTable ?? readProcessTable)();
+  } catch (error) {
+    // A `ps` that fails or times out just means no dedup this sweep — never a runner failure.
+    deps.log(`test-run dedup: process table read failed: ${errMessage(error)}`);
+    return [];
+  }
+
+  const gateCommands = deps.gateCommands?.() ?? {};
+  const plan = planTestRunDedup(parseProcessTable(table), rootPid, deps.protectedPids?.() ?? [], {
+    ownedPids,
+    keepPid: deps.leaseHolderPid?.(),
+    isGateRun: (args) => classifyGateRun(args, gateCommands) !== null,
+  });
+  if (plan.killPids.length === 0) return [];
+
+  const kill = deps.kill ?? killPid;
+  const waitForExit = deps.waitForExit ?? waitForPidsExit;
+  deps.log(
+    `test-run dedup (#2142): a newer test run started, killing ${plan.staleRoots.length} superseded run(s) ` +
+      `[roots ${plan.staleRoots.join(", ")}; ${plan.killPids.length} pid(s)]` +
+      `${plan.keptPid !== undefined ? `; keeping ${plan.keptPid}` : ""}`,
+  );
+  for (const pid of plan.killPids) kill(pid, "SIGTERM");
+  const exited = await waitForExit(plan.killPids, deps.killGraceMs ?? KILL_GRACE_MS);
+  if (!exited) {
+    for (const pid of plan.killPids) kill(pid, "SIGKILL");
+  }
+  return plan.killPids;
+}
+
+/** True unless the operator has explicitly turned dedup off for this session. */
+export function testRunDedupEnabled(env: Record<string, string | undefined> = process.env): boolean {
+  const raw = (relayEnv(env, "AGENT_RELAY_TEST_DEDUP") ?? "").trim().toLowerCase();
+  return raw !== "0" && raw !== "false" && raw !== "off";
+}
+
+/**
+ * Runner-side maintenance timer: same shape as the attachment-cache sweep — self-arming,
+ * single-flight, and a no-op the moment the session has no resolvable provider pid.
+ */
+export class TestRunDedupSweep {
+  private timer?: Timer;
+  private inFlight = false;
+
+  constructor(private readonly deps: TestRunDedupDeps, private readonly intervalMs: number = TEST_RUN_DEDUP_SWEEP_MS) {}
+
+  start(): void {
+    if (this.timer || !testRunDedupEnabled()) return;
+    const sweep = () => {
+      if (this.inFlight) return;
+      this.inFlight = true;
+      void runTestRunDedupSweep(this.deps)
+        .catch((error) => this.deps.log(`test-run dedup sweep failed: ${errMessage(error)}`))
+        .finally(() => { this.inFlight = false; });
+    };
+    // Do not leave a just-started runner unprotected for its first whole interval.
+    // The interval remains the steady-state mechanism for later overlapping commands.
+    sweep();
+    this.timer = setInterval(sweep, this.intervalMs);
+    this.timer.unref?.();
+  }
+
+  stop(): void {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = undefined;
+  }
+}

package/src/transcript-context.ts

@@ -0,0 +1,99 @@
+import { readFileSync, statSync } from "node:fs";
+import type { ContextState } from "@humwick/sdk";
+import type { ProviderContextUsage } from "./adapter";
+
+// #1512: Claude reports context only through its out-of-band status-line probe,
+// which freezes after an in-process compact/clear/native-resume (no new process,
+// so the probe file stops advancing while the agent keeps taking turns). The
+// transcript — handed to the runner every turn by the Stop hook — carries the
+// same per-turn token usage, so the runner derives fresh context from it here as
+// a probe-independent fallback that keeps context.lastUpdatedAt advancing across
+// those in-process generation bumps. Kept out of runner-core to hold that giant's
+// line budget (epic #291); runner-core just threads its per-session cache through.
+
+export interface TranscriptContextCache {
+  path: string;
+  mtimeMs: number;
+  /** Byte size alongside mtime: a same-second rewrite (coarse mtime granularity) still changes length. */
+  size: number;
+  usage: ProviderContextUsage | undefined;
+}
+
+export interface TranscriptContextInput {
+  /** Latest transcript path the Stop hook reported this session. */
+  transcriptPath: string | undefined;
+  /** The transcript-backed adapter's per-turn usage parser (absent for others). */
+  derive: ((jsonl: string) => ProviderContextUsage | undefined) | undefined;
+  /** Context-window size — stable for the session, so reuse what the probe saw. */
+  tokensMax: number | undefined;
+  /** Prior parse, reused when the transcript's (mtime, size) is unchanged (large files). */
+  cache: TranscriptContextCache | undefined;
+  now: number;
+}
+
+// Returns the derived context (or undefined when it can't be computed) and the
+// cache to carry forward. The context-window size is stable for a session, so we
+// reuse the tokensMax the status-line probe reported at least once rather than
+// re-deriving it from a model catalog the runner doesn't hold; the transcript
+// supplies the per-turn tokensUsed. The parse is cached by transcript (mtime, size)
+// so a large log isn't re-read every 30s heartbeat while nothing new has been
+// written. Size is paired with mtime because an in-process compact/clear/resume can
+// rewrite the transcript within the same coarse mtime tick (1s on some filesystems),
+// which mtime alone would miss — leaving stale context; the length still changes.
+export function transcriptDerivedContext(input: TranscriptContextInput): {
+  context: ContextState | undefined;
+  cache: TranscriptContextCache | undefined;
+} {
+  const { transcriptPath, derive, tokensMax, cache, now } = input;
+  if (!transcriptPath || !derive) return { context: undefined, cache };
+  if (typeof tokensMax !== "number" || !Number.isFinite(tokensMax) || tokensMax <= 0) return { context: undefined, cache };
+
+  let nextCache = cache;
+  let usage: ProviderContextUsage | undefined;
+  try {
+    const stat = statSync(transcriptPath);
+    const mtimeMs = stat.mtimeMs;
+    const size = stat.size;
+    if (cache?.path === transcriptPath && cache.mtimeMs === mtimeMs && cache.size === size) {
+      usage = cache.usage;
+    } else {
+      usage = derive(readFileSync(transcriptPath, "utf8"));
+      nextCache = { path: transcriptPath, mtimeMs, size, usage };
+    }
+  } catch {
+    return { context: undefined, cache };
+  }
+  if (!usage) return { context: undefined, cache: nextCache };
+
+  return { context: providerContextState(usage.tokensUsed, tokensMax, usage.occurredAt ?? now), cache: nextCache };
+}
+
+/** The one ContextState shape for a provider-reported token count against a context window. */
+export function providerContextState(tokensUsed: number, tokensMax: number, lastUpdatedAt: number, confidence: ContextState["confidence"] = "reported"): ContextState {
+  return {
+    utilization: Math.max(0, Math.min(1, tokensUsed / tokensMax)),
+    tokensUsed,
+    tokensMax,
+    lifecycleState: "working",
+    warmTopics: [],
+    tasksSinceCompact: 0,
+    lastUpdatedAt,
+    source: "api",
+    confidence,
+  };
+}
+
+/** The context a provider reports right after it cleared the conversation: an explicit zero, never an omission that leaves the previous usage on the card. */
+export function freshContextState(clearedAt: number, tokensMax?: number): ContextState {
+  return {
+    utilization: 0,
+    ...(tokensMax ? { tokensMax } : {}),
+    lifecycleState: "fresh",
+    warmTopics: [],
+    tasksSinceCompact: 0,
+    lastCompactedAt: clearedAt,
+    lastUpdatedAt: clearedAt,
+    source: "api",
+    confidence: "reported",
+  };
+}

package/src/transport-errors.ts

@@ -0,0 +1,48 @@
+export function walkErrorChain(error: unknown, match: (code: string, name: string, message: string) => boolean): boolean {
+  const seen = new Set<unknown>();
+  let current: unknown = error;
+  while (current && !seen.has(current)) {
+    seen.add(current);
+    const record = typeof current === "object" && current !== null ? current as Record<string, unknown> : undefined;
+    const code = record && typeof record.code === "string" ? record.code : "";
+    const name = record && typeof record.name === "string" ? record.name : "";
+    const message = record && typeof record.message === "string"
+      ? record.message
+      : typeof current === "string" ? current : "";
+    if (match(code, name, message)) return true;
+    current = record?.cause;
+  }
+  return false;
+}
+
+export type TransportErrorClass = "connect" | "ambiguous" | "fatal";
+
+// Sent-then-response-lost: a mid-flight reset or a post-send abort. Safe to retry only when idempotent.
+export function isAmbiguousTransportError(error: unknown): boolean {
+  return walkErrorChain(error, (code, name, message) =>
+    /^(?:ECONNRESET|EPIPE|ETIMEDOUT|ConnectionClosed|ConnectionReset)$/i.test(code) ||
+    name === "AbortError" ||
+    /socket connection was closed|connection was closed unexpectedly|socket hang up|ECONNRESET|EPIPE|ETIMEDOUT|ConnectionClosed|ConnectionReset|the operation was aborted|aborted/i.test(message));
+}
+
+// Connect-phase: the request never reached the relay app. Always safe to retry, for every tool.
+export function isConnectPhaseError(error: unknown): boolean {
+  return walkErrorChain(error, (code, _name, message) =>
+    /^(?:ECONNREFUSED|ENOTFOUND|EAI_AGAIN|EHOSTUNREACH|ENETUNREACH|ECONNABORTED|ConnectionRefused)$/i.test(code) ||
+    /ECONNREFUSED|ENOTFOUND|EAI_AGAIN|EHOSTUNREACH|ENETUNREACH|Unable to connect|failed to fetch|fetch failed|getaddrinfo|connection refused|ConnectionRefused/i.test(message));
+}
+
+export function classifyTransportError(error: unknown): TransportErrorClass {
+  // Ambiguous wins over connect: a reset/abort signal anywhere in the chain means the call MAY have
+  // executed, which is the more conservative (retry-only-if-idempotent) treatment.
+  if (isAmbiguousTransportError(error)) return "ambiguous";
+  if (isConnectPhaseError(error)) return "connect";
+  return "fatal";
+}
+
+// Back-compat: a failure is "retryable transport" if it is either connect-phase or ambiguous (the old
+// single-class predicate #1790 exposed). The retry DECISION now also weighs idempotency for the
+// ambiguous class — see forwardWithConnectionRetry.
+export function isRetryableTransportError(error: unknown): boolean {
+  return classifyTransportError(error) !== "fatal";
+}

package/src/turn-opener.ts

@@ -0,0 +1,55 @@
+import type { Message } from "@humwick/sdk";
+import type { ProviderDeliverContext, ProviderSessionEvent } from "./adapter";
+import { deliveredBatchReplyRoute } from "./reply-obligation-cache";
+
+import { receivesTurnResponseAutomatically } from "./response-routing";
+
+type ReplyRoute = NonNullable<ProviderSessionEvent["replyRoute"]>;
+
+// #2840 — binds the delivered message that OPENS a provider turn to that turn; only its final answers it.
+// Armed before the input is offered (OpenCode runs the whole turn inside deliver, Codex starts it
+// synchronously), bound at the next turn-start edge, consumed by the final with that turn id. A turn
+// that starts with nothing armed clears the binding, so a later timer turn never inherits a question.
+export class TurnOpenerLedger {
+  private pending?: { token: number; route: ReplyRoute | null };
+  private bound?: { turnId: string; route: ReplyRoute };
+  private tokens = 0;
+
+  constructor(private readonly selfId: () => string) {}
+
+  /** These messages are about to open a turn. The dashboard `user` sink is answered by the mirror instead. */
+  arm(messages: Message[]): number {
+    const route = deliveredBatchReplyRoute(messages, this.selfId());
+    this.pending = { token: ++this.tokens, route: route && !receivesTurnResponseAutomatically(route.to) ? route : null };
+    return this.tokens;
+  }
+
+  /** One offer: arms it when it opens a turn, hands the adapter a per-send `openTurnFor`, and
+   *  `settle(false)` disarms an offer that opened nothing (refused, failed, nothing acknowledged). */
+  open(messages: Message[], opensTurn: boolean, ctx?: ProviderDeliverContext): { ctx: ProviderDeliverContext; settle: (opened: boolean) => void } {
+    const token = opensTurn && messages.length > 0 ? this.arm(messages) : undefined;
+    const openTurnFor = (batch: Message[]) => { const sendToken = this.arm(batch); return () => this.disarm(sendToken); };
+    // Replaces only this offer's own still-pending arm, so a narrowing never arms a turn the offer did not open.
+    const narrowTurnOpener = (batch: Message[]) => { if (token === undefined || this.pending?.token !== token) return () => {}; const narrowed = this.arm(batch); return () => this.disarm(narrowed); };
+    return { ctx: { ...ctx, openTurnFor, narrowTurnOpener }, settle: (opened) => { if (token !== undefined && !opened) this.disarm(token); } };
+  }
+
+  /** The offer that armed `token` opened no turn. Never restores. */
+  disarm(token: number): void {
+    if (this.pending?.token === token) this.pending = undefined;
+  }
+
+  noteTurnStarted(turnId: string): void {
+    const route = this.pending?.route;
+    this.pending = undefined;
+    this.bound = route ? { turnId, route } : undefined;
+  }
+
+  /** The opener the final of `turnId` answers, at most once. */
+  take(turnId: string | undefined): ReplyRoute | undefined {
+    if (!turnId || this.bound?.turnId !== turnId) return undefined;
+    const { route } = this.bound;
+    this.bound = undefined;
+    return route;
+  }
+}