@humwick/runner 0.0.0-stage → 0.130.0

package/src/mid-turn-delivery.ts

@@ -0,0 +1,43 @@
+// #2539 Phase A — the shared soft-steer foundation.
+//
+// One adapter-owned eligibility decision (`partitionMidTurnDelivery`), one config seam
+// (`resolveActiveTurnMessageDelivery`) and one acceptance-correlation id (`midTurnClientUserId`),
+// shared by every adapter that owns an additive mid-turn steer channel (codex `turn/steer` today;
+// opencode/zai build on this in Phase B). Kept in a neutral module so adapters never couple to
+// each other and runner-core never couples to a specific provider.
+import { isRecord, type Message } from "@humwick/sdk";
+import { taskIdFromMessage } from "./runner-helpers";
+
+export { resolveActiveTurnMessageDelivery } from "./delivery-policy";
+
+/** Keep synthetic context inputs and claimed work on their own turn boundary. */
+export function partitionMidTurnDelivery(messages: Message[]): { steerable: Message[]; boundaryOnly: Message[] } {
+  const steerable: Message[] = [];
+  const boundaryOnly: Message[] = [];
+  for (const message of messages) {
+    if (isSteerableMidTurnMessage(message)) steerable.push(message);
+    else boundaryOnly.push(message);
+  }
+  return { steerable, boundaryOnly };
+}
+
+function isSteerableMidTurnMessage(message: Message): boolean {
+  // Synthetic boundary payloads: memory / self-resume / context injections carry id 0.
+  if (message.id === 0) return false;
+  const payload = isRecord(message.payload) ? message.payload : undefined;
+  if (payload?.memoryInjection === true || payload?.resumeInjection === true) return false;
+  // Claimable messages / task assignments keep their claim window semantics.
+  if (message.claimable === true || taskIdFromMessage(message) !== undefined) return false;
+  return true;
+}
+
+/**
+ * Stable acceptance-correlation id for one steered composition (#2539 design C). Derived from
+ * the ordered batch ids, so a re-offer of the SAME subset reuses the id: the app-server echoes
+ * it back as the `userMessage.clientId` item field, and an echo observed after a lost steer
+ * response lets the next offer settle by correlation instead of re-steering (which would
+ * duplicate). Correlation, NOT idempotent dedupe — the upstream may accept the same id twice.
+ */
+export function midTurnClientUserId(messages: Message[]): string {
+  return `relay-steer-${messages.map((message) => message.id).join(",")}`;
+}

package/src/native-memory-lever.ts

