@humwick/runner 0.0.0-stage → 0.130.1

package/src/adapters/tool-summary.ts

@@ -0,0 +1,214 @@
+/**
+ * Provider-neutral safe-summary + secret redaction for the one-line tool-activity row.
+ *
+ * Claude (`summarizeToolUse`), Codex (`codexToolSummary`) and OpenCode (`opencode-tool-events`)
+ * all render the SAME discreet activity row (TraceView `ToolCallRow`), and each had — or would
+ * have added — its own copy of "collapse whitespace → clip to ~200 chars". That is the exact
+ * duplicate-helper class this repo's DRY ratchet guards against, and neither existing copy
+ * redacted secrets. This is the single home: one-line, redact, clip. Adapters keep only their
+ * own field/category mapping and call in here for the safe text.
+ */
+
+import { isAbsolute, resolve } from "node:path";
+import { isRecord, stringValue } from "@humwick/sdk";
+
+/** The shared activity-row budget. A summary LONGER than this is clipped to 197 chars + a
+ *  one-char ellipsis — byte-identical to the pre-existing Claude/Codex clip (`length > 200`), so an
+ *  existing 199/200-char summary stays unchanged and no row shifts. */
+const SUMMARY_MAX_CHARS = 200;
+const SUMMARY_CLIP_CHARS = 197;
+
+/**
+ * Candidate arg fields, in priority order, that carry a human-meaningful one-line summary of a
+ * tool call across providers. Covers Claude's snake_case input keys and the camelCase variants
+ * OpenCode's built-in tools use (`filePath`), so one list serves every adapter.
+ */
+const SUMMARY_CANDIDATE_KEYS = [
+  "command",
+  "file_path",
+  "filePath",
+  "path",
+  "pattern",
+  "query",
+  "url",
+  "description",
+  "prompt",
+] as const;
+
+/** Collapse all whitespace runs to single spaces and trim. Non-strings become "". */
+export function oneLineText(value: unknown): string {
+  return typeof value === "string" ? value.replace(/\s+/g, " ").trim() : "";
+}
+
+/**
+ * Best-effort redaction of credential-shaped substrings before a tool's command/args land durably
+ * in the chat mirror / a report-up. This is NOT a proof that no secret can ever leak — a one-line
+ * free-text summary of arbitrary tool input cannot make that guarantee — so it layers three
+ * conservative, structural nets and errs toward over-redaction (a real secret surfacing is always
+ * the worse outcome, #2354):
+ *   1. positional shapes — URL basic-auth, `Authorization: Bearer/Basic …`;
+ *   2. known provider key prefixes — OpenRouter/Anthropic/OpenAI `sk-…`, GitHub `gh?_`, Slack
+ *      `xox…`, AWS `AKIA…`;
+ *   3. labelled assignments — any KEY/TOKEN/SECRET/PASSWORD/CREDENTIAL-ish name (bare `KEY=` too),
+ *      with a quoted value (whitespace/newlines allowed inside quotes) or a bare value;
+ *   4. dotted base64url tokens — a JWT (header-anchored: any `eyJ…`-led dotted run, redacted whole)
+ *      or a high-entropy `id.secret` pair, which the single-run backstop below can't see because a
+ *      `.` is not a legal token terminator;
+ *   5. unlabelled high-entropy tokens — a long mixed upper/lower/digit run, or a base64 run, that
+ *      isn't a plain lowercase-hex hash/UUID.
+ * Ordinary paths, lowercase-hex SHAs, UUIDs, and version strings are deliberately left readable.
+ */
+// A name is "sensitive" when it contains one of these words (so bare `KEY`, `API_KEY`, `authToken`,
+// `db_password` all match). `auth` is intentionally absent — `Authorization:` is handled by the
+// bearer/basic rule, and `auth_token`/`authToken` already match via `token`.
+const SENSITIVE_NAME = "(?:key|token|secret|password|passwd|passphrase|credential)";
+
+export function redactSecrets(text: string): string {
+  if (!text) return text;
+  let out = text;
+  // 1a. URL basic-auth: scheme://user:password@host → scheme://[redacted]@host
+  out = out.replace(/([a-z][a-z0-9+.-]*:\/\/)[^\s/:@]+:[^\s/@]+@/gi, "$1[redacted]@");
+  // 1b. Authorization headers / bearer + basic tokens.
+  out = out.replace(/\b(bearer|basic)\s+[A-Za-z0-9._~+/=-]{8,}/gi, "$1 [redacted]");
+  // 2. Known provider key prefixes.
+  out = out.replace(/\bsk-(?:or|ant|proj|live|test)-[A-Za-z0-9_-]{8,}/gi, "[redacted-key]");
+  out = out.replace(/\bsk-[A-Za-z0-9]{16,}/g, "[redacted-key]");
+  out = out.replace(/\bgh[pousr]_[A-Za-z0-9]{16,}/g, "[redacted-key]");
+  out = out.replace(/\bxox[baprs]-[A-Za-z0-9-]{10,}/gi, "[redacted-key]");
+  out = out.replace(/\bAKIA[0-9A-Z]{12,}/g, "[redacted-key]");
+  // 3a. Labelled assignment with a QUOTED value — whitespace/newlines allowed inside the quotes.
+  out = out.replace(
+    new RegExp(`([A-Za-z0-9_.\\-]*${SENSITIVE_NAME}[A-Za-z0-9_.\\-]*["']?\\s*[=:]\\s*)(["'])(?:\\\\.|(?!\\2)[\\s\\S])*\\2`, "gi"),
+    "$1$2[redacted]$2",
+  );
+  // 3b. Labelled assignment with a BARE (unquoted) value — up to the next whitespace/delimiter.
+  out = out.replace(
+    new RegExp(`([A-Za-z0-9_.\\-]*${SENSITIVE_NAME}[A-Za-z0-9_.\\-]*["']?\\s*[=:]\\s*)[^\\s"'&,;}]+`, "gi"),
+    "$1[redacted]",
+  );
+  // 4. Dotted base64url tokens the single-run backstop (rule 5) cannot see: a `.` is not a legal
+  //    token terminator there, so a JWT / dotted `id.secret` slips through whole. URL delimiters
+  //    (`/ ? &`) count as boundaries too, so a query-string- or path-embedded token stays bounded.
+  //  4a. JWT — anchored on the HEADER, not on segment lengths. A compact JWS/JWT always begins
+  //      `eyJ` (base64url of `{"`); once that header is present, redact the ENTIRE dotted run
+  //      wholesale regardless of how short the payload/signature segments are (a `{}`-payload is the
+  //      valid 3-char segment `e30`) or whether a trailing signature is empty. The header IS the
+  //      signal, so no entropy check — a JWT is a credential whatever its later segments look like.
+  out = out.replace(
+    /(^|[\s=:"'(,[/?&])(eyJ[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]*){1,4})(?=$|[\s"')\],;/?&])/g,
+    "$1[redacted-token]",
+  );
+  //  4b. Generic dotted `id.secret` pair — each dot-joined segment >=12 chars AND the run
+  //      high-entropy (mixed upper+lower+digit), so a clearly credential-shaped pair like a 15.15
+  //      run is caught, while dotted hostnames, package names, versions and file paths (short and/or
+  //      low-entropy segments — none carry the upper+lower+digit combo) stay readable.
+  out = out.replace(
+    /(^|[\s=:"'(,[/?&])([A-Za-z0-9_-]{12,}(?:\.[A-Za-z0-9_-]{12,}){1,2})(?=$|[\s"')\],;/?&])/g,
+    (match, pre: string, tok: string) => {
+      const bare = tok.replace(/\./g, "");
+      const highEntropy = /[A-Z]/.test(bare) && /[a-z]/.test(bare) && /[0-9]/.test(bare);
+      return highEntropy ? `${pre}[redacted-token]` : match;
+    },
+  );
+  // 5. Unlabelled high-entropy token backstop: a >=24-char base64url run that is either mixed
+  //    upper+lower+digit or carries base64 markers (+//). A plain lowercase-hex or all-lowercase
+  //    run (git SHA, UUID) is left alone so ordinary identifiers stay readable.
+  out = out.replace(/(^|[\s=:"'(,[&?])([A-Za-z0-9_+/-]{24,}={0,2})(?=$|[\s"')\],;&?])/g, (match, pre: string, tok: string) => {
+    const highEntropy = (/[A-Z]/.test(tok) && /[a-z]/.test(tok) && /[0-9]/.test(tok)) || /[+/]/.test(tok);
+    return highEntropy ? `${pre}[redacted-token]` : match;
+  });
+  return out;
+}
+
+/** Redact then clip to the shared activity-row budget. The single exit through which every
+ *  adapter's summary text passes, so redaction can never be skipped. Clips only when the redacted
+ *  text is LONGER than the budget (`> 200`), byte-identical to the pre-existing Claude/Codex clip. */
+export function clipToolSummary(text: string): string {
+  const redacted = redactSecrets(text);
+  return redacted.length > SUMMARY_MAX_CHARS ? `${redacted.slice(0, SUMMARY_CLIP_CHARS)}…` : redacted;
+}
+
+/**
+ * Pick the first present candidate arg field from a tool's input and return its one-line value,
+ * or "" when none is present. `extraKeys` lets an adapter prepend provider-specific field names
+ * ahead of the shared list without re-implementing the scan.
+ */
+export function summarizeToolInput(input: Record<string, unknown> | undefined, extraKeys: readonly string[] = []): string {
+  if (!input) return "";
+  for (const key of [...extraKeys, ...SUMMARY_CANDIDATE_KEYS]) {
+    const value = input[key];
+    if (typeof value === "string" && value.trim()) return oneLineText(value);
+  }
+  return "";
+}
+
+// #2437 — the structured-params sibling of the one-line summary above: the FULL tool-call
+// input/arguments, redacted then size-capped for the dashboard trace's expandable detail (the
+// one-line `body` stays a short label; this is the "show me everything" view). Own budget, own
+// key list — deliberately separate constants from the one-line summary's so tuning one never
+// silently reshapes the other.
+const PARAMS_DEFAULT_MAX_BYTES = 3200;
+const PARAMS_TRUNCATION_MARKER = "…[truncated]";
+// Field names that get their VALUE wholesale-redacted regardless of shape (a bare `[redacted]`,
+// not run through redactSecrets — the key name alone is reason enough not to show any of it).
+const SENSITIVE_PARAM_KEY = /token|secret|password|key|authorization/i;
+const PARAMS_MAX_DEPTH = 12;
+
+function redactParamsValue(value: unknown, depth: number): unknown {
+  if (depth > PARAMS_MAX_DEPTH) return "[redacted-depth]";
+  if (typeof value === "string") return redactSecrets(value);
+  if (Array.isArray(value)) return value.map((entry) => redactParamsValue(entry, depth + 1));
+  if (value && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+      out[key] = SENSITIVE_PARAM_KEY.test(key) ? "[redacted]" : redactParamsValue(entry, depth + 1);
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Redact then size-cap a tool call's raw input/arguments for the dashboard trace's expandable
+ * detail (#2437). Redaction runs FIRST, over the whole structured value — every string passes
+ * through the shared `redactSecrets` net, and any object key matching
+ * `/token|secret|password|key|authorization/i` is replaced wholesale — so a later byte-budget cut
+ * can never land mid-secret. Only THEN is the redacted value serialized and size-capped: within
+ * `maxBytes` it is returned as the still-structured (object/array/primitive) value so the caller's
+ * JSON viewer pretty-prints it; over budget, the serialized text is sliced to `maxBytes` UTF-8
+ * bytes and a trailing `…[truncated]` marker appended, returned as a plain string. `undefined`/
+ * `null` input passes through unchanged so a tool with no captured input round-trips cleanly.
+ */
+export function redactAndCapParams(input: unknown, maxBytes: number = PARAMS_DEFAULT_MAX_BYTES): unknown {
+  if (input === undefined || input === null) return input;
+  const redacted = redactParamsValue(input, 0);
+  let serialized: string;
+  try {
+    serialized = JSON.stringify(redacted) ?? "";
+  } catch {
+    return "[unserializable]";
+  }
+  if (Buffer.byteLength(serialized, "utf8") <= maxBytes) return redacted;
+  const truncated = Buffer.from(serialized, "utf8").subarray(0, maxBytes).toString("utf8");
+  return `${truncated}${PARAMS_TRUNCATION_MARKER}`;
+}
+
+/** #3411 — the absolute file paths among a tool's raw input values: a relative path resolves
+ *  against `cwd` when one is known and is dropped otherwise. Undefined when none remain. */
+export function absoluteToolPaths(candidates: readonly unknown[], cwd?: string): string[] | undefined {
+  const paths: string[] = [];
+  for (const candidate of candidates) {
+    if (typeof candidate !== "string" || !candidate.trim()) continue;
+    if (isAbsolute(candidate)) paths.push(candidate);
+    else if (cwd) paths.push(resolve(cwd, candidate));
+  }
+  return paths.length ? paths : undefined;
+}
+
+/** #3508 — the files a Codex shell command reads: Codex parses each read into `commandActions`
+ *  ({ type: "read", path }), so a read touches its file's area just as an edit does. */
+export function codexReadPaths(item: Record<string, unknown>, cwd?: string): string[] | undefined {
+  const actions = Array.isArray(item.commandActions) ? item.commandActions.filter(isRecord) : [];
+  const reads = actions.filter((a) => a.type === "read").map((a) => stringValue(a.path) ?? "").filter(Boolean);
+  return absoluteToolPaths(reads, stringValue(item.cwd) ?? cwd);
+}

package/src/agent-redact.ts

@@ -0,0 +1,75 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { AGENT_REDACT_FILES, AGENT_REDACT_VERSION, agentRedactInstallDir, agentRedactConfigPath, errMessage, isRecord, type ProvisioningHookSet } from "@humwick/sdk";
+import { humwickHome, redactionEnabledFromEnv } from "./config";
+import { parseHookSet } from "./project-hooks";
+
+// #3025 — agent-redact post-tool hooks for every runner-managed launch. The orchestrator installs
+// the pinned binary and the hook entries its `install` command writes (agent-redact-provisioning.ts).
+// A host without them launches agents without redaction and says so: an agent must always run.
+
+/** What reached the launch. Reported on every launch (relay-injection-events.ts). */
+export type AgentRedactState =
+  | { state: "on"; version: string; mechanism: string }
+  | { state: "off" }
+  | { state: "unavailable"; reason: string };
+
+type AgentRedactAbsent = Exclude<AgentRedactState, { state: "on" }>;
+
+export interface AgentRedactInstall {
+  claudeHooks: ProvisioningHookSet;
+  codexHooks: ProvisioningHookSet;
+  opencodePlugin: string;
+}
+
+
+export function resolveAgentRedact(home: string = humwickHome()): AgentRedactInstall | AgentRedactAbsent {
+  if (!redactionEnabledFromEnv()) return { state: "off" };
+  const dir = agentRedactInstallDir(home);
+  if (!existsSync(join(dir, AGENT_REDACT_FILES.binary))) {
+    return { state: "unavailable", reason: `agent-redact ${AGENT_REDACT_VERSION} is not installed on this host (${dir})` };
+  }
+  try {
+    const opencodePlugin = join(dir, AGENT_REDACT_FILES.opencodePlugin);
+    if (!existsSync(opencodePlugin)) throw new Error(`${opencodePlugin} is missing`);
+    return {
+      claudeHooks: readPostToolUseHooks(join(dir, AGENT_REDACT_FILES.claudeHooks)),
+      codexHooks: readPostToolUseHooks(join(dir, AGENT_REDACT_FILES.codexHooks)),
+      opencodePlugin,
+    };
+  } catch (err) {
+    return { state: "unavailable", reason: `agent-redact ${AGENT_REDACT_VERSION} hook entries are unusable: ${errMessage(err)}` };
+  }
+}
+
+export function isAgentRedactInstall(value: AgentRedactInstall | AgentRedactAbsent): value is AgentRedactInstall {
+  return !("state" in value);
+}
+
+export function agentRedactOn(mechanism: string): AgentRedactState {
+  return { state: "on", version: AGENT_REDACT_VERSION, mechanism };
+}
+
+/** Hooks inherit the provider's env. An operator's own AGENT_REDACT_CONFIG wins over Relay's. */
+export function agentRedactEnv(redaction: AgentRedactState): Record<string, string> {
+  return redaction.state === "on" ? { AGENT_REDACT_CONFIG: process.env.AGENT_REDACT_CONFIG || agentRedactConfigPath() } : {};
+}
+
+/** Puts the plugin in (or takes it out of) an OpenCode config dir. True when the plugin is in place. */
+export function syncOpenCodeRedactPlugin(opencodeConfigDir: string, redaction: AgentRedactState, home: string = humwickHome()): boolean {
+  const target = join(opencodeConfigDir, "plugins", "agent-redact.ts");
+  if (redaction.state !== "on") {
+    rmSync(target, { force: true });
+    return false;
+  }
+  mkdirSync(join(opencodeConfigDir, "plugins"), { recursive: true, mode: 0o700 });
+  copyFileSync(join(agentRedactInstallDir(home), AGENT_REDACT_FILES.opencodePlugin), target);
+  return true;
+}
+
+function readPostToolUseHooks(path: string): ProvisioningHookSet {
+  const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+  const hooks = parseHookSet(isRecord(parsed) ? parsed.hooks : undefined);
+  if (!hooks.PostToolUse?.length) throw new Error(`${path} has no PostToolUse hook`);
+  return hooks;
+}

package/src/agent-runner/commands/dispatch.ts

@@ -0,0 +1,185 @@
+import { errMessage, isRecord } from "@humwick/sdk";
+import type { ShutdownOutcome } from "../../adapter";
+import type { ProviderInputTicket } from "../../provider-input-queue";
+import type { NativeSelfResumeHandoff } from "../../native-self-resume";
+import { PROVIDER_INPUT_COMMAND_TYPES } from "../../runner-helpers";
+import { boundaryReasonForCommand, type LifecycleAction, type SessionDestroyReason } from "../../session-destroy";
+import { exitRunner } from "../../runner-exit";
+import { logger } from "../../logger";
+import { ContextSubmitAborted } from "../../context-boundary";
+import type { RunnerLaunchOptions } from "../runner-context";
+
+interface CommandDispatchDeps {
+  agentId: string;
+  options: RunnerLaunchOptions;
+  reserveInput(): ProviderInputTicket;
+  disarmForcedContext(type: string): void;
+  beginExitCommand(): void;
+  setLifecycleAction(action: LifecycleAction | undefined): void;
+  isStopped(): boolean;
+  beginNativeSelfResume(type: string, params: Record<string, unknown>, commandId: string): NativeSelfResumeHandoff | undefined;
+  runNativeSelfResume<T>(handoff: NativeSelfResumeHandoff | undefined, operation: () => Promise<T>): Promise<T>;
+  rejectNativeSelfResume(handoff: NativeSelfResumeHandoff, error: Error): void;
+  finishNativeSelfResume(handoff: NativeSelfResumeHandoff): void;
+  beginSelfResumeClearFence(type: string, params: Record<string, unknown>, commandId: string): void;
+  startCommandClaim(commandId: string): void;
+  finishCommandClaim(commandId: string): void;
+  runPreSessionDestroy(reason: SessionDestroyReason): Promise<void>;
+  publishStatus(): void;
+  reconnect(): void;
+  restart(params: Record<string, unknown>): Promise<void>;
+  compactCommand(params: Record<string, unknown>, handoff: NativeSelfResumeHandoff | undefined, commandId: string): Promise<Record<string, unknown>>;
+  clearContextCommand(params: Record<string, unknown>, ticket: ProviderInputTicket | undefined, commandId: string): Promise<Record<string, unknown>>;
+  releaseSubmitHold(params: Record<string, unknown>): Promise<Record<string, unknown>>;
+  interrupt(params: Record<string, unknown>): Promise<Record<string, unknown> | void>;
+  injectContext(params: Record<string, unknown>, ticket?: ProviderInputTicket): Promise<Record<string, unknown>>;
+  respondToPermissionDecision(params: Record<string, unknown>): Promise<Record<string, unknown>>;
+  injectPrompt(params: Record<string, unknown>, ticket?: ProviderInputTicket, commandId?: string): Promise<Record<string, unknown>>;
+  shutdown(type: string, params: Record<string, unknown>): Promise<ShutdownOutcome>;
+  finishClearCommand(commandId: string): void;
+  setOffline(): Promise<unknown>;
+  deleteAgent(): Promise<unknown>;
+  stop(): Promise<void>;
+  updateCommand(commandId: string, input: { status: string; result?: Record<string, unknown>; error?: string }): Promise<unknown>;
+  /** `GET /api/commands/:id` — the full record behind a bounded bus event (#3606). */
+  fetchCommand(commandId: string): Promise<Response>;
+  /** #3398 — the command's destructive input reached the provider and no reset has settled it. */
+  destructiveInputUnsettled(commandId: string): boolean;
+  checkAcknowledgement(ack: unknown, status: string): void;
+}
+
+export class CommandDispatch {
+  constructor(private readonly deps: CommandDispatchDeps) {}
+
+  /**
+   * The bus dispatch seam (#1565 F1).
+   *
+   * Commands that put a payload into the provider's input channel take their place in the
+   * `providerInput` queue HERE, synchronously, before the first `await` — so the order the relay
+   * created them in (continuation first, memory beside it) is the order they are delivered in, no
+   * matter how long each command's own bookkeeping takes. Everything else keeps dispatching
+   * fire-and-forget: the gate is on the wire, not on command handling.
+   *
+   * The ticket is released when the command settles even if delivery never happened (a throw before
+   * the deliver, an unsupported provider), so a failed command can never wedge the stream.
+   */
+  dispatchCommand(type: string, params: Record<string, unknown>, commandId: string, command?: Record<string, unknown>): void {
+    const ticket = PROVIDER_INPUT_COMMAND_TYPES.has(type) ? this.deps.reserveInput() : undefined;
+    void this.handleCommand(type, params, commandId, command, ticket).finally(() => ticket?.release());
+  }
+
+  private async handleCommand(type: string, params: Record<string, unknown>, commandId: string, command?: Record<string, unknown>, ticket?: ProviderInputTicket): Promise<void> {
+    const target = typeof command?.target === "string" ? command.target : this.deps.agentId;
+    if (target !== this.deps.agentId && target !== this.deps.options.runnerId) return;
+    if (type !== "agent.shutdown" && type !== "agent.restart" && type !== "agent.reconnect" && type !== "agent.kill" && type !== "agent.compact" && type !== "agent.clearContext" && type !== "agent.injectContext" && type !== "agent.permissionDecision" && type !== "agent.interrupt" && type !== "agent.releaseSubmitHold" && type !== "prompt.inject") return;
+    // #3606 — a bus event carries params whole only up to a size budget; read the rest by id.
+    if (command?.paramsOmitted === true) {
+      try { params = await this.loadCommandParams(commandId); } catch (error) {
+        await this.updateCommand(commandId, "failed", undefined, `command params unavailable: ${errMessage(error)}`).catch(() => {});
+        return;
+      }
+    }
+
+    this.deps.disarmForcedContext(type);
+
+    const exitAfterCommand = type === "agent.shutdown" || type === "agent.kill";
+    if (exitAfterCommand) this.deps.beginExitCommand();
+    // #1746 — the confirmed terminal outcome of an exit command's provider teardown. Stays
+    // undefined if shutdownProvider never ran or threw; only a positive `killed` authorizes
+    // deregistration (a roster removal must imply the process is gone).
+    let killOutcome: ShutdownOutcome | undefined;
+    const nativeSelfResume = this.deps.beginNativeSelfResume(type, params, commandId);
+    this.deps.beginSelfResumeClearFence(type, params, commandId);
+    this.deps.startCommandClaim(commandId);
+    try {
+      await this.deps.runNativeSelfResume(nativeSelfResume, () => this.updateCommand(commandId, "accepted"));
+      await this.deps.runNativeSelfResume(nativeSelfResume, () => this.updateCommand(commandId, "running"));
+      // Pre-session-destroy seam (#183): for destructive transitions, run end-of-session
+      // work (Insights capture, #184) BEFORE the invasive operation, surfaced as a
+      // non-addressable "finalizing" state so the agent isn't mistaken for merely busy.
+      const destroyReason = boundaryReasonForCommand(type);
+      if (destroyReason) await this.deps.runNativeSelfResume(nativeSelfResume, () => this.deps.runPreSessionDestroy(destroyReason));
+      // Move from the transient finalizing window to the executing teardown state (or drop
+      // it entirely for compact/clear, which complete promptly once capture is done).
+      if (exitAfterCommand) this.deps.setLifecycleAction(type === "agent.kill" ? "killing" : "shutting-down");
+      else if (type === "agent.restart") this.deps.setLifecycleAction("restarting");
+      else this.deps.setLifecycleAction(undefined);
+      if (!exitAfterCommand) this.deps.publishStatus();
+      let providerResult: Record<string, unknown> | void = undefined;
+      if (type === "agent.restart") await this.deps.restart(params);
+      else if (type === "agent.reconnect") this.deps.reconnect();
+      else if (type === "agent.compact") {
+        providerResult = await this.deps.compactCommand(params, nativeSelfResume, commandId);
+      } else if (type === "agent.clearContext") {
+        providerResult = await this.deps.clearContextCommand(params, ticket, commandId);
+      } else if (type === "agent.releaseSubmitHold") {
+        providerResult = await this.deps.releaseSubmitHold(params);
+      } else if (type === "agent.interrupt") {
+        providerResult = await this.deps.interrupt(params);
+      } else if (type === "agent.injectContext") {
+        providerResult = await this.deps.injectContext(params, ticket);
+      } else if (type === "agent.permissionDecision") {
+        providerResult = await this.deps.respondToPermissionDecision(params);
+      } else if (type === "prompt.inject") {
+        providerResult = await this.deps.injectPrompt(params, ticket, commandId);
+      } else {
+        killOutcome = await this.deps.shutdown(type, params);
+      }
+      await this.updateCommand(commandId, "succeeded", {
+        action: type,
+        agentId: this.deps.agentId,
+        runnerId: this.deps.options.runnerId,
+        policyName: this.deps.options.policyName,
+        spawnRequestId: this.deps.options.spawnRequestId,
+        reason: typeof params.reason === "string" ? params.reason : undefined,
+        ...(providerResult ? { providerResult } : {}),
+      });
+    } catch (error) {
+      if (nativeSelfResume) this.deps.rejectNativeSelfResume(nativeSelfResume, error instanceof Error ? error : new Error(errMessage(error)));
+      this.deps.finishCommandClaim(commandId);
+      this.deps.publishStatus();
+      // An unsettled destructive input can still reset the context: Relay replaces the process (#3398).
+      // One that never reached the provider says so: nothing can still apply, and Relay closes its obligation (#3441).
+      const unsettled = this.deps.destructiveInputUnsettled(commandId) ? { destructiveInputUnsettled: true }
+        : error instanceof ContextSubmitAborted ? { destructiveInputSubmitted: false } : undefined;
+      await this.updateCommand(commandId, "failed", unsettled, errMessage(error)).catch(() => {});
+    } finally {
+      this.deps.finishCommandClaim(commandId);
+      this.deps.finishClearCommand(commandId);
+      if (exitAfterCommand) {
+        if (params.preserveRegistration === true) {
+          await this.deps.setOffline().catch(() => {});
+        } else if (killOutcome === "killed") {
+          // #1746 — CONFIRM-DEAD-BEFORE-DEREGISTER. Only remove the roster row once the
+          // provider is positively confirmed gone. If the force-kill could not confirm death
+          // (killOutcome "failed-to-kill", or undefined because shutdownProvider threw), leave
+          // the agent registered so it stays visible (as "kill-failed") rather than becoming a
+          // silent zombie — a roster removal must imply the process is dead.
+          await this.deps.deleteAgent().catch(() => {});
+        }
+        if (this.deps.options.exitProcessOnShutdown !== false) {
+          setTimeout(() => void this.deps.stop().catch((error) => {
+            logger.error("lifecycle", `stop after command failed: ${error}`);
+          }).finally(() => exitRunner(0, type === "agent.kill" ? "agent.kill command" : "agent.shutdown command")), 10);
+        }
+      } else if (!this.deps.isStopped()) {
+        if (nativeSelfResume) this.deps.finishNativeSelfResume(nativeSelfResume);
+        this.deps.setLifecycleAction(undefined);
+        this.deps.publishStatus();
+      }
+    }
+  }
+
+  private async loadCommandParams(commandId: string): Promise<Record<string, unknown>> {
+    const response = await this.deps.fetchCommand(commandId);
+    if (!response.ok) throw new Error(`command lookup failed: ${response.status}`);
+    const command: unknown = await response.json();
+    if (!isRecord(command) || !isRecord(command.params)) throw new Error("command lookup returned no params");
+    return command.params;
+  }
+
+  private async updateCommand(commandId: string, status: string, result?: Record<string, unknown>, error?: string): Promise<void> {
+    const ack = await this.deps.updateCommand(commandId, { status, ...(result ? { result } : {}), ...(error ? { error } : {}) });
+    this.deps.checkAcknowledgement(ack, status);
+  }
+}

package/src/agent-runner/commands/lifecycle.ts

@@ -0,0 +1,84 @@
+import { errMessage } from "@humwick/sdk";
+import type { ManagedProcess, ShutdownOutcome } from "../../adapter";
+import type { RestartProviderOptions } from "../../runner-helpers";
+import { commandTimeoutMs, restartOptionsFromCommand } from "../../runner-helpers";
+import type { LifecycleAction } from "../../session-destroy";
+import type { RunnerLaunchOptions } from "../runner-context";
+import { logger } from "../../logger";
+
+interface LifecycleCommandsDeps {
+  options: RunnerLaunchOptions;
+  agentId: string;
+  process(): ManagedProcess | undefined;
+  restartProvider(options: RestartProviderOptions): Promise<void>;
+  shutdownProvider(hard: boolean, timeoutMs: number): Promise<ShutdownOutcome>;
+  releaseSubmitHold(resend: boolean): Promise<Record<string, unknown>>;
+  hasProviderTurn(): boolean;
+  sessionLog(message: string): void;
+  resetEmptyTurns(): void;
+  scheduleInterruptReconcile(): void;
+  waitForProviderTurnClear(): Promise<void>;
+  injectPrompt(params: Record<string, unknown>): Promise<Record<string, unknown>>;
+  markStopped(): void;
+  armTerminal(): void;
+  setLifecycleAction(action: LifecycleAction | undefined): void;
+  publishStatus(): void;
+}
+
+export class LifecycleCommands {
+  constructor(private readonly deps: LifecycleCommandsDeps) {}
+
+  restart(params: Record<string, unknown>): Promise<void> {
+    return this.deps.restartProvider(restartOptionsFromCommand(params));
+  }
+
+  reconnect(): void { this.deps.publishStatus(); }
+
+  releaseSubmitHold(params: Record<string, unknown>): Promise<Record<string, unknown>> {
+    return this.deps.releaseSubmitHold(params.resend === true);
+  }
+
+  async interrupt(params: Record<string, unknown>): Promise<Record<string, unknown> | void> {
+    let providerResult: Record<string, unknown> | void = undefined;
+    if (!this.deps.options.adapter.interrupt || !this.deps.process()) throw new Error("provider does not support interrupt");
+    const redirect = params.redirect && typeof params.redirect === "object" && !Array.isArray(params.redirect)
+      ? params.redirect as Record<string, unknown>
+      : undefined;
+    const hasProviderTurn = this.deps.hasProviderTurn();
+    if (hasProviderTurn || !redirect) {
+      this.deps.sessionLog(`interrupt requested via ${typeof params.requestedVia === "string" ? params.requestedVia : "dashboard"}`);
+      // #2389 — an interrupted turn always ends with no output, and that state already has its
+      // own notice (`agent.turn_interrupted`). It must not also draw an empty-turn strike.
+      this.deps.resetEmptyTurns();
+      providerResult = await this.deps.options.adapter.interrupt(this.deps.process()!);
+      this.deps.scheduleInterruptReconcile();
+    }
+    if (redirect && hasProviderTurn) await this.deps.waitForProviderTurnClear();
+    if (redirect) providerResult = { interrupt: providerResult, redirect: await this.deps.injectPrompt(redirect) };
+    return providerResult;
+  }
+
+  async shutdown(type: string, params: Record<string, unknown>): Promise<ShutdownOutcome> {
+    let killOutcome: ShutdownOutcome;
+    try {
+      killOutcome = await this.deps.shutdownProvider(type === "agent.kill", commandTimeoutMs(params));
+    } catch (shutdownError) {
+      // #1725 fix-forward — a throw INSIDE shutdownProvider (e.g. tmux missing from PATH ⇒
+      // defaultKillSession's Bun.spawnSync throws ENOENT) previously left killOutcome undefined
+      // and the "kill-failed" pill unset (that pill is set inside shutdownProvider, which never
+      // completed) — so the confirm-dead gate below deleted nothing AND published nothing, wedging
+      // the agent at "shutting-down" forever while the process exited anyway. Treat the throw
+      // exactly like a returned "failed-to-kill": surface the terminal pill and proceed, so the
+      // row reflects reality (a visible, re-targetable kill-failed) instead of an indefinite
+      // in-flight state, and the confirm-dead gate keeps it registered rather than deregistering
+      // a process whose death was never confirmed.
+      killOutcome = "failed-to-kill";
+      this.deps.markStopped();
+      this.deps.armTerminal();
+      this.deps.setLifecycleAction("kill-failed");
+      this.deps.publishStatus();
+      logger.error("lifecycle", `provider shutdown threw for ${this.deps.agentId}: ${errMessage(shutdownError)}; treating as failed-to-kill and keeping agent registered`);
+    }
+    return killOutcome;
+  }
+}