@humwick/runner 0.0.0-stage → 0.130.0

package/src/busy-reconciler.ts

@@ -0,0 +1,282 @@
+import { errMessage } from "@humwick/sdk";
+import type { PaneBusyReading } from "./adapter";
+
+type ProviderActivity = "busy" | "idle" | "unknown";
+
+const BUSY_RECONCILE_POLL_MS = 4_000;
+const BUSY_RECONCILE_IDLE_CONFIRM = 8;
+const BUSY_RECONCILE_IDLE_CONFIRM_NO_BUSY = 15;
+const INTERRUPT_RECONCILE_DELAY_MS = 1_500;
+const PROVIDER_TURN_CLEAR_TIMEOUT_MS = 60_000;
+// #1980 U2 — how many consecutive reconcile ticks a live turn may be HELD (never force-cleared,
+// because there is no positive end-evidence) before the backstop escalates a NOTIFY-ONLY
+// watchdog. At the 4s poll this is ~20 min. The escalation NEVER cancels the turn (a 44-min gate
+// is legitimate); it only surfaces "this turn has been held a long time" to the coordinator, so a
+// genuinely wedged-but-active agent (a frozen `busy`, or a pane-scrape-only long tool the runner
+// cannot prove idle) is seen instead of silently cancelled. One-shot per turn (reset on arm/disarm).
+//
+// #2010 INVARIANT: this interval (BUSY_RECONCILE_WATCHDOG_TICKS * BUSY_RECONCILE_POLL_MS, ~20
+// min) must stay >= the server's STUCK_BUSY_PROVIDER_TURN_MS threshold (src/config.ts, default
+// 15 min but operator-configurable via AGENT_RELAY_STUCK_BUSY_PROVIDER_TURN_MS). The server-side
+// gate in auditProviderTurnWatchdog (src/services/turn-reconcile-audit.ts) only wakes the
+// coordinator once staleForMs (time since real last progress) reaches that threshold. If an
+// operator raises the server threshold ABOVE this interval, a genuinely dead-from-the-start turn
+// could reach the watchdog tick count while staleForMs is still under the (raised) threshold —
+// the gate would then suppress a real stall. Keep this interval the larger of the two, or the
+// suppression re-enters.
+export const BUSY_RECONCILE_WATCHDOG_TICKS = 300;
+
+interface BusyReconcilerDeps {
+  isStopped(): boolean;
+  hasProcess(): boolean;
+  currentStatus(): "idle" | "busy" | "offline" | "error";
+  isProviderBlocked(): boolean;
+  hasProviderTurn(): boolean;
+  canProbeActivity(): boolean;
+  probeActivity(): Promise<ProviderActivity> | undefined;
+  // #769 P1-A / #1656: optional independent pane-busy read. `busy` vetoes a clear; `not-busy`
+  // is the positive corroboration every counted idle tick requires; anything else is unknown
+  // and holds the turn. Omitted entirely by providers with no pane to read.
+  probePaneBusy?(): Promise<PaneBusyReading> | undefined;
+  clearProviderTurn(reason: string): void;
+  // #1980 U2 — escalate a NOTIFY-ONLY watchdog for a live turn the backstop has HELD past the
+  // prolonged-hold threshold (a frozen-active `busy`, or a pane-scrape-only long tool that can
+  // never be positively proven idle — probeActivity reads `unknown`, not `idle`, so the clear
+  // paths are never reached). The runner turns this into a coordinator notification; it MUST NOT
+  // cancel the turn. Optional: providers/tests without a watchdog simply hold silently.
+  escalateWatchdog?(reason: string): void;
+  /** Every no-provider-turn edge (#2984: a pending effort change applies here). */
+  turnCleared?(): void;
+  sessionDebug(message: string): void;
+}
+
+export class BusyReconciler {
+  private idleStreak = 0;
+  private timer?: ReturnType<typeof setInterval>;
+  private sawBusy = false;
+  // #1980 U2 — consecutive reconcile ticks this live turn has been held without ending, and the
+  // one-shot guard so the prolonged-hold watchdog notifies at most once per turn. Both reset on
+  // arm/disarm (a new turn starts a fresh hold budget).
+  private heldTicks = 0;
+  private watchdogEscalated = false;
+  // #1838 row 14 — the activity probe now runs OFF the runner's event loop (async tmux
+  // subprocess + probe reads), so a single reconcile can outlast the 4s poll interval when a
+  // tmux socket is slow. This guard drops any timer tick that fires while the previous
+  // reconcile is still in flight, so slow probes can never stack N concurrent reads on one
+  // pane. It is only consulted on the TIMER path (runInBackground); tests that drive run()
+  // directly and await it to completion are unaffected — the flag is always clear by the next
+  // call.
+  private reconcileInFlight = false;
+  // #1838 round-3 HIGH — a monotonic generation, the same await-fence the turn watcher uses.
+  // Captured at the start of a reconcile and re-checked after EVERY await before any streak
+  // mutation or clearProviderTurn: a disarm / re-arm / turn clear that happens while an off-loop
+  // probe is in flight means the verdict describes a STALE turn, so it must not clear a
+  // successor. Bumped on arm, disarm, and every turn-clear signal (providerTurnCleared) — the
+  // three points at which the turn identity this reconciler is judging can change.
+  private generation = 0;
+  private readonly providerTurnClearWaiters = new Set<(error?: Error) => void>();
+
+  constructor(private readonly deps: BusyReconcilerDeps) {}
+
+  arm(): void {
+    if (this.timer || !this.deps.canProbeActivity()) return;
+    this.generation++;
+    this.idleStreak = 0;
+    this.sawBusy = false;
+    this.heldTicks = 0;
+    this.watchdogEscalated = false;
+    this.timer = setInterval(() => this.runInBackground(), BUSY_RECONCILE_POLL_MS);
+  }
+
+  disarm(): void {
+    this.generation++;
+    if (this.timer) clearInterval(this.timer);
+    this.timer = undefined;
+    this.idleStreak = 0;
+    this.sawBusy = false;
+    this.heldTicks = 0;
+    this.watchdogEscalated = false;
+  }
+
+  // #1838 round-3 HIGH — true when an in-flight reconcile that started at `gen` must abandon
+  // without mutating streak state or clearing: the generation moved (arm/disarm/turn clear), or
+  // the turn/process/lifecycle preconditions it verified BEFORE its await no longer hold. Cheap,
+  // synchronous, re-evaluated after each await.
+  private stale(gen: number): boolean {
+    return gen !== this.generation
+      || this.deps.isStopped()
+      || !this.deps.hasProcess()
+      || this.deps.currentStatus() !== "busy"
+      || this.deps.isProviderBlocked()
+      || !this.deps.hasProviderTurn();
+  }
+
+  scheduleInterruptReconcile(): void {
+    setTimeout(() => {
+      if (this.deps.isStopped() || !this.deps.hasProcess()) return;
+      this.reconcileInterruptInBackground();
+    }, INTERRUPT_RECONCILE_DELAY_MS);
+  }
+
+  // These two calls run from timers, so their promises have no caller that can observe a
+  // rejection. In particular clearProviderTurn can synchronously throw while publishing its
+  // durable timeline event during teardown. Catch at this boundary so an expected race cannot
+  // become Bun's process-fatal unhandled rejection; retain the error in the session log.
+  private runInBackground(): void {
+    // #1838 row 14 — skip this tick if the previous off-loop reconcile is still running.
+    if (this.reconcileInFlight) {
+      this.deps.sessionDebug("busy reconcile skipped: previous probe still in flight");
+      return;
+    }
+    this.reconcileInFlight = true;
+    void this.run()
+      .catch((error) => this.reportBackgroundRejection("busy reconcile", error))
+      .finally(() => { this.reconcileInFlight = false; });
+  }
+
+  private reconcileInterruptInBackground(): void {
+    void this.reconcileInterrupt().catch((error) => this.reportBackgroundRejection("post-interrupt reconcile", error));
+  }
+
+  private reportBackgroundRejection(scope: string, error: unknown): void {
+    // Logging must not rethrow from the rejection handler and recreate the same unhandled path.
+    try { this.deps.sessionDebug(`${scope} failed: ${errMessage(error)}`); } catch {}
+  }
+
+  private async reconcileInterrupt(): Promise<void> {
+    const gen = this.generation;
+    if (this.deps.currentStatus() !== "busy" || this.deps.isProviderBlocked()) return;
+    const probe = this.deps.probeActivity();
+    let activity: ProviderActivity = "unknown";
+    try { if (probe) activity = await probe; } catch { return; }
+    // #1838 round-3 HIGH: re-check after the probe await. Turn A was interrupted, its probe
+    // stalled, A ended and Turn B began — A's stale `idle` must NOT clear B. `stale(gen)` catches
+    // the disarm/re-arm/turn-clear (via generation) AND a status/turn that moved out from under us.
+    if (this.stale(gen)) return;
+    this.deps.sessionDebug(`post-interrupt reconcile probe=${activity}`);
+    if (activity === "idle") this.deps.clearProviderTurn("post-interrupt");
+  }
+
+  /** Await the same provider-turn-clear signal maintained by status events and the
+   * interrupt backstop. Redirect uses this boundary before starting its next turn. */
+  waitForProviderTurnClear(timeoutMs = PROVIDER_TURN_CLEAR_TIMEOUT_MS): Promise<void> {
+    if (!this.deps.hasProviderTurn()) return Promise.resolve();
+    return new Promise<void>((resolve, reject) => {
+      let timeout: ReturnType<typeof setTimeout>;
+      const finish = (error?: Error) => {
+        clearTimeout(timeout);
+        this.providerTurnClearWaiters.delete(finish);
+        if (error) reject(error); else resolve();
+      };
+      timeout = setTimeout(() => finish(new Error("timed out waiting for interrupted provider turn to clear")), timeoutMs);
+      timeout.unref?.();
+      this.providerTurnClearWaiters.add(finish);
+    });
+  }
+
+  providerTurnCleared(): void {
+    // #1838 round-3 HIGH — a turn clear/replacement invalidates any in-flight reconcile that was
+    // judging the turn that just ended. Bump BEFORE the waiter-fan-out and the hasProviderTurn
+    // guard: this method is only invoked by the runner on a no-provider-turn edge, so it never
+    // fires during a legitimate active reconcile.
+    this.generation++;
+    if (this.deps.hasProviderTurn()) return;
+    for (const finish of [...this.providerTurnClearWaiters]) finish();
+    this.deps.turnCleared?.();
+  }
+
+  private async run(): Promise<void> {
+    const gen = this.generation;
+    const probe = this.deps.probeActivity();
+    if (this.deps.isStopped() || !this.deps.hasProcess() || !probe) {
+      this.disarm();
+      return;
+    }
+    if (this.deps.currentStatus() !== "busy" || this.deps.isProviderBlocked()) {
+      this.idleStreak = 0;
+      return;
+    }
+    if (!this.deps.hasProviderTurn()) {
+      this.disarm();
+      return;
+    }
+    // #1656: a probe we could not read is `unknown`, not `idle`. It breaks the streak
+    // exactly like any other non-idle reading — it must never be silently skipped past.
+    let activity: ProviderActivity;
+    try { activity = await probe; } catch { activity = "unknown"; }
+    // #1838 round-3 HIGH: re-check after the (off-loop) probe await, BEFORE touching sawBusy /
+    // idleStreak. A disarm/re-arm or turn clear while the probe was in flight means this verdict
+    // is for a stale turn — abandon rather than mutate the successor's streak.
+    if (this.stale(gen)) return;
+    // #1980 U2 — this tick observed a still-live, still-busy provider turn that did not end. A
+    // turn that is genuinely wedged-but-active never reaches a force-clear at all: a frozen
+    // foreground tool keeps reading `busy`, and a pane-scrape-only long tool reads `unknown` (not
+    // `idle`, so its streak never accumulates). Count the hold so such a turn is escalated to a
+    // notify-only watchdog rather than being either silently cancelled OR held forever in silence.
+    this.heldTicks += 1;
+    if (this.heldTicks >= BUSY_RECONCILE_WATCHDOG_TICKS) this.emitWatchdog("prolonged-hold");
+    if (activity === "busy") this.sawBusy = true;
+    if (activity !== "idle") {
+      this.idleStreak = 0;
+      this.deps.sessionDebug(`reconcile probe=${activity} sawBusy=${this.sawBusy} streak=${this.idleStreak}`);
+      return;
+    }
+    // #769 P1-A / #1656: the probe alone does not get to end a turn. An independent pane read
+    // runs on EVERY idle tick — not just once at the force-clear moment — and the streak counts
+    // only ticks where it positively reported `not-busy`. That is the substance of #1656: the
+    // old counter measured "how long since I last saw busy", which a pane that cannot be read at
+    // all satisfies perfectly. It now measures accumulated positive evidence that the turn ended,
+    // and any tick that fails to produce such evidence resets it to zero.
+    const pane = await this.readPaneBusy();
+    // #1838 round-3 HIGH: re-check after the pane await too — this is the tick that can call
+    // clearProviderTurn, so a turn that was replaced during the pane read must not be cleared.
+    if (this.stale(gen)) return;
+    if (pane === "busy") {
+      this.idleStreak = 0;
+      this.sawBusy = true;
+      this.deps.sessionDebug("reconcile probe=idle vetoed: pane still reads busy");
+      return;
+    }
+    if (pane === "no-session" || pane === "unreadable") {
+      this.idleStreak = 0;
+      this.deps.sessionDebug(`reconcile probe=idle but pane=${pane} — unknown, holding the turn`);
+      return;
+    }
+    this.idleStreak += 1;
+    const confirm = this.sawBusy ? BUSY_RECONCILE_IDLE_CONFIRM : BUSY_RECONCILE_IDLE_CONFIRM_NO_BUSY;
+    this.deps.sessionDebug(`reconcile not-busy pane=${pane ?? "none"} sawBusy=${this.sawBusy} streak=${this.idleStreak}/${confirm}`);
+    if (this.idleStreak < confirm) return;
+    // #1980 U2 — reaching here means POSITIVE end-evidence: the activity read is `idle`, which for
+    // a probe-capable Claude session comes only from the provider's own idle assertion or a
+    // busy-verdict a real interrupt / trust-window decay turned idle — NOT from pane silence. A
+    // long foreground tool the runner cannot see now reads `unknown` (probeActivity, #1980 U2),
+    // whose streak resets above, so the `no-busy-observed` force-cancel that lost the 44-min gate
+    // is no longer reachable from silence. Genuine ends still clear here, with their reason +
+    // notification (the interrupted-turn audit downstream).
+    // Capture the reason BEFORE disarm(): disarm resets `sawBusy`, so reading it afterwards (as the
+    // original did) always reported `no-busy-observed`, mislabeling even a genuine sawBusy clear —
+    // the confirm threshold above already branched correctly on the pre-disarm value.
+    const reason = this.sawBusy ? "backstop reconciler" : "backstop reconciler (no-busy-observed)";
+    this.disarm();
+    this.deps.clearProviderTurn(reason);
+  }
+
+  // #1980 U2 — fire the notify-only watchdog at most once per turn. The reconciler NEVER cancels
+  // the turn on this path; it only asks the runner to tell the coordinator the turn is being held.
+  private emitWatchdog(reason: string): void {
+    if (this.watchdogEscalated) return;
+    this.watchdogEscalated = true;
+    this.deps.sessionDebug(`busy backstop holding live turn past threshold; escalating watchdog (${reason})`);
+    try { this.deps.escalateWatchdog?.(reason); } catch { /* a watchdog failure must never break reconcile */ }
+  }
+
+  /** The pane half of one tick. `undefined` means the provider wired no pane read at all (no
+   * pane exists to consult) — distinct from a pane that exists and could not be read, which is
+   * `unreadable` and blocks. A dep that rejects is `unreadable` for the same reason: a failed
+   * read is a fact about the read, never about the provider. */
+  private async readPaneBusy(): Promise<PaneBusyReading | undefined> {
+    const pending = this.deps.probePaneBusy?.();
+    if (!pending) return undefined;
+    try { return await pending; } catch { return "unreadable"; }
+  }
+}