@@ -0,0 +1,329 @@
+import { writeChildEnv } from "@humwick/sdk/env";
+// #1565 P5.7 (design §10.3) — the provider-NATIVE-memory lever.
+//
+// WHAT THIS IS FOR. Every agent today can carry two competing memory stores: relay memory (which
+// survives a respawn) and the provider's own (which, for 8 of 11 built-in profiles, is destroyed
+// at every spawn because the managed provider home is instanceId-keyed). This module renders one
+// profile field into the concrete per-provider switches that make relay memory THE store.
+//
+// TWO INVARIANTS, both load-bearing:
+//
+//  1. ABSENT ⇒ OFF for Relay-spawned Claude. A profile without `nativeMemory` explicitly emits
+//     `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1` and `autoMemoryEnabled:false`, so provider auto-memory
+//     cannot inject its own instructions into Relay-managed Claude sessions. Other providers keep
+//     their existing absent-policy behavior until they have an explicit global default.
+//
+//  2. A DECLARED policy renders EXPLICITLY IN BOTH DIRECTIONS — never as "omit the flag"
+//     (§10.3.5). `policy:"on"` emits `CLAUDE_CODE_DISABLE_AUTO_MEMORY=0` / `-c
+//     features.memories=true`, not an absence. An absence cannot override an `autoMemoryEnabled:
+//     false` or `features.memories = false` written into a reused managed home on an earlier
+//     launch, so a K3 kill-switch pull would be silently defeated. An explicit value cannot be.
+//
+// REACH, per §10.3.1's table — and the reason the env/argv lever is the one that must always be
+// present: relay writes a managed `settings.json`/`config.toml` only into an ISOLATED home, and
+// must never clobber a host-base agent's real `~/.claude`/`~/.codex`. Claude's env var sits ABOVE
+// the settings read in the CLI's own predicate and Codex's `-c` sits above `config.toml`, so the
+// portable lever is also the authoritative one; the file channels are a belt, not the trousers.
+//
+// NEVER THROWS. Resolution is total: any unexpected input degrades to "nothing applied, reported
+// as suppressed" rather than propagating. A failure to apply this lever must not fail a spawn
+// (the #1612 discipline, applied to the switch instead of the preamble) — an agent that launches
+// with its native memory still on is a two-store agent, which is exactly today's state; an agent
+// that fails to launch is an outage.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { AgentProfileNativeMemoryPolicy, SpawnProvider } from "@humwick/sdk";
+import { sanitizeFsName } from "@humwick/sdk/fs-name";
+import type { RunnerSpawnConfig } from "./adapter";
+import { providerHomeRootFromEnv } from "./config";
+import { hostProviderDefaultArgs } from "./host-asset-plan";
+import { upsertTomlTable } from "./relay-mcp";
+
+export const CLAUDE_DISABLE_AUTO_MEMORY_ENV = "CLAUDE_CODE_DISABLE_AUTO_MEMORY";
+export const CLAUDE_AUTO_MEMORY_ENABLED_SETTING = "autoMemoryEnabled";
+export const CLAUDE_AUTO_MEMORY_DIRECTORY_SETTING = "autoMemoryDirectory";
+export const CODEX_MEMORIES_FEATURE_KEY = "features.memories";
+
+/** `"default"` = no effective policy applies, so no lever is emitted. */
+export type ResolvedNativeMemoryPolicy = AgentProfileNativeMemoryPolicy | "default";
+
+export interface NativeMemoryLever {
+  policy: ResolvedNativeMemoryPolicy;
+  /** Env additions for the launch. Empty when no effective policy applies. */
+  env: Record<string, string>;
+  /** Argv additions for the launch. Empty for `"default"`. */
+  args: string[];
+  /** Provider-settings keys relay folds into its OWN settings channel (Claude `--settings` and,
+   *  for an isolated home, the managed `settings.json`). Empty when no effective policy applies
+   *  and for Codex. */
+  settings: Record<string, unknown>;
+  /** Codex only: `config.toml` keys for an ISOLATED `CODEX_HOME`. Empty otherwise. */
+  configToml: Record<string, string>;
+  /** The levers that actually reach this launch, as short stable ids for the projection report. */
+  applied: string[];
+  /** Levers that were resolved but could NOT be delivered on this base/provider. Reported LOUDLY
+   *  (the `hooksSuppressed` precedent, #1096) so a lever is never silently absent while the
+   *  report claims it applied. */
+  suppressed?: { reason: string; levers: string[] };
+}
+
+const NONE: NativeMemoryLever = { policy: "default", env: {}, args: [], settings: {}, configToml: {}, applied: [] };
+
+function none(): NativeMemoryLever {
+  return { ...NONE, env: {}, args: [], settings: {}, configToml: {}, applied: [] };
+}
+
+/**
+ * A STABLE, relay-owned, per-profile directory for `policy:"redirect"` (§10.3.4/F3). Deliberately
+ * NOT under the instanceId-keyed provider home: the entire point of the redirect is that a
+ * host-base profile's native store stops being destroyed every spawn and becomes durable and
+ * harvestable. Sibling to the per-instance homes, so one profile's native memory is one directory.
+ */
+export function defaultNativeMemoryDirectory(provider: SpawnProvider, config: RunnerSpawnConfig): string {
+  const profileName = sanitizeFsName(config.agentProfile?.name || config.profile || "profile", {
+    replacement: "-",
+    collapse: false,
+    maxLen: 120,
+    fallback: "profile",
+  });
+  return join(providerHomeRootFromEnv(), provider, profileName, "native-memory");
+}
+
+interface ClaudeDeliveryChannels {
+  /** An isolated managed home exists, so relay owns a `settings.json` it may write. */
+  managedSettings: boolean;
+  /** Relay's inline `--settings` reaches this launch (false when a caller `--settings` is a file
+   *  path or malformed JSON and therefore unmergeable — the same gate `claudeSettingsArgs` uses). */
+  inlineSettings: boolean;
+}
+
+function resolveClaudeLever(
+  policy: AgentProfileNativeMemoryPolicy,
+  directory: string | undefined,
+  channels: ClaudeDeliveryChannels,
+  resolveDefaultDirectory: () => string,
+): NativeMemoryLever {
+  // The env var is unconditional and authoritative — it works on EVERY base, host included, and
+  // outranks the settings read inside the CLI's own predicate.
+  const disable = policy === "off";
+  const env = writeChildEnv({}, { [CLAUDE_DISABLE_AUTO_MEMORY_ENV]: disable ? "1" : "0" });
+  const applied = [`env:${CLAUDE_DISABLE_AUTO_MEMORY_ENV}=${disable ? "1" : "0"}`];
+
+  const settings: Record<string, unknown> = { [CLAUDE_AUTO_MEMORY_ENABLED_SETTING]: !disable };
+  if (policy === "redirect") settings[CLAUDE_AUTO_MEMORY_DIRECTORY_SETTING] = directory ?? resolveDefaultDirectory();
+
+  const settingsLevers = Object.keys(settings).map((key) => `settings:${key}`);
+  const settingsReach = channels.managedSettings || channels.inlineSettings;
+  if (settingsReach) {
+    applied.push(...settingsLevers);
+    return { policy, env, args: [], settings, configToml: {}, applied };
+  }
+  // No settings channel: the env var still carries the on/off decision (and outranks settings
+  // anyway), so "off"/"on" lose nothing. A REDIRECT does lose something real — native memory
+  // stays on but writes wherever the provider defaults to — so say so instead of implying the
+  // redirect happened.
+  return {
+    policy,
+    env,
+    args: [],
+    settings: {},
+    configToml: {},
+    applied,
+    suppressed: {
+      reason: policy === "redirect"
+        ? `relay has no settings channel for this launch (no isolated managed home, and the caller's --settings could not be merged), so ${CLAUDE_AUTO_MEMORY_DIRECTORY_SETTING} was NOT applied: native memory stays ON at the provider's default location`
+        : `relay has no settings channel for this launch (no isolated managed home, and the caller's --settings could not be merged), so the ${CLAUDE_AUTO_MEMORY_ENABLED_SETTING} belt was not applied; the ${CLAUDE_DISABLE_AUTO_MEMORY_ENV} env lever still applies and outranks settings`,
+      levers: settingsLevers,
+    },
+  };
+}
+
+function resolveCodexLever(policy: AgentProfileNativeMemoryPolicy, isolatedHome: boolean): NativeMemoryLever {
+  // §10.3.4: Codex memories live in a fixed `CODEX_HOME` sqlite with no redirect knob, so
+  // `redirect` degrades to an EXPLICIT "on" — never to "off". Losing a redirect must not be a
+  // path that silently deletes a store.
+  const enable = policy !== "off";
+  const value = enable ? "true" : "false";
+  const args = ["-c", `${CODEX_MEMORIES_FEATURE_KEY}=${value}`];
+  const applied = [`arg:${CODEX_MEMORIES_FEATURE_KEY}=${value}`];
+  const configToml: Record<string, string> = isolatedHome ? { [CODEX_MEMORIES_FEATURE_KEY]: value } : {};
+  if (isolatedHome) applied.push(`config.toml:${CODEX_MEMORIES_FEATURE_KEY}=${value}`);
+
+  const suppressedLevers: string[] = [];
+  const reasons: string[] = [];
+  if (policy === "redirect") {
+    suppressedLevers.push("redirect");
+    reasons.push("Codex has no autoMemoryDirectory equivalent (memories live in a fixed CODEX_HOME sqlite), so the redirect could not be applied; native memory was left EXPLICITLY ON instead");
+  }
+  if (!isolatedHome) {
+    suppressedLevers.push(`config.toml:${CODEX_MEMORIES_FEATURE_KEY}`);
+    reasons.push(`this host-base launch reuses the real ~/.codex, which relay must not write, so the config.toml belt was not applied; the ${CODEX_MEMORIES_FEATURE_KEY} argv lever still applies and outranks config.toml`);
+  }
+  return {
+    policy,
+    env: {},
+    args,
+    settings: {},
+    configToml,
+    applied,
+    ...(suppressedLevers.length ? { suppressed: { reason: reasons.join("; "), levers: suppressedLevers } } : {}),
+  };
+}
+
+// Per-provider lever renderers, dispatched by NAME rather than by an identity branch — the same
+// registry shape `launch-assembly`'s ASSEMBLERS/MATERIALIZERS use, so adding a provider is a table
+// entry (and an unregistered provider degrades to "no lever, reported", never to a throw).
+type NativeMemoryLeverRenderer = (
+  policy: AgentProfileNativeMemoryPolicy,
+  input: ResolveNativeMemoryLeverInput,
+) => NativeMemoryLever;
+
+// #2513 — the claude renderer is shared by every claude-family provider id (claude-b reuses
+// the claude adapter/launch path whole), so the absent⇒off invariant holds for it too.
+const claudeLeverRenderer: NativeMemoryLeverRenderer = (policy, input) => resolveClaudeLever(
+  policy,
+  input.config.agentProfile?.nativeMemory?.directory,
+  { managedSettings: Boolean(input.channels?.managedSettings), inlineSettings: Boolean(input.channels?.inlineSettings) },
+  () => defaultNativeMemoryDirectory(input.provider, input.config),
+);
+
+const LEVER_RENDERERS: Record<string, NativeMemoryLeverRenderer> = {
+  claude: claudeLeverRenderer,
+  "claude-b": claudeLeverRenderer,
+  "claude-api": claudeLeverRenderer,
+  codex: (policy, input) => resolveCodexLever(policy, Boolean(input.isolatedHome)),
+};
+
+// Global defaults belong beside the renderer registry so adding a provider does not create an
+// identity branch in the resolver. Profile declarations still take precedence over this table.
+const PROVIDER_DEFAULT_POLICIES: Partial<Record<SpawnProvider, AgentProfileNativeMemoryPolicy>> = {
+  claude: "off",
+  "claude-b": "off",
+  "claude-api": "off",
+};
+
+export interface ResolveNativeMemoryLeverInput {
+  provider: SpawnProvider;
+  config: RunnerSpawnConfig;
+  /** Claude only — see {@link ClaudeDeliveryChannels}. Ignored for Codex. */
+  channels?: Partial<ClaudeDeliveryChannels>;
+  /** Codex only — true when this launch has an isolated `CODEX_HOME` relay may write. */
+  isolatedHome?: boolean;
+}
+
+/**
+ * Render the profile's `nativeMemory` field into concrete launch levers. Total: absent profiles
+ * resolve to the runner-level Claude default (`"off"`); providers without such a default return
+ * the empty application (policy `"default"`). Any unexpected failure becomes a reported
+ * suppression rather than a throw.
+ */
+export function resolveNativeMemoryLever(input: ResolveNativeMemoryLeverInput): NativeMemoryLever {
+  try {
+    const declared = input.config.agentProfile?.nativeMemory;
+    const declaredPolicy = declared?.policy ?? (declared?.directory ? "redirect" : undefined);
+    const policy = declaredPolicy ?? PROVIDER_DEFAULT_POLICIES[input.provider];
+    if (!policy) return none();
+    if (policy !== "on" && policy !== "off" && policy !== "redirect") {
+      return {
+        ...none(),
+        suppressed: { reason: `unrecognized nativeMemory.policy ${JSON.stringify(policy)}; no lever was applied and the provider default (native memory ON) stands`, levers: ["nativeMemory"] },
+      };
+    }
+    const render = LEVER_RENDERERS[input.provider];
+    if (render) return render(policy, input);
+    return {
+      ...none(),
+      policy,
+      suppressed: { reason: `provider ${input.provider} has no known native-memory lever; nothing was applied`, levers: ["nativeMemory"] },
+    };
+  } catch (err) {
+    // The fail-safe (#1612's discipline applied to the switch). A lever we could not compute must
+    // degrade to "not applied, loudly reported" — never to a failed spawn.
+    return {
+      ...none(),
+      suppressed: { reason: `native-memory lever could not be resolved: ${(err as Error)?.message ?? String(err)}; no lever was applied and the provider default (native memory ON) stands`, levers: ["nativeMemory"] },
+    };
+  }
+}
+
+// ── Launch-seam adapters ───────────────────────────────────────────────────────
+//
+// The two entry points `launch-assembly` calls, kept here so the lever's whole surface — what it
+// emits, where each half is delivered, and what happens when a delivery fails — reads as one file.
+
+/**
+ * Resolve the Claude lever with its REAL delivery channels. The `inlineSettings` reach uses the
+ * same caller-`--settings` mergeability gate `claudeSettingsArgs` applies, so the lever's
+ * applied/suppressed report cannot claim a settings key the merge then drops. Both `assembleClaude`
+ * (for the launch) and `materializeClaudeAssets` (for the managed settings.json) call this, so the
+ * launch and the disk agree — the `claudeManagedHookSettings` pattern.
+ */
+export function resolveClaudeNativeMemoryLever(
+  config: RunnerSpawnConfig,
+  configHome: string | undefined,
+  hostDefaultArgs: string[],
+  callerSettingsMergeable: (argLists: string[][]) => boolean,
+  provider: SpawnProvider = "claude",
+): NativeMemoryLever {
+  return resolveNativeMemoryLever({
+    provider,
+    config,
+    channels: {
+      managedSettings: Boolean(configHome),
+      inlineSettings: callerSettingsMergeable([hostDefaultArgs, config.providerArgs]),
+    },
+  });
+}
+
+/**
+ * The native-memory keys `materializeClaudeAssets` writes into an ISOLATED managed home's
+ * settings.json. Returns `{}` for host base (which reuses the real `~/.claude` — relay must not
+ * write it); that base is covered by the env lever plus the inline `--settings`.
+ */
+export function claudeManagedNativeMemorySettings(
+  config: RunnerSpawnConfig,
+  configHome: string | undefined,
+  callerSettingsMergeable: (argLists: string[][]) => boolean,
+  provider: SpawnProvider = "claude",
+): Record<string, unknown> {
+  if (!configHome) return {};
+  const hostDefaultArgs = hostProviderDefaultArgs(config);
+  return resolveClaudeNativeMemoryLever(config, configHome, hostDefaultArgs, callerSettingsMergeable, provider).settings;
+}
+
+/**
+ * The fail-safe at the APPLY seam (#1612's discipline, moved from the preamble to the switch). The
+ * file-channel belt is best-effort by construction: the authoritative lever is the env var / `-c`
+ * arg, computed into the launch and touching no disk, so a failed belt write costs nothing an
+ * operator can observe — while a THROW here would fail the whole spawn. So: never propagate, and
+ * never swallow either. Returns the reason on failure (also logged), `undefined` on success.
+ */
+export function applyNativeMemoryBelt(label: string, apply: () => void): string | undefined {
+  try {
+    apply();
+    return undefined;
+  } catch (err) {
+    const reason = `native-memory lever: ${label} could not be written: ${(err as Error)?.message ?? String(err)}. `
+      + "The authoritative env/argv lever still applies (it outranks the file channel), and the spawn continues — design #1565 §10.3.";
+    console.warn(reason);
+    return reason;
+  }
+}
+
+/**
+ * Idempotently upsert the `[features]` table into an ISOLATED `CODEX_HOME/config.toml`. Values are
+ * already rendered TOML literals (`"true"`/`"false"`) and are emitted BARE, not quoted:
+ * `features.memories` is a boolean, and a quoted string would not parse as one.
+ */
+export function writeCodexFeaturesToml(codexHome: string, features: Record<string, string>): void {
+  const bodyLines = Object.entries(features)
+    .map(([key, value]) => [key.startsWith("features.") ? key.slice("features.".length) : key, value] as const)
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([key, value]) => `${key} = ${value}`);
+  if (!bodyLines.length) return;
+  mkdirSync(codexHome, { recursive: true });
+  const configPath = join(codexHome, "config.toml");
+  const existing = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
+  writeFileSync(configPath, upsertTomlTable(existing, "features", bodyLines), { mode: 0o600 });
+}

