harnery 0.42.0 → 0.43.0

package/src/core/hooks/cli.ts

@@ -57,7 +57,13 @@ import {
 } from "../agents/state/heartbeat-writer.ts";
 import { readLiveCoordinationRow } from "../agents/state/live-coordination-view.ts";
 import { ensureLiveCoordinationHeartbeat } from "../agents/state/live-coordination-writer.ts";
-import { assignName } from "../agents/state/names.ts";
+import {
+  assignName,
+  readForkParent,
+  readForkState,
+  recordForkDetection,
+  resolveName,
+} from "../agents/state/names.ts";
 import { writePidmapRow } from "../agents/state/pidmap.ts";
 import {
   agentsRequireGitFinalization,
@@ -115,6 +121,7 @@ import {
   soundForEvent,
 } from "./effects/index.ts";
 import { toolInputHash, toolTargetHash } from "./events/input-hash.ts";
+import { detectClaudeCodeFork } from "./fork-lineage.ts";
 import { canonicalize } from "./guard-path.ts";
 import {
   beginHookHealth,
@@ -135,6 +142,7 @@ import {
 } from "./resolve/transcript.ts";
 import { clearHookRunMarker, writeHookRunMarker } from "./run-markers.ts";
 import { sessionNamePresence } from "./session-name-presence.ts";
+import { shellRmReason } from "./shell-rm.ts";
 import { shellWaiterReason } from "./shell-waiter.ts";
 
 interface Argv {
@@ -250,12 +258,14 @@ function assignNameInProcess(
   coordRoot: string,
   instanceId: string,
   kind: "session" | "subagent" | "transient",
-  forkedFrom?: string,
+  fork?: { forkedFrom?: string; fork?: boolean; forkChecked?: boolean },
 ): { name: string; kind: string } | null {
   try {
     const name = assignName(coordRoot, instanceId, kind, {
       freshnessSecs: coordFreshnessSeconds(coordRoot),
-      ...(forkedFrom ? { forkedFrom } : {}),
+      ...(fork?.forkedFrom ? { forkedFrom: fork.forkedFrom } : {}),
+      ...(fork?.fork ? { fork: true } : {}),
+      ...(fork?.forkChecked ? { forkChecked: true } : {}),
     });
     return { name, kind };
   } catch {
@@ -263,6 +273,66 @@ function assignNameInProcess(
   }
 }
 
+/**
+ * Name a main session, recording fork lineage when the instance is new. Every
+ * main-session naming path goes through here: whichever hook first sees a new
+ * instance writes its history row, and lineage can only ride that first row
+ * (later detection appends a `fork.detected` row instead).
+ */
+function assignSessionNameInProcess(
+  coordRoot: string,
+  instanceId: string,
+  payload: ParsedPayload | null,
+  adapter: Adapter,
+): { name: string; kind: string } | null {
+  let fork: { forkedFrom?: string; fork?: boolean; forkChecked?: boolean } | undefined;
+  try {
+    if (
+      adapter === "claude-code" &&
+      payload?.session_id === instanceId &&
+      !resolveName(coordRoot, instanceId)
+    ) {
+      const detected = detectClaudeCodeFork({
+        coordRoot,
+        transcriptPath: payload.transcript_path,
+        sessionId: instanceId,
+        source: payload.source,
+      });
+      fork = {
+        ...(detected.forkedFrom ? { forkedFrom: detected.forkedFrom } : {}),
+        fork: detected.fork,
+        forkChecked: detected.checked,
+      };
+    }
+  } catch {
+    fork = undefined;
+  }
+  return assignNameInProcess(coordRoot, instanceId, "session", fork);
+}
+
+/**
+ * Finish fork detection that session start could not: a CLI fork starts before
+ * its transcript exists, and a mid-flight instance may never see SessionStart.
+ * Runs once per instance; the appended `fork_checked` row stops later calls.
+ */
+function healForkLineage(
+  coordRoot: string,
+  instanceId: string,
+  payload: ParsedPayload | null,
+): void {
+  if (!payload?.transcript_path || payload.session_id !== instanceId) return;
+  const state = readForkState(coordRoot, instanceId);
+  if (!state || state.checked) return;
+  const detected = detectClaudeCodeFork({
+    coordRoot,
+    transcriptPath: payload.transcript_path,
+    sessionId: instanceId,
+    knownFork: state.fork,
+  });
+  if (!detected.checked) return;
+  recordForkDetection(coordRoot, instanceId, detected);
+}
+
 /** Mid-flight sessions can emit tools before SessionStart assigns a pool name.
  * Stamp the disposable cache so Codec does not render the 8-character id. */
 function ensureSessionDisplayName(
@@ -270,13 +340,14 @@ function ensureSessionDisplayName(
   instanceId: string,
   sessionId: string,
   adapter: Adapter,
+  payload: ParsedPayload | null,
 ): void {
   if (coordEnv("WORKFLOW_CHILD") === "1") return;
   const row =
     readLiveCoordinationRow(coordRoot, instanceId) ?? readHeartbeat(coordRoot, instanceId);
   if (row?.kind === "subagent" || row?.kind === "transient" || row?.workflow_run_id) return;
   if (row?.name?.trim()) return;
-  const assigned = assignNameInProcess(coordRoot, instanceId, "session");
+  const assigned = assignSessionNameInProcess(coordRoot, instanceId, payload, adapter);
   if (!assigned?.name) return;
   if (!readHeartbeat(coordRoot, instanceId)) {
     try {
@@ -345,22 +416,22 @@ function buildEventData(
       // The platform label is the adapter id itself; enumerating and defaulting
       // to codex silently mislabels any adapter not in the list.
       const adapterPlatform = ctx.adapter;
-      // Recorded fork lineage is NOT detected here. On claude-code a fork
-      // never fires its own session.started — SessionStart fires under the
-      // PARENT's session id (source=resume) before the fork id is minted
-      // (verified 2026-08-05) — so detection at this point can only mislabel
-      // the resumed parent. The fork's new instance is caught by the
-      // tool.requested heal path instead. The forkedFrom plumbing below stays
-      // for adapters that DO report a parent at session start.
-      const forkedFrom: string | undefined = undefined;
       // Assign (or recover) name + kind in-process. Idempotent: resume
-      // returns the original name; new owner consumes a counter slot.
+      // returns the original name; new owner consumes a counter slot and,
+      // on claude-code, runs fork detection (fork-lineage.ts). Since Claude
+      // Code 2.1.283 both fork flows fire SessionStart under the FORK's own
+      // id (verified 2026-10-07), superseding the 2026-08-05 finding that a
+      // fork never started on its own id. A resumed parent keeps its existing
+      // history row, so it is never relabeled here.
       // Workflow children stay unnamed, as on the tool path: a pool name
       // would make them the addressee of mail held for that name.
       const assigned =
         coordEnv("WORKFLOW_CHILD") === "1"
           ? undefined
-          : assignNameInProcess(ctx.coordRoot, ctx.instanceId, "session", forkedFrom);
+          : assignSessionNameInProcess(ctx.coordRoot, ctx.instanceId, p, ctx.adapter);
+      const forkedFrom = assigned
+        ? readForkParent(ctx.coordRoot, ctx.instanceId)?.instance_id
+        : undefined;
       // Write the adapter pid-map row so `harn agents whoami` ppid-walks find
       // this owner. Prefer the payload pid (the actual claude binary), then the
       // anchor walk (the `node` ancestor for Cursor, which has no payload pid),
@@ -429,7 +500,7 @@ function buildEventData(
         coordEnv("WORKFLOW_CHILD") !== "1" &&
         !readLiveCoordinationRow(ctx.coordRoot, ctx.instanceId)?.name
       ) {
-        assignNameInProcess(ctx.coordRoot, ctx.instanceId, "session");
+        assignSessionNameInProcess(ctx.coordRoot, ctx.instanceId, p, ctx.adapter);
       }
       const prompt = p?.prompt ?? "";
       const { value, truncated } = clampString(prompt, 4000);
@@ -851,7 +922,7 @@ async function main(): Promise<number> {
     !priorCoordination?.workflow_run_id &&
     !priorCoordination?.name?.trim()
   ) {
-    assignNameInProcess(coordRoot, owner.instance_id, "session");
+    assignSessionNameInProcess(coordRoot, owner.instance_id, payload, adapter);
   }
 
   const data = buildEventData(norm.event_type, {
@@ -1063,11 +1134,18 @@ function recordSignal(run: HookRun): void {
   }
   if (norm.event_type !== "session.ended") {
     try {
-      ensureSessionDisplayName(coordRoot, owner.instance_id, sessionId, adapter);
+      ensureSessionDisplayName(coordRoot, owner.instance_id, sessionId, adapter, payload);
     } catch (error) {
       logError(coordRoot, error, { phase: "session-display-name" });
     }
   }
+  if (norm.event_type === "tool.requested" && adapter === "claude-code" && run.topLevelSession) {
+    try {
+      healForkLineage(coordRoot, owner.instance_id, payload);
+    } catch (error) {
+      logError(coordRoot, error, { phase: "fork-lineage-heal" });
+    }
+  }
   const v3EventId =
     v3Result && "event" in v3Result
       ? v3Result.event.event_id
@@ -1559,6 +1637,17 @@ async function handleToolRequested(run: HookRun): Promise<number | undefined> {
     return 0;
   }
 
+  const rmReason = shellRmReason(
+    payload?.tool_name,
+    payload?.tool_input,
+    resolveBinName(coordRoot),
+  );
+  if (rmReason) {
+    const { emitDeny } = await import("./adapter/output.ts");
+    emitDeny(adapter, rmReason);
+    return 0;
+  }
+
   // G-guard for ALL adapters. Claude Code previously ran this via a
   // pre-tool-use bash adapter (which called `agent-coord verdict --rule=claim`);
   // that adapter is now deleted, so agent-hook owns the deny for every adapter.

package/src/core/hooks/fork-lineage.ts

@@ -0,0 +1,82 @@
+/**
+ * Claude Code fork detection: decide whether a new main-session instance is a
+ * branch of another session, and which one.
+ *
+ * Two shapes exist as of Claude Code 2.1.283 (verified 2026-10-07):
+ *
+ *   - CLI `--resume <id> --fork-session` fires SessionStart under the FORK's id
+ *     with `source: "fork"`, before its transcript exists, and names no parent.
+ *     The transcript later holds the parent's message uuids with every row's
+ *     `sessionId` rewritten, so the parent is found by uuid containment
+ *     (`detectForkParent`) once the transcript is on disk.
+ *   - The desktop app's "Fork from here" copies the parent's rows into the
+ *     fork's transcript with their original `sessionId`, so inherited rows
+ *     name the parent directly (`detectInheritedSessionParent`).
+ *
+ * Inherited rows alone do not prove a fork: a continuation of a finished
+ * session can carry them too. The parent's liveness separates the two. A
+ * parent with an unended generation is still running (or resumable) and owns
+ * its name, task, and claims, so the new instance is a fork. A finished
+ * parent makes it a continuation, which keeps the generic notice.
+ *
+ * Everything here fails open: an unreadable transcript or an unknown layout
+ * yields "not a fork", never an error.
+ */
+
+import { existsSync } from "node:fs";
+import { readLiveCoordinationRow } from "../agents/state/live-coordination-view.ts";
+import { detectForkParent, detectInheritedSessionParent } from "./resolve/transcript.ts";
+
+export interface ForkDetection {
+  fork: boolean;
+  forkedFrom?: string;
+  /** Detection had the evidence it needs; the tool-path heal can skip it. */
+  checked: boolean;
+}
+
+/** Sources after which a brand-new instance cannot hold inherited history. */
+const FRESH_SOURCES = new Set(["startup", "clear"]);
+
+export function detectClaudeCodeFork(input: {
+  coordRoot: string;
+  transcriptPath: string | undefined;
+  sessionId: string;
+  source?: string;
+  /** The instance was already recorded as a fork without a parent. */
+  knownFork?: boolean;
+  isLive?: (instanceId: string) => boolean;
+}): ForkDetection {
+  try {
+    const declared = input.source === "fork" || input.knownFork === true;
+    const transcriptReady = !!input.transcriptPath && existsSync(input.transcriptPath);
+    const isLive =
+      input.isLive ?? ((id: string) => readLiveCoordinationRow(input.coordRoot, id) !== null);
+
+    const inherited = transcriptReady
+      ? detectInheritedSessionParent(input.transcriptPath, input.sessionId)
+      : undefined;
+    if (inherited && inherited !== input.sessionId) {
+      if (declared || isLive(inherited)) {
+        return { fork: true, forkedFrom: inherited, checked: true };
+      }
+      return { fork: false, checked: true };
+    }
+
+    if (declared) {
+      if (!transcriptReady) return { fork: true, checked: false };
+      const parent = detectForkParent(input.transcriptPath, input.sessionId);
+      return {
+        fork: true,
+        ...(parent && parent !== input.sessionId ? { forkedFrom: parent } : {}),
+        checked: true,
+      };
+    }
+
+    return {
+      fork: false,
+      checked: transcriptReady || FRESH_SOURCES.has(input.source ?? ""),
+    };
+  } catch {
+    return { fork: false, checked: true };
+  }
+}

package/src/core/hooks/resolve/transcript.ts

@@ -356,6 +356,94 @@ const FORK_SCAN_MAX_BYTES = 128 * 1024 * 1024;
 /** How many message uuids to sample across the fork's copied prefix. */
 const FORK_SAMPLE_SIZE = 24;
 
+/** Tail window scanned for inherited rows; a fork's own rows are few when the
+ * scan runs (session start or the first tool call), so the copied history ends
+ * well inside it. */
+const INHERITED_TAIL_BYTES = 4 * 1024 * 1024;
+const INHERITED_HEAD_BYTES = 64 * 1024;
+const SESSION_ID_FIELD_RE =
+  /"sessionId":"([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})"/gi;
+
+/**
+ * Detect inherited history from row session ids: the session whose rows were
+ * copied into this transcript, or undefined when every row is this session's.
+ *
+ * Empirical basis (verified 2026-10-07, Claude Code 2.1.283): the desktop
+ * app's "Fork from here" copies the parent's rows into the fork's transcript
+ * WITHOUT rewriting their `sessionId`, so the fork's file opens with thousands
+ * of rows stamped with the parent's id. The CLI `--fork-session` path rewrites
+ * the ids instead and is covered by {@link detectForkParent}.
+ *
+ * When the history is itself several generations deep, the LAST foreign row is
+ * the nearest ancestor, so the tail is scanned first. Whether the foreign
+ * session is a fork parent or a dead predecessor (a continuation) is the
+ * caller's call. Fail-soft: never throws, undefined on any read problem.
+ */
+export function detectInheritedSessionParent(
+  transcriptPath: string | undefined,
+  sessionId: string,
+): string | undefined {
+  try {
+    const readablePath = resolveTranscriptPath(transcriptPath);
+    if (!readablePath || !sessionId) return undefined;
+    const size = statSync(readablePath).size;
+    const fromTail = lastForeignSessionId(
+      readRange(readablePath, Math.max(0, size - INHERITED_TAIL_BYTES), size),
+      sessionId,
+    );
+    if (fromTail || size <= INHERITED_TAIL_BYTES) return fromTail;
+    return lastForeignSessionId(
+      readRange(readablePath, 0, Math.min(size, INHERITED_HEAD_BYTES)),
+      sessionId,
+    );
+  } catch {
+    return undefined;
+  }
+}
+
+function lastForeignSessionId(text: string | undefined, sessionId: string): string | undefined {
+  if (!text) return undefined;
+  const own = sessionId.toLowerCase();
+  const lines = text.split("\n");
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i]!;
+    if (!line.includes('"sessionId":"')) continue;
+    let foreign = false;
+    for (const m of line.matchAll(SESSION_ID_FIELD_RE)) {
+      if (m[1]!.toLowerCase() !== own) foreign = true;
+    }
+    if (!foreign) continue;
+    // Confirm on the parsed row: a nested object can carry another session's
+    // id, but only the row's own top-level field says whose row it is. A
+    // partial line at a window edge fails to parse and is skipped.
+    try {
+      const row = JSON.parse(line) as { sessionId?: unknown };
+      if (typeof row.sessionId === "string" && row.sessionId.toLowerCase() !== own) {
+        return row.sessionId;
+      }
+    } catch {
+      /* torn line */
+    }
+  }
+  return undefined;
+}
+
+function readRange(path: string, start: number, end: number): string | undefined {
+  try {
+    const fs = require("node:fs") as typeof import("node:fs");
+    const fd = fs.openSync(path, "r");
+    try {
+      const buf = Buffer.alloc(Math.max(0, end - start));
+      fs.readSync(fd, buf, 0, buf.length, start);
+      return buf.toString("utf8");
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Detect the parent session of a forked CC conversation from its transcript.
  *

package/src/core/hooks/shell-rm.ts

@@ -0,0 +1,103 @@
+import { basename, shellCommandFromTool, tokenize } from "./shell-tokens.ts";
+
+/**
+ * Deny a shell `rm` and name the guarded replacement. The instructions have
+ * said "use <bin> rm instead of shell rm" since the command shipped, and
+ * agents still reached for bare rm several times a day, often on unquoted
+ * variable paths that Claude Code then stops on for a human prompt. A
+ * repeated, machine-detectable failure belongs in a gate, not more prose.
+ *
+ * This is a guardrail against the reflex, not a security boundary: it reads
+ * command positions only (so `git rm`, `docker rm`, and quoted examples pass),
+ * plus the `xargs rm`, `find -exec rm`, and `bash -c '...rm...'` shapes.
+ * HARNERY_ALLOW_RM=1 on the command is the deliberate override.
+ */
+
+const OVERRIDE = "HARNERY_ALLOW_RM=1";
+const SEPARATORS = new Set([";", "|", "||", "&", "&&", "(", ")", "{", "}"]);
+const KEYWORDS = new Set(["do", "if", "then", "elif", "else", "!", "while", "until", "time"]);
+const WRAPPERS = new Set(["command", "exec", "builtin", "nohup", "sudo", "doas", "env", "nice"]);
+// xargs options that consume the following token as their value.
+const XARGS_VALUE_FLAGS = new Set(["-n", "-I", "-L", "-P", "-d", "-E", "-s", "-a"]);
+
+function isRm(value: string, quoted: boolean): boolean {
+  return !quoted && basename(value) === "rm";
+}
+
+function invokesRm(source: string, depth = 0): boolean {
+  if (depth > 8) return false;
+  const tokens = tokenize(source);
+  if (tokens.some((t) => !t.quoted && t.value === OVERRIDE)) return false;
+  let start = true;
+  let afterWrapper = false;
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i]!;
+    if (token.operator) {
+      if (SEPARATORS.has(token.value)) {
+        start = true;
+        afterWrapper = false;
+      }
+      continue;
+    }
+    if (!start) continue;
+    if (!token.quoted) {
+      if (KEYWORDS.has(token.value)) continue;
+      if (/^[A-Za-z_][A-Za-z_0-9]*=/.test(token.value)) continue;
+      if (afterWrapper && token.value.startsWith("-")) continue;
+    }
+    const name = basename(token.value);
+    if (WRAPPERS.has(name)) {
+      afterWrapper = true;
+      continue;
+    }
+    start = false;
+    afterWrapper = false;
+    if (isRm(token.value, token.quoted)) return true;
+    if (name === "xargs") {
+      for (let j = i + 1; j < tokens.length && !tokens[j]!.operator; j++) {
+        const arg = tokens[j]!;
+        if (arg.value.startsWith("-")) {
+          if (XARGS_VALUE_FLAGS.has(arg.value)) j++;
+          continue;
+        }
+        if (isRm(arg.value, arg.quoted)) return true;
+        break;
+      }
+    }
+    if (name === "find") {
+      for (let j = i + 1; j < tokens.length && !tokens[j]!.operator; j++) {
+        if (!/^-(?:exec|execdir|ok|okdir)$/.test(tokens[j]!.value)) continue;
+        const next = tokens[j + 1];
+        if (next && !next.operator && isRm(next.value, next.quoted)) return true;
+      }
+    }
+    if (["bash", "sh", "dash", "zsh", "ksh"].includes(name)) {
+      for (let j = i + 1; j < tokens.length && !tokens[j]!.operator; j++) {
+        if (/^-[a-z]*c[a-z]*$/.test(tokens[j]!.value)) {
+          const script = tokens[j + 1];
+          if (script && !script.operator && invokesRm(script.value, depth + 1)) return true;
+          break;
+        }
+      }
+    }
+  }
+  return false;
+}
+
+export function shellRmReason(
+  toolName: unknown,
+  toolInput: unknown,
+  binName: string,
+): string | null {
+  const command = shellCommandFromTool(toolName, toolInput);
+  if (command === null || !invokesRm(command)) return null;
+  return (
+    `Shell rm blocked: it skips the resolved-path, Git-ownership, and peer-claim checks, and an ` +
+    `unquoted variable path can expand to the wrong target. Use the guarded paths instead: ` +
+    `\`${binName} rm --root <directory> <paths...>\` previews removal of untracked files (add ` +
+    `--yes to delete, -r for a directory); \`git rm\` removes tracked source; ` +
+    `\`${binName} artifacts discard <id>\` retires managed evidence. To replace a file, overwrite ` +
+    `it in place or \`mv\` the new file over the old one, so nothing needs deleting. If none of ` +
+    `these fit, prefix the command with ${OVERRIDE}.`
+  );
+}

package/src/core/hooks/shell-tokens.ts

@@ -0,0 +1,96 @@
+/** Shared, deliberately small shell lexer for PreToolUse command guards. */
+
+export interface Token {
+  value: string;
+  quoted: boolean;
+  operator?: boolean;
+}
+
+/** Keep quoted arguments opaque, including examples and heredoc bodies. */
+export function tokenize(source: string): Token[] {
+  const out: Token[] = [];
+  const heredocs: { end: string; tabs: boolean }[] = [];
+  for (let i = 0; i < source.length; ) {
+    const ch = source[i]!;
+    if (ch === "\\" && source[i + 1] === "\n") {
+      i += 2;
+      continue;
+    }
+    if (ch === "\n") {
+      out.push({ value: ";", quoted: false, operator: true });
+      i++;
+      for (const doc of heredocs.splice(0)) {
+        while (i < source.length) {
+          const end = source.indexOf("\n", i);
+          const stop = end === -1 ? source.length : end;
+          const line = source.slice(i, stop);
+          i = end === -1 ? source.length : end + 1;
+          if ((doc.tabs ? line.replace(/^\t+/, "") : line) === doc.end) break;
+        }
+      }
+      continue;
+    }
+    if (/\s/.test(ch)) {
+      i++;
+      continue;
+    }
+    if (ch === "#") {
+      const end = source.indexOf("\n", i);
+      i = end === -1 ? source.length : end;
+      continue;
+    }
+    if (";|&(){}<>".includes(ch)) {
+      const op = source.slice(i).match(/^(?:<<-?|>>|&&|\|\||[;|&(){}<>])/)![0];
+      out.push({ value: op, quoted: false, operator: true });
+      i += op.length;
+      continue;
+    }
+    let value = "";
+    let quoted = false;
+    while (i < source.length && !/[\s;|&(){}<>]/.test(source[i]!)) {
+      const next = source[i++]!;
+      if (next === "'" || next === '"' || next === "`") {
+        quoted = true;
+        while (i < source.length && source[i] !== next) {
+          if (source[i] === "\\" && next !== "'" && i + 1 < source.length) i++;
+          value += source[i++]!;
+        }
+        if (source[i] === next) i++;
+      } else if (next === "\\" && i < source.length) {
+        const escaped = source[i++]!;
+        if (escaped !== "\n") value += escaped;
+      } else {
+        value += next;
+      }
+    }
+    const previous = out.at(-1)?.value;
+    if (previous === "<<" || previous === "<<-") {
+      heredocs.push({ end: value, tabs: previous === "<<-" });
+    }
+    out.push({ value, quoted });
+  }
+  return out;
+}
+
+export function basename(value: string): string {
+  return value.split(/[\\/]/).at(-1) ?? value;
+}
+
+/** The command string of a Bash-style tool call, or null for any other tool. */
+export function shellCommandFromTool(toolName: unknown, toolInput: unknown): string | null {
+  if (typeof toolName !== "string") return null;
+  const name = toolName.toLowerCase().replace(/^functions\./, "");
+  if (!["bash", "shell", "shell_command", "exec_command"].includes(name)) return null;
+  let input = toolInput;
+  if (typeof input === "string") {
+    try {
+      input = JSON.parse(input);
+    } catch {
+      return null;
+    }
+  }
+  if (!input || typeof input !== "object") return null;
+  const args = input as Record<string, unknown>;
+  const command = args.command ?? args.cmd;
+  return typeof command === "string" ? command : null;
+}