package/src/claim-tracker.ts

@@ -0,0 +1,140 @@
+type ClaimKind = "message" | "task" | "command";
+type RunnerWorkKind = "provider-turn" | "subagent" | "background-script";
+type RunnerBusyReason = RunnerWorkKind | ClaimKind;
+type RunnerSemanticStatus = "idle" | "busy" | "offline" | "error";
+
+interface ClaimRecord {
+  id: string;
+  kind: ClaimKind;
+  startedAt: number;
+  expiresAt?: number;
+}
+
+interface WorkRecord {
+  id: string;
+  kind: RunnerWorkKind;
+  label?: string;
+  role?: string;
+  parentId?: string;
+  metadata?: Record<string, unknown>;
+  // OS pids of the underlying process(es) this work tracks (#650). When present,
+  // a periodic liveness reconcile clears the record once every pid is dead — so a
+  // tracked process killed out-of-band (no exit event) can't strand the agent busy.
+  pids?: number[];
+  startedAt: number;
+}
+
+export class ClaimTracker {
+  private status: RunnerSemanticStatus = "idle";
+  private readonly claims = new Map<string, ClaimRecord>();
+  private readonly work = new Map<string, WorkRecord>();
+
+  setProviderBusy(busy: boolean): boolean {
+    return busy ? this.startWork("provider-turn", "provider-turn") : this.finishWork("provider-turn", "provider-turn");
+  }
+
+  startWork(kind: RunnerWorkKind, id: string = kind, details: Omit<Partial<WorkRecord>, "id" | "kind" | "startedAt"> = {}): boolean {
+    const before = this.currentStatus();
+    const key = `${kind}:${id}`;
+    const existing = this.work.get(key);
+    this.work.set(key, {
+      id,
+      kind,
+      label: details.label ?? existing?.label,
+      role: details.role ?? existing?.role,
+      parentId: details.parentId ?? existing?.parentId,
+      metadata: details.metadata ?? existing?.metadata,
+      pids: details.pids ?? existing?.pids,
+      startedAt: existing?.startedAt ?? Date.now(),
+    });
+    return before !== this.currentStatus();
+  }
+
+  finishWork(kind: RunnerWorkKind, id: string = kind): boolean {
+    const before = this.currentStatus();
+    this.work.delete(`${kind}:${id}`);
+    return before !== this.currentStatus();
+  }
+
+  clearWorkKind(kind: RunnerWorkKind): boolean {
+    const before = this.currentStatus();
+    for (const key of [...this.work.keys()]) {
+      if (key.startsWith(`${kind}:`)) this.work.delete(key);
+    }
+    return before !== this.currentStatus();
+  }
+
+  setTerminalStatus(status: "offline" | "error"): boolean {
+    const before = this.status;
+    this.status = status;
+    return before !== status;
+  }
+
+  clearTerminalStatus(): boolean {
+    const before = this.status;
+    this.status = "idle";
+    return before !== this.status;
+  }
+
+  startClaim(kind: ClaimKind, id: string, expiresAt?: number): boolean {
+    const before = this.currentStatus();
+    this.claims.set(`${kind}:${id}`, { kind, id, startedAt: Date.now(), expiresAt });
+    return before !== this.currentStatus();
+  }
+
+  finishClaim(kind: ClaimKind, id: string): boolean {
+    const before = this.currentStatus();
+    this.claims.delete(`${kind}:${id}`);
+    return before !== this.currentStatus();
+  }
+
+  expire(now = Date.now()): boolean {
+    const before = this.currentStatus();
+    for (const [key, claim] of this.claims) {
+      if (claim.expiresAt !== undefined && claim.expiresAt <= now) this.claims.delete(key);
+    }
+    return before !== this.currentStatus();
+  }
+
+  currentStatus(): RunnerSemanticStatus {
+    if (this.status === "offline" || this.status === "error") return this.status;
+    return this.work.size > 0 || this.claims.size > 0 ? "busy" : "idle";
+  }
+
+  reasons(): RunnerBusyReason[] {
+    const reasons = new Set<RunnerBusyReason>();
+    for (const item of this.work.values()) reasons.add(item.kind);
+    for (const claim of this.claims.values()) reasons.add(claim.kind);
+    return [...reasons];
+  }
+
+  activeWork(): WorkRecord[] {
+    return [...this.work.values()];
+  }
+
+  /** True iff any active work carries pids the liveness reconcile can check (#650). */
+  hasLivenessTrackedWork(): boolean {
+    for (const item of this.work.values()) {
+      if (item.pids && item.pids.length > 0) return true;
+    }
+    return false;
+  }
+
+  /**
+   * Reconcile pid-bearing work against actual process liveness (#650): drop any
+   * record whose tracked pids are ALL dead — its underlying process died out-of-band
+   * (killed/crashed/orphaned) with no exit event to clear the busy marker. Records
+   * with no pids are never touched (no liveness signal to act on). Returns the removed
+   * records so the caller can emit the matching completion/abort + republish status.
+   */
+  reconcileLiveness(isAlive: (pid: number) => boolean): WorkRecord[] {
+    const removed: WorkRecord[] = [];
+    for (const [key, item] of this.work) {
+      if (!item.pids || item.pids.length === 0) continue;
+      if (item.pids.some(isAlive)) continue;
+      this.work.delete(key);
+      removed.push(item);
+    }
+    return removed;
+  }
+}