package/src/native-self-resume.ts

@@ -0,0 +1,244 @@
+import { compactExecutionBudgetMs, errMessage, isRecord } from "@humwick/sdk";
+import type { ProviderStatusEvent, SemanticStatus } from "./adapter";
+
+interface RunnerTimelineEvent {
+  status: string;
+  id?: string;
+  timestamp: number;
+  title?: string;
+  body?: string;
+  icon?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface NativeSelfResumeHandoff {
+  commandId: string;
+  generation?: number;
+  compactedAt?: number;
+  submittedAt?: number;
+  abort: AbortController;
+  timer: ReturnType<typeof setTimeout>;
+  resolve: (result: Record<string, unknown>) => void;
+  reject: (error: Error) => void;
+  promise: Promise<Record<string, unknown>>;
+}
+
+export function isNativeSelfResumeCompact(type: string, params: Record<string, unknown>): boolean {
+  if (type !== "agent.compact") return false;
+  const selfResume = params.selfResume;
+  return Boolean(selfResume && typeof selfResume === "object" && !Array.isArray(selfResume) && (selfResume as Record<string, unknown>).mode === "native");
+}
+
+export class NativeSelfResumeTracker {
+  private current?: NativeSelfResumeHandoff;
+
+  get active(): NativeSelfResumeHandoff | undefined {
+    return this.current;
+  }
+
+  begin(commandId: string, params: Record<string, unknown>): NativeSelfResumeHandoff {
+    if (this.current) this.reject(this.current, new Error("native compact superseded"));
+    let resolve!: (result: Record<string, unknown>) => void;
+    let reject!: (error: Error) => void;
+    const promise = new Promise<Record<string, unknown>>((res, rej) => {
+      resolve = res;
+      reject = rej;
+    });
+    const selfResume = params.selfResume && typeof params.selfResume === "object" && !Array.isArray(params.selfResume)
+      ? params.selfResume as Record<string, unknown>
+      : undefined;
+    const generation = typeof selfResume?.generation === "number" ? selfResume.generation : undefined;
+    void promise.catch(() => {});
+    const timeoutMs = compactExecutionBudgetMs(params);
+    const abort = new AbortController();
+    const handoff: NativeSelfResumeHandoff = {
+      commandId,
+      abort,
+      generation,
+      promise,
+      resolve,
+      reject,
+      timer: setTimeout(() => {
+        if (this.current !== handoff) return;
+        this.reject(handoff, new Error(`native self-resume timed out after ${Math.round(timeoutMs / 1000)}s`));
+      }, timeoutMs),
+    };
+    this.current = handoff;
+    return handoff;
+  }
+
+  finish(handoff?: NativeSelfResumeHandoff): void {
+    if (!handoff) return;
+    clearTimeout(handoff.timer);
+    if (this.current === handoff) this.current = undefined;
+  }
+
+  resolve(handoff: NativeSelfResumeHandoff, result: Record<string, unknown>): void {
+    this.finish(handoff);
+    handoff.resolve(result);
+  }
+
+  reject(handoff: NativeSelfResumeHandoff, error: Error): void {
+    this.finish(handoff);
+    handoff.abort.abort(error);
+    handoff.reject(error);
+  }
+
+  async run<T>(handoff: NativeSelfResumeHandoff | undefined, operation: () => Promise<T>): Promise<T> {
+    if (!handoff) return operation();
+    handoff.abort.signal.throwIfAborted();
+    const result = await Promise.race([operation(), handoff.promise.then(() => new Promise<T>(() => {}))]);
+    handoff.abort.signal.throwIfAborted();
+    return result;
+  }
+
+  checkAcknowledgement(ack: unknown, status: string): void {
+    if (!isRecord(ack) || !isRecord(ack.command)) return;
+    this.settleCommand(ack.command);
+    if ((status === "accepted" || status === "running") && ["canceled", "timed_out", "failed", "rejected", "succeeded"].includes(String(ack.command.status))) throw new Error(`command already ${ack.command.status}`);
+  }
+
+  settleCommand(command: Record<string, unknown>): void {
+    if (command.id !== this.current?.commandId) return;
+    if (["canceled", "timed_out", "failed", "rejected"].includes(String(command.status))) {
+      this.reject(this.current!, new Error(`compact command ${command.status}: ${command.error ?? "server settlement"}`));
+    }
+  }
+
+  async reconcile(fetchCommand: (id: string) => Promise<Response>): Promise<void> {
+    const handoff = this.current;
+    if (!handoff) return;
+    const response = await fetchCommand(handoff.commandId);
+    if (!response.ok) throw new Error(`compact settlement lookup failed: ${response.status}`);
+    const command: unknown = await response.json();
+    if (isRecord(command)) this.settleCommand(command);
+  }
+
+  notePrompt(prompt: string, timestamp = Date.now()): void {
+    const active = this.current;
+    if (!active || active.submittedAt === undefined || timestamp < active.submittedAt) return;
+    if (/^(?:<pasted_content[^>]*>\s*)?\/compact(?:\s|$)/.test(prompt.trim())) {
+      this.reject(active, new Error("compact was submitted as a user prompt; boundary did not apply"));
+    }
+  }
+
+  noteCompacted(timestamp: number = Date.now()): void {
+    if (!this.current || this.current.submittedAt === undefined || timestamp < this.current.submittedAt) return;
+    this.current.compactedAt = timestamp;
+  }
+}
+
+interface NativeSelfResumeRecoveryOptions {
+  handoff: NativeSelfResumeHandoff;
+  tracker: NativeSelfResumeTracker;
+  providerSessionId: string;
+  status: SemanticStatus;
+  diagnostics: Record<string, unknown>;
+  now: number;
+  publishTimeline(event: RunnerTimelineEvent): void;
+  setTerminalProviderExit(marker: Record<string, unknown>): void;
+  setProviderStatus(update: ProviderStatusEvent): void;
+  restartProvider(resumeId?: string): Promise<void>;
+  publishStatus(): void;
+  scheduleDrain(): void;
+}
+
+export async function recoverNativeSelfResumeExit(opts: NativeSelfResumeRecoveryOptions): Promise<void> {
+  const resumeId = typeof opts.diagnostics.claudeResumeId === "string" && opts.diagnostics.claudeResumeId.length > 0
+    ? opts.diagnostics.claudeResumeId
+    : undefined;
+  if (opts.handoff.compactedAt && resumeId) {
+    await recoverWithClaudeResume(opts, resumeId);
+    return;
+  }
+  await recoverWithFreshLaunch(opts, resumeId);
+}
+
+async function recoverWithClaudeResume(opts: NativeSelfResumeRecoveryOptions, resumeId: string): Promise<void> {
+  opts.publishTimeline({
+    status: "provider.restart_decision",
+    id: `provider-self-resume-relaunch-${opts.providerSessionId}-${opts.now}`,
+    timestamp: Date.now(),
+    title: "Self-resume relaunching",
+    body: `Claude exited during native self-resume; runner is relaunching with claude --resume ${resumeId}.`,
+    icon: "ti-refresh",
+    metadata: selfResumeMetadata(opts.handoff, opts.diagnostics, {
+      decision: "resume-native-self-resume",
+      reason: "self-resume-exit-after-compact",
+      claudeResumeId: resumeId,
+      compactedAt: opts.handoff.compactedAt,
+    }),
+  });
+  try {
+    await opts.restartProvider(resumeId);
+    opts.publishStatus();
+    opts.scheduleDrain();
+    opts.tracker.resolve(opts.handoff, { recovered: true, via: "claude-resume", claudeResumeId: resumeId });
+  } catch (error) {
+    const message = errMessage(error);
+    opts.setTerminalProviderExit(selfResumeMetadata(opts.handoff, opts.diagnostics, {
+      reason: "self-resume-relaunch-failed",
+      claudeResumeId: resumeId,
+      compactedAt: opts.handoff.compactedAt,
+      lastError: message,
+    }));
+    opts.setProviderStatus({
+      status: "offline",
+      reason: "provider-turn",
+      id: `provider-self-resume-relaunch-failed-${opts.providerSessionId}`,
+      clear: ["provider-turn", "subagent", "background-script"],
+    });
+    opts.tracker.reject(opts.handoff, new Error(`self-resume relaunch failed: ${message}`));
+  }
+}
+
+async function recoverWithFreshLaunch(opts: NativeSelfResumeRecoveryOptions, resumeId?: string): Promise<void> {
+  opts.publishTimeline({
+    status: "provider.restart_decision",
+    id: `provider-self-resume-fresh-launch-${opts.providerSessionId}-${opts.now}`,
+    timestamp: Date.now(),
+    title: "Self-resume fresh-launching",
+    body: "Claude exited during native self-resume before a compacted marker; runner is fresh-launching so Relay can inject the persisted continuation.",
+    icon: "ti-refresh",
+    metadata: selfResumeMetadata(opts.handoff, opts.diagnostics, {
+      decision: "fresh-launch-native-self-resume",
+      reason: "self-resume-exit-before-compact",
+      ...(resumeId ? { claudeResumeId: resumeId } : {}),
+    }),
+  });
+  try {
+    await opts.restartProvider();
+    opts.publishStatus();
+    opts.scheduleDrain();
+    opts.tracker.resolve(opts.handoff, {
+      recovered: true,
+      via: "fresh-launch",
+      ...(resumeId ? { claudeResumeId: resumeId } : {}),
+    });
+  } catch (error) {
+    const message = errMessage(error);
+    opts.setTerminalProviderExit(selfResumeMetadata(opts.handoff, opts.diagnostics, {
+      reason: "self-resume-fresh-launch-failed",
+      ...(resumeId ? { claudeResumeId: resumeId } : {}),
+      lastError: message,
+    }));
+    opts.setProviderStatus({
+      status: "offline",
+      reason: "provider-turn",
+      id: `provider-self-resume-fresh-launch-failed-${opts.providerSessionId}`,
+      clear: ["provider-turn", "subagent", "background-script"],
+    });
+    opts.tracker.reject(opts.handoff, new Error(`self-resume fresh launch failed: ${message}`));
+  }
+}
+
+function selfResumeMetadata(handoff: NativeSelfResumeHandoff, diagnostics: Record<string, unknown>, extra: Record<string, unknown>): Record<string, unknown> {
+  return {
+    eventType: "provider.restart_decision",
+    selfResume: true,
+    selfResumeCommandId: handoff.commandId,
+    selfResumeGeneration: handoff.generation ?? null,
+    ...extra,
+    ...diagnostics,
+  };
+}