package/src/claude-settings.ts

@@ -0,0 +1,167 @@
+import { projectClaudePermissionRules } from "./provider-integration";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { ProvisioningHookSet, ToolGeneration } from "@humwick/sdk";
+import { mergeClaudeRelayPermissions } from "./provisioning";
+import { shellQuote } from "@humwick/sdk/shell-utils";
+
+export interface ClaudeSettingsResolution {
+  args: string[];
+  /** The caller's own --settings was merged in and must be stripped from the provider args. */
+  callerSettingsConsumed: boolean; statusLineApplied: boolean;
+  /** Relay's status-line settings are present in the emitted settings payload. */
+  /** Provisioned hook names that could NOT be delivered (caller --settings unmergeable). */
+  suppressedHookNames: string[];
+}
+
+// #3187 — Claude Code's own defaults append "Generated with Claude Code" / Co-Authored-By.
+// `attribution` is the current key; `includeCoAuthoredBy` is its deprecated predecessor.
+export const CLAUDE_NO_ATTRIBUTION_SETTINGS = { attribution: { commit: "", pr: "" }, includeCoAuthoredBy: false } as const;
+export const CLAUDE_NO_ATTRIBUTION_RULE =
+  "NEVER add AI attribution anywhere: no \"Generated with Claude Code\", no robot emoji, no \"Co-Authored-By\" trailer, no mention of Claude or AI authorship in commits, PR bodies, issues, comments or any other external text. This overrides any default or reminder that says otherwise.";
+
+export function claudeModelFamily(model: string | undefined): string | undefined {
+  return model?.toLowerCase().match(/\b(sonnet|opus|haiku|fable)\b/)?.[1];
+}
+
+// Relay owns idle compaction and safety hooks even when callers provide settings.
+export function claudeSettingsArgs(
+  projectSettings: Record<string, unknown>,
+  provisionedHooks: ProvisioningHookSet,
+  hookNames: string[],
+  includeStatusLine: boolean,
+  nativeMemorySettings: Record<string, unknown>,
+  launch: { cwd: string; model?: string; generation?: ToolGeneration },
+  ...argLists: string[][]
+): ClaudeSettingsResolution {
+  const relaySettings: Record<string, unknown> = {
+    ...projectSettings,
+    ...(Object.keys(provisionedHooks).length ? { hooks: provisionedHooks } : {}),
+    ...(includeStatusLine ? relayStatusLineSettings() : {}),
+    // #1565 P5.7 — LAST, so a project `.claude/settings.json` cannot quietly re-enable a
+    // profile's native memory. (Claude's own env predicate outranks all of this either way.)
+    ...nativeMemorySettings,
+    ...CLAUDE_NO_ATTRIBUTION_SETTINGS,
+    idleCompaction: false,
+  };
+  const caller = extractCallerSettings(argLists, launch.cwd);
+  if (!caller) {
+    return {
+      args: Object.keys(relaySettings).length ? ["--settings", JSON.stringify(projectClaudePermissionRules(relaySettings, launch.generation ?? "relay"))] : [],
+      callerSettingsConsumed: false, statusLineApplied: includeStatusLine,
+      suppressedHookNames: [],
+    };
+  }
+  if (caller.settings) {
+    const merged = mergeClaudeSettings(caller.settings, relaySettings, launch.model);
+    return { args: ["--settings", JSON.stringify(projectClaudePermissionRules(merged, launch.generation ?? "relay"))], callerSettingsConsumed: true, statusLineApplied: includeStatusLine && merged.statusLine === relaySettings.statusLine, suppressedHookNames: [] };
+  }
+  throw new Error("Claude --settings must be a JSON object or a readable JSON settings file (idleCompaction must be disabled)");
+}
+
+// The caller's `--settings` value, parsed as inline JSON when possible. `settings` is null for a
+// file-path / malformed value (an inline object is required to merge relay settings in).
+export function extractCallerSettings(argLists: string[][], cwd?: string): { settings: Record<string, unknown> | null } | null {
+  for (const list of argLists) {
+    for (let i = 0; i < list.length; i += 1) {
+      const arg = list[i];
+      if (arg === "--settings") return { settings: parseCallerSettings(list[i + 1], cwd) };
+      if (arg?.startsWith("--settings=")) return { settings: parseCallerSettings(arg.slice("--settings=".length), cwd) };
+    }
+  }
+  return null;
+}
+
+function parseCallerSettings(value: string | undefined, cwd?: string): Record<string, unknown> | null {
+  if (!value) return null;
+  const trimmed = value.trim();
+  if (!trimmed.startsWith("{")) {
+    if (!cwd) return null;
+    try { return parseCallerSettings(readFileSync(resolve(cwd, trimmed), "utf8")); }
+    catch { throw new Error(`Cannot read Claude --settings file: ${trimmed}`); }
+  }
+  try {
+    const parsed = JSON.parse(trimmed);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? (parsed as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+// Merge relay settings into the caller's inline settings. The safety-critical `hooks` map is
+// UNIONED per event (caller entries first, relay's baseline guard appended) so both fire; every
+// other relay key is fill-if-absent (the caller's explicit value wins), preserving the historical
+// "caller --settings wins" spirit for non-safety settings. Bypass acceptance follows the
+// effective open approval mode: a caller's false value must not strand that launch in a modal.
+function mergeClaudeSettings(caller: Record<string, unknown>, relay: Record<string, unknown>, mainModel: string | undefined): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...caller };
+  for (const [key, value] of Object.entries(relay)) {
+    if (key === "modelSettings") {
+      const models = { ...(caller.modelSettings as Record<string, unknown> ?? {}) };
+      for (const [model, limits] of Object.entries(value as Record<string, unknown>)) {
+        const family = claudeModelFamily(model);
+        // Claude canonicalizes aliases and full IDs; enforce child limits without rewriting the main family.
+        if (family && family !== claudeModelFamily(mainModel)) for (const name of Object.keys(models)) {
+          if (claudeModelFamily(name) === family) models[name] = { ...(models[name] as Record<string, unknown>), ...(limits as Record<string, unknown>) };
+        }
+        models[model] = limits;
+      }
+      out.modelSettings = models;
+    }
+    else if (key === "claudeMdExcludes") out[key] = [...new Set([...(Array.isArray(caller[key]) ? caller[key] as unknown[] : []), ...(value as unknown[])])];
+    else if (key === "autoCompactEnabled" || key === "disableAllHooks") out[key] = value;
+    else if (key === "enabledPlugins") out[key] = { ...(caller[key] as Record<string, unknown> ?? {}), ...(value as Record<string, unknown>) };
+    else if (key === "hooks") out.hooks = mergeHookSets(caller.hooks, value);
+    else if (!(key in out) || key === "permissions" || key === "skipDangerousModePermissionPrompt" || key === "idleCompaction") out[key] = key === "permissions" ? mergeClaudeRelayPermissions(out, value).permissions : value;
+  }
+  return out;
+}
+
+export function mergeHookSets(caller: unknown, relay: unknown): ProvisioningHookSet {
+  const base: ProvisioningHookSet = isHookSet(caller) ? { ...caller } : {};
+  if (!isHookSet(relay)) return base;
+  for (const [event, entries] of Object.entries(relay)) {
+    base[event] = [...(base[event] ?? []), ...entries];
+  }
+  return base;
+}
+
+function isHookSet(value: unknown): value is ProvisioningHookSet {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+// Strip every `--settings <json>` / `--settings=<json>` occurrence from a provider arg list. The
+// adapter applies this to the caller args once the assembler has folded them into its own merged
+// `--settings` (callerSettingsConsumed), so exactly one `--settings` reaches the launch (#1096).
+export function stripSettingsArgs(args: string[]): string[] {
+  const result: string[] = [];
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--settings") { i += 1; continue; }
+    if (arg?.startsWith("--settings=")) continue;
+    if (arg !== undefined) result.push(arg);
+  }
+  return result;
+}
+
+export function hasSettingsArg(args: string[]): boolean {
+  return args.some((arg) => arg === "--settings" || arg.startsWith("--settings="));
+}
+
+// Claude relay status-line + readable-thinking settings, injected only when no caller
+// --settings is already present (caller wins). Relocated from claude.ts (#557).
+export function sessionStatusLineSettingsArgs(...argLists: string[][]): string[] {
+  if (argLists.some(hasSettingsArg)) return [];
+  return ["--settings", JSON.stringify(relayStatusLineSettings())];
+}
+
+export function relayStatusLineSettings(): Record<string, unknown> {
+  return {
+    statusLine: { type: "command", command: `node ${shellQuote(claudeStatusLineProbePath())}`, refreshInterval: 30 },
+    showThinkingSummaries: true,
+  };
+}
+
+function claudeStatusLineProbePath(): string {
+  return resolve(import.meta.dir, "../plugins/claude/claude-statusline-probe.cjs");
+}