@staix/agent-hub 0.12.21 → 0.12.23

package/src/cli/help.ts

@@ -7,7 +7,7 @@ export interface HelpEntry { section: string; usage: string; description: string
 const SECTIONS: [string, [usage: string, description: string][]][] = [
   ["Projects", [
     ["ahub --project <path|id> <command>", "select a repository or worktree explicitly"],
-    ["ahub projects [--json]", "list registered projects and live status"],
+    ["ahub projects [--json] [--color=auto|always|never]", "list registered projects and live status"],
     ["ahub projects remove <id>", "forget a stopped registration (keeps project files)"],
     ["ahub setup [--yes]", "install or update the Claude Code channel plugin from this package, then run doctor"],
     ["ahub init [--dry-run --json]", "preview or write .agenthub/config.json and the AGENTS.md marker block (drops a legacy CLAUDE.md block)"],
@@ -17,18 +17,18 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
   ["Daemon and runtime", [
     ["ahub up [--unattended] [--no-console]", "start the daemon; interactive terminals enter console"],
     ["ahub console [--panels] [--color=auto|always|never]", "enter the human console, leaving the daemon running on exit"],
-    ["ahub status", "the hub, its peers, model backends and task counts"],
-    ["ahub status --all", "show every registered project"],
+    ["ahub status [--json] [--full] [--color=auto|always|never]", "the hub, its peers, model backends and task counts"],
+    ["ahub status --all [--json] [--color=auto|always|never]", "show every registered project"],
     ["ahub logs [-f]", "the last 100 lines of hub.log; -f shows the last 10 and follows it"],
-    ["ahub doctor", "check the tools, daemon, plugin, gateway, models and memory worker this project uses"],
-    ["ahub doctor --orphans [--kill]", "list registrations whose project root is gone; --kill stops their daemons (SIGTERM, then SIGKILL) only after the process identity checks out"],
+    ["ahub doctor [--json] [--color=auto|always|never]", "check the tools, daemon, plugin, gateway, models and memory worker this project uses"],
+    ["ahub doctor --orphans [--kill] [--json] [--color=auto|always|never]", "list registrations whose project root is gone; --kill stops their daemons (SIGTERM, then SIGKILL) only after the process identity checks out"],
     ["ahub kill", "stop this project's hub"],
     ["ahub reset [--all] [--yes]", "list, then with --yes stop the hub and discard every queued and needs_review delivery, clear holds and pauses and drop session pointers; --all moves the state directory to .agenthub/archive instead"],
-    ["ahub restart [--dry-run] [--yes]", "recover this project's runtime"],
-    ["ahub upgrade --to <version> [--dry-run] [--yes]", "review and upgrade running projects"],
-    ["ahub recovery status|resume|abort <operation-id>", "inspect, resume or cancel a preflight; status names the next actions"],
-    ["ahub recovery dispose <operation-id> --fresh-session codex|claude --reason <text>", "end a partial operation by starting that peer as a new session, recording the lost conversation"],
-    ["ahub recovery dispose <operation-id> --stop-and-archive --reason <text>", "end a partial operation: stop its own targets, archive its snapshot and release the lock; the upgrade is abandoned, not completed"],
+    ["ahub restart [--dry-run] [--yes]", "recover this project's runtime; on a terminal without a flag it reviews the plan with you, follows the progress and offers the next steps"],
+    ["ahub upgrade [--to <version>] [--dry-run] [--yes]", "review and upgrade running projects; --to defaults to the latest release (--yes needs it), and a newer release's own coordinator takes over; on a terminal without --dry-run or --yes: review, end agents first if you choose, apply, follow, and resume, cancel, end or reset on the spot"],
+    ["ahub recovery [status|resume|abort] [<operation-id>]", "inspect, resume or cancel a preflight; status names the next actions; without an id, the operation that holds the lock, and with nothing else on a terminal its screen"],
+    ["ahub recovery dispose [<operation-id>] --fresh-session codex|claude --reason <text>", "end a partial operation by starting that peer as a new session, recording the lost conversation"],
+    ["ahub recovery dispose [<operation-id>] --stop-and-archive --reason <text>", "end a partial operation: stop its own targets, archive its snapshot and release the lock; the upgrade is abandoned, not completed"],
     ["ahub daemon [--unattended]", "internal: the detached hub process that ahub up or the dashboard manager starts"],
     ["ahub recovery-run <operation-id>", "internal: the detached runner of an upgrade, restart or recovery resume"],
   ]],
@@ -36,22 +36,26 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub claude [--print-command] [--unattended] [args...]", "launch Claude Code with the hub channel"],
     ["ahub codex [--print-command] [--unattended] [args...]", "start the Codex adapter and attach the TUI"],
     ["ahub kimi [--print-command] [--model <alias>]", "start Kimi headless under ACP"],
-    ["ahub pi [--print-command] [--mode headless|tui] [--backend auto|dgx|mlx] [--session-id <id>] [--session-file <path>]", "start Pi"],
+    ["ahub pi [--print-command] [--mode headless|tui | --headless] [--backend auto|dgx|mlx] [--session-id <id>] [--session-file <path>]", "start Pi: its TUI in this terminal unless --headless or the start mode setting (peers.pi.start_mode) says headless; without a terminal the hub opens one or says how"],
     ["ahub local [--route <id> | --model <id>]", "start the hub-native worker on the self-hosted models (routing.toml)"],
-    ["ahub models setup|status|start|stop", "prepare or inspect local Ollama MLX (legacy stop is explicit)"],
+    ["ahub stop <peer>", "human only: stop a hub-owned headless peer; end TUI agents in their terminals"],
+    ["ahub models status [--json] [--color=auto|always|never]", "inspect local model state as labelled fields"],
+    ["ahub models setup|start|stop", "prepare or inspect local Ollama MLX (legacy stop is explicit)"],
   ]],
   ["Messages and approvals", [
     ["ahub say [@peer ...] <text>", "send as the console user (no @peer = broadcast); delivered at once, start the text with [STATUS] to let it batch or [FYI] for the record only"],
     ["ahub tail", "live stream of messages, states and permission requests"],
     ["ahub permission [<peer> [ask|ask-when-needed|never-ask]] [--yes]", "human only: inspect or set a running peer mode; never-ask requires --yes; config never-ask waits for console y"],
     ["ahub permit <id> <option>", "answer a permission request shown by tail (\"deny\" cancels)"],
+    ["ahub settings [list] [--json] | get <key>", "human only: the settings the dashboard can change, each with its value, the file it comes from and when it applies"],
+    ["ahub settings set <key> <value|inherit> [--yes] [--preview] | undo", "human only: change one, written to .agenthub/config.local.json or routing.local.toml (never a tracked file); --preview shows the effect and saves nothing; undo puts back the last write"],
     ["ahub pause|resume <peer>", "hold a peer's deliveries in its queue / release them"],
-    ["ahub queue list [--peer <id>] [--json]", "inspect durable deliveries"],
-    ["ahub queue show <delivery-id>", "inspect one delivery and revision"],
+    ["ahub queue list [--peer <id>] [--json] [--color=auto|always|never]", "inspect durable deliveries"],
+    ["ahub queue show <delivery-id> [--json] [--color=auto|always|never]", "inspect one delivery and revision"],
     ["ahub queue resolve <delivery-id> --action completed|retry|discard --reason <text>", "release a delivery held as needs_review: mark it completed, retry it or discard it"],
   ]],
   ["Tasks and review", [
-    ["ahub board [state | --ready]", "the task board; --ready: proposed tasks with nothing left to wait for"],
+    ["ahub board [state | --ready] [--json] [--color=auto|always|never]", "the task board; --ready: proposed tasks with nothing left to wait for"],
     ["ahub task propose [--class <c> | <class>] <title...> [--owner <peer>] [--path <p>]... [--after <id>]... [--urgent] [--detail <text>]", "put a task on the board; a first word that names a class is taken as the class; while a task named by --after is not approved yet, --owner reserves the task for that peer, offered to it first once it is ready; otherwise --owner assigns it now"],
     ["ahub task show|escalate <id>", "full task with history (PII text included) / hand it to the next peer in escalate_to"],
     ["ahub task assign <id> <peer>", "give a task to a peer yourself; a task that still waits is reserved for that peer instead"],
@@ -63,15 +67,16 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub remember <text...>", "save a note to the memory all agents share"],
   ]],
   ["Budget", [
-    ["ahub budget", "quota windows per peer, and who is paused until when"],
+    ["ahub budget [--json] [--color=auto|always|never]", "quota windows per peer, and who is paused until when"],
     ["ahub budget set <peer> <0..1> [--resets-in 30m] [--window 5h|week]", "feed a reading by hand (also: test the relay)"],
     ["ahub budget resume <peer>", "override a budget pause; readings are ignored for that peer until the window resets"],
-    ["ahub budget execution configure <config.json> | status [id] | disable <id>", "opt-in limits on model calls, tool calls, time and tokens for pi and local"],
+    ["ahub budget execution status [id] [--json] [--color=auto|always|never]", "read execution counters and limits"],
+    ["ahub budget execution configure <config.json> | disable <id>", "opt-in limits on model calls, tool calls, time and tokens for pi and local"],
   ]],
   ["History and reports", [
-    ["ahub turns [peer] [--limit N]", "recent turns and the files each changed (a git work tree only)"],
+    ["ahub turns [peer] [--limit N] [--json] [--color=auto|always|never]", "recent turns and the files each changed (a git work tree only)"],
     ["ahub undo <turn> [--yes] [--context]", "put back the files a turn changed; refuses files changed since. Without --yes it only lists them; --context also drops a Codex turn from its conversation"],
-    ["ahub report [--since 7d|<iso>] [--by task] [--json]", "turns, tokens, messages, overlaps and task events per period"],
+    ["ahub report [--since 7d|<iso>] [--by task] [--json] [--color=auto|always|never]", "turns, tokens, messages, overlaps and task events per period"],
     ["ahub export [--since 7d|<iso>]", "structured events (events.jsonl) as JSON lines; never message bodies"],
     ["ahub research [--since 30d] [--all] [--json]", "success, first-pass, rework and check-failure rates, tokens and wall time per approved task, from the opt-in research records"],
     ["ahub research export [--format jsonl|csv] [--since 30d] [--all]", "the research records for outside analysis: ids, counts and tokens, never text"],
@@ -89,6 +94,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
   ]],
   ["Dashboard", [
     ["ahub ui [--no-open]", "open the local dashboard (or print its one-time link)"],
+    ["ahub ui --settings [--no-open]", "human only: open it with a settings session, which for 15 minutes may change permission modes, routing and start settings"],
     ["ahub ui --all [--no-open]", "open the unified project dashboard"],
     ["ahub ui --all --stop", "stop only the dashboard manager"],
     ["ahub manager", "internal: the dashboard manager process that ahub ui --all starts"],

package/src/cli/identity.ts

@@ -26,7 +26,7 @@ export type PeerCommandAccess = "allowed" | "conductor" | "console";
 
 /** A closed list: unknown commands cannot acquire console authority through an agent shell. */
 export function classifyPeerCommand(command: string, args: readonly string[]): PeerCommandAccess {
-  if (command === "permission") return "console";
+  if (command === "permission" || command === "stop") return "console";
   if (args.some((arg) => arg === "--as-user" || arg.startsWith("--as-user="))) return "console";
   if (command === "task") {
     if (["propose", "show"].includes(args[0] ?? "")) return "allowed";
@@ -39,7 +39,7 @@ export function classifyPeerCommand(command: string, args: readonly string[]): P
   // #251: a run resets the bench project's tree and proposes work; reading results is harmless.
   // The subcommand is the first argument that is not --json, which the command accepts anywhere.
   if (command === "bench") return args.find((arg) => arg !== "--json") === "run" ? "console" : "allowed";
-  if (command === "budget") return !args.length || args.every((arg) => arg === "--json") ? "allowed" : "console";
+  if (command === "budget") return !args.length || args.every((arg) => arg === "--json" || arg === "--full" || arg.startsWith("--color=")) ? "allowed" : "console";
   if (["claude", "codex", "kimi", "pi", "local", "pause", "resume"].includes(command)) return "conductor";
   if (["help", "version", "--version", "say", "status", "board", "report", "turns", "review", "remember", "facts", "check-path"].includes(command)) return "allowed";
   return "console";
@@ -47,7 +47,7 @@ export function classifyPeerCommand(command: string, args: readonly string[]): P
 
 /** No argument text is included: notices and refusal logs must not copy task text or credentials. */
 export function cliCommandLabel(command: string, args: readonly string[]): string {
-  if (!["upgrade", "restart", "recovery", "recovery-run", "help", "--help", "--version", "version", "projects", "ui", "manager", "setup", "init", "daemon", "up", "console", "claude", "codex", "kimi", "pi", "local", "models", "say", "queue", "tail", "budget", "board", "task", "review", "remember", "ask", "route", "pause", "resume", "permit", "permission", "status", "logs", "export", "report", "research", "bench", "facts", "check-path", "turns", "undo", "kill", "reset", "doctor"].includes(command)) return "unknown";
+  if (!["upgrade", "restart", "recovery", "recovery-run", "help", "--help", "--version", "version", "projects", "ui", "manager", "setup", "init", "daemon", "up", "console", "claude", "codex", "kimi", "pi", "local", "stop", "models", "say", "queue", "tail", "budget", "board", "task", "review", "remember", "ask", "route", "pause", "resume", "permit", "permission", "settings", "status", "logs", "export", "report", "research", "bench", "facts", "check-path", "turns", "undo", "kill", "reset", "doctor"].includes(command)) return "unknown";
   if (["task", "queue", "budget", "route", "recovery", "models", "projects", "research", "bench"].includes(command)) {
     const sub = command === "bench" ? args.find((arg) => arg !== "--json") : args[0];
     if (sub && ["propose", "show", "assign", "escalate", "label", "list", "resolve", "resume", "set", "execution", "explain", "status", "abort", "dispose", "setup", "start", "stop", "remove", "export", "backfill", "run", "report", "compare"].includes(sub)) return `${command} ${sub}`;

package/src/cli/init.ts

@@ -57,7 +57,7 @@ function changes(cwd: string): PlannedWrite[] {
   }
   const ignore = join(cwd, ".gitignore");
   let lines = existsSync(ignore) ? readFileSync(ignore, "utf8") : "";
-  for (const entry of [".agenthub/state/", ".agenthub/config.local.json"]) {
+  for (const entry of [".agenthub/state/", ".agenthub/config.local.json", ".agenthub/routing.local.toml"]) {
     if (!lines.split("\n").includes(entry)) lines = `${lines}${lines && !lines.endsWith("\n") ? "\n" : ""}${entry}\n`;
   }
   write(ignore, lines, "ignore runtime state and machine-local configuration");

package/src/cli/launch.ts

@@ -1,10 +1,11 @@
 // Launchers inject only the flags the hub owns and refuse user-supplied duplicates.
-import { mkdirSync, writeFileSync, renameSync, unlinkSync, lstatSync, readFileSync } from "node:fs";
-import { randomUUID } from "node:crypto";
+import { mkdirSync, writeFileSync, renameSync, unlinkSync, lstatSync, readFileSync, openSync, closeSync, readSync, accessSync, constants, linkSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { randomUUID, createHash } from "node:crypto";
 import { resolve, join, basename, dirname, isAbsolute } from "node:path";
 import { processLiveness, processSignature } from "../pi/process-signature.ts";
 import { realPath } from "../hub/project.ts";
-import { peerChildEnv } from "../hub/child-process.ts";
+import { peerChildEnv, processTable } from "../hub/child-process.ts";
 export const CLAUDE_CHANNEL = "plugin:agent-hub@agent-hub";
 
 /** Launch identity belongs to the native child, never to the agent that invoked the wrapper. */
@@ -65,14 +66,188 @@ export function cleanupClaudeSettings(stateDir: string, previous: unknown): void
 /** Crash fallback only: an absent/unreadable owner identity never certifies that its native launch ended. */
 export function cleanupStaleClaudeSettings(stateDir: string, previous: unknown, identity = processSignature): void {
   if (!previous || typeof previous !== "object" || Array.isArray(previous)) return;
-  const record = previous as Record<string, unknown>;
+  const original = previous as Record<string, unknown>;
+  const record = readClaudeNative(stateDir, original as ClaudeLaunchRecord) ?? original;
   if (typeof record.launcherSignature !== "string" || !record.launcherSignature) return;
   if (processLiveness(record.launcherPid, record.launcherSignature, identity) !== "gone") return;
-  // ponytail: spawnSync launch records have no independent native identity, so crash-left settings are retained.
-  // Upgrade path: record the native child's PID and processSignature before admitting crash fallback cleanup.
   if (typeof record.nativePid !== "number" || !Number.isSafeInteger(record.nativePid) || record.nativePid <= 0 || record.nativePid === record.launcherPid || typeof record.nativeSignature !== "string" || !record.nativeSignature) return;
-  if (processLiveness(record.nativePid, record.nativeSignature, identity) !== "gone") return;
+  if (record.nativeIdentity === "direct-child") {
+    // A direct child may exec in place. A changed signature while its PID still runs cannot certify native exit.
+    // The shared table excludes exited zombies; an unavailable table certifies nothing.
+    const table = processTable();
+    if (!table || table.some(row => row.pid === record.nativePid)) return;
+  } else if (processLiveness(record.nativePid, record.nativeSignature, identity) !== "gone") return;
   cleanupClaudeSettings(stateDir, record.settingsFile);
+  removeClaudeNative(stateDir, original as ClaudeLaunchRecord);
+}
+
+export interface ClaudeLaunchRecord extends Record<string, unknown> {
+  instanceId: string; launchId: string; settingsFile?: string; launcherPid: number; launcherSignature?: string;
+}
+
+export interface ClaudeLaunchPublication { recorded: boolean; warning?: string; }
+
+/** Native attestation alone is serialized; managed hook metadata never waits on this lock. */
+async function withClaudeLaunchRecord(stateDir: string, action: () => void): Promise<ClaudeLaunchPublication> {
+  const lock = join(stateDir, "claude-launch.lock"), temp = `${lock}.${randomUUID()}.tmp`;
+  const skipped = (reason = `${lock} is busy or unverified`): ClaudeLaunchPublication => ({ recorded: false, warning: `Native identity and crash cleanup disabled for this launch; managed hook record stays current. ${reason}; inspect ${lock} and verify its owner has ended before removing it.` });
+  const signature = processSignature(process.pid);
+  if (!signature) return skipped("launcher identity could not be verified");
+  let locked = false, tempCreated = false, own: { dev: number; ino: number } | undefined;
+  try {
+    const fd = openSync(temp, "wx", 0o600); tempCreated = true;
+    try { writeFileSync(fd, JSON.stringify({ pid: process.pid, signature })); } finally { closeSync(fd); }
+    const stat = lstatSync(temp); own = { dev: stat.dev, ino: stat.ino };
+    const deadline = performance.now() + 250;
+    for (;;) {
+      try { linkSync(temp, lock); break; }
+      catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "EEXIST") return skipped();
+        let before;
+        try { before = lstatSync(lock); } catch { if (performance.now() < deadline) continue; return skipped(); }
+        if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1 || (before.mode & 0o777) !== 0o600 || !process.getuid || before.uid !== process.getuid()) return skipped();
+        let owner: { pid?: unknown; signature?: unknown };
+        try { owner = JSON.parse(readFileSync(lock, "utf8")); } catch { return skipped(); }
+        if (!owner || typeof owner.signature !== "string" || !owner.signature) return skipped();
+        const alive = processLiveness(owner.pid, owner.signature);
+        if (alive === "unknown") return skipped();
+        if (alive === "live") {
+          if (performance.now() >= deadline) return skipped();
+          await new Promise(resolve => setTimeout(resolve, 25)); continue;
+        }
+        const current = lstatSync(lock);
+        if (current.dev !== before.dev || current.ino !== before.ino) return skipped();
+        unlinkSync(lock);
+      }
+    }
+    locked = true;
+    unlinkSync(temp);
+    try { action(); } catch { return skipped("native attestation publication failed"); }
+    return { recorded: true };
+  } catch { return skipped("native attestation lock could not be read or published"); }
+  finally {
+    if (locked && own) {
+      try { const current = lstatSync(lock); if (current.dev === own.dev && current.ino === own.ino) unlinkSync(lock); }
+      catch { /* only our verified lock may be removed */ }
+    }
+    if (tempCreated) { try { unlinkSync(temp); } catch { /* our populated temp may already be linked and consumed */ } }
+  }
+}
+
+function writeClaudeLaunchRecord(stateDir: string, record: Record<string, unknown>): void {
+  const file = join(stateDir, "claude-launch.json"), temp = `${file}.${randomUUID()}.tmp`;
+  try { writeFileSync(temp, JSON.stringify(record), { mode: 0o600 }); renameSync(temp, file); }
+  finally { try { unlinkSync(temp); } catch { /* the rename normally consumed it */ } }
+}
+
+export function recordClaudeLaunch(stateDir: string, record: ClaudeLaunchRecord): ClaudeLaunchPublication {
+  writeClaudeLaunchRecord(stateDir, record);
+  return { recorded: true };
+}
+
+function sameClaudeLaunch(left: ClaudeLaunchRecord, right: ClaudeLaunchRecord): boolean {
+  return left.instanceId === right.instanceId && left.launchId === right.launchId && left.settingsFile === right.settingsFile
+    && left.launcherPid === right.launcherPid && left.launcherSignature === right.launcherSignature;
+}
+function nativeAttestationPath(stateDir: string, launch: ClaudeLaunchRecord): string {
+  const hash = createHash("sha256").update(JSON.stringify([launch.instanceId, launch.launchId, launch.settingsFile, launch.launcherPid, launch.launcherSignature])).digest("hex");
+  return join(stateDir, `claude-native-${hash}.json`);
+}
+function privateClaudeNative(stateDir: string, launch: ClaudeLaunchRecord): { file: string; stat: ReturnType<typeof lstatSync>; record: ClaudeLaunchRecord } | undefined {
+  const file = nativeAttestationPath(stateDir, launch);
+  try {
+    const stat = lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || (stat.mode & 0o777) !== 0o600 || !process.getuid || stat.uid !== process.getuid()) return;
+    const record = JSON.parse(readFileSync(file, "utf8")) as ClaudeLaunchRecord;
+    if (!record || !sameClaudeLaunch(record, launch) || typeof record.nativePid !== "number" || !Number.isSafeInteger(record.nativePid) || record.nativePid <= 0 || typeof record.nativeSignature !== "string" || !record.nativeSignature || record.nativeIdentity !== "direct-child") return;
+    return { file, stat, record };
+  } catch { return; }
+}
+export function readClaudeNative(stateDir: string, launch: ClaudeLaunchRecord): ClaudeLaunchRecord | undefined {
+  return privateClaudeNative(stateDir, launch)?.record;
+}
+function removeClaudeNative(stateDir: string, launch: ClaudeLaunchRecord): void {
+  const saved = privateClaudeNative(stateDir, launch); if (!saved?.stat) return;
+  try { const now = lstatSync(saved.file); if (now.dev === saved.stat.dev && now.ino === saved.stat.ino) unlinkSync(saved.file); }
+  catch { /* absent or replaced native proof remains untouched */ }
+}
+
+/** Never attach an old child's identity to a replacement launch, even when its spawn callback arrives later. */
+export async function recordClaudeNative(stateDir: string, launch: ClaudeLaunchRecord, pid: number, signature: string, report?: (warning: string) => void): Promise<boolean> {
+  let recorded = false;
+  const publication = await withClaudeLaunchRecord(stateDir, () => {
+    let current: ClaudeLaunchRecord;
+    try {
+      const file = join(stateDir, "claude-launch.json"), stat = lstatSync(file);
+      if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || (stat.mode & 0o777) !== 0o600 || !process.getuid || stat.uid !== process.getuid()) return;
+      current = JSON.parse(readFileSync(file, "utf8"));
+    } catch { return; }
+    if (!sameClaudeLaunch(current, launch)) return;
+    if (!Number.isSafeInteger(pid) || pid <= 0 || pid === launch.launcherPid || !signature) return;
+    const file = nativeAttestationPath(stateDir, launch), temp = `${file}.${randomUUID()}.tmp`;
+    try {
+      lstatSync(file);
+      const saved = privateClaudeNative(stateDir, launch);
+      recorded = !!saved && saved.record.nativePid === pid && saved.record.nativeSignature === signature;
+      return; // a launch's first native proof is immutable; an unknown file is never overwritten
+    } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") return; }
+    try {
+      writeFileSync(temp, JSON.stringify({ ...launch, nativePid: pid, nativeSignature: signature, nativeIdentity: "direct-child" }), { mode: 0o600, flag: "wx" });
+      renameSync(temp, file);
+    } finally { try { unlinkSync(temp); } catch { /* atomic rename consumed our private temporary file */ } }
+    try { recorded = sameClaudeLaunch(JSON.parse(readFileSync(join(stateDir, "claude-launch.json"), "utf8")), launch); } catch { /* replaced or unreadable managed record */ }
+  });
+  if (publication.warning) report?.(publication.warning);
+  return publication.recorded && recorded;
+}
+
+/** Scripts and interpreters can leave a different native owner behind: their crash cleanup remains disabled. */
+function directNativeExecutable(command: string, cwd: string, env: NodeJS.ProcessEnv): boolean {
+  const interpreter = /^(?:node|bun|deno|env|busybox|python(?:[0-9.]+)?|ruby|perl|bash|sh|zsh|fish|dash|ksh|csh|tcsh|ash)(?:\.exe)?$/;
+  if (interpreter.test(basename(command))) return false;
+  const paths = command.includes("/") ? [resolve(cwd, command)] : (env.PATH ?? "").split(":").filter(Boolean).map(path => resolve(cwd, path, command));
+  for (const path of paths) {
+    let fd: number | undefined;
+    try {
+      const target = realPath(path);
+      accessSync(target, constants.X_OK);
+      if (interpreter.test(basename(target))) return false;
+      fd = openSync(target, "r");
+      const bytes = Buffer.alloc(4); if (readSync(fd, bytes, 0, 4, 0) !== 4) return false;
+      return ["7f454c46", "feedface", "cefaedfe", "feedfacf", "cffaedfe", "cafebabe", "bebafeca", "cafebabf", "bfbafeca"].includes(bytes.toString("hex"));
+    } catch { /* resolve the next PATH entry */ }
+    finally { if (fd !== undefined) closeSync(fd); }
+  }
+  return false;
+}
+
+/** Same native stdio/environment and exit result as spawnSync, with a live child identity before it exits. */
+export async function runClaudeLaunch(launch: Launch, options: { cwd: string; env: NodeJS.ProcessEnv; stateDir: string; record?: ClaudeLaunchRecord }): Promise<{ status: number | null; signal: NodeJS.Signals | null; error?: Error }> {
+  const direct = directNativeExecutable(launch.cmd, options.cwd, options.env);
+  return new Promise(resolveResult => {
+    let attestation: Promise<unknown> | undefined;
+    let childSignature: string | undefined;
+    const child = spawn(launch.cmd, launch.args, { cwd: options.cwd, env: options.env, stdio: "inherit" });
+    child.once("spawn", () => {
+      if (!options.record || !child.pid) return;
+      const unavailable = (reason: string) => console.error(`Native identity and crash cleanup disabled for this launch; managed hook record stays current. ${reason}.`);
+      if (!direct) { unavailable("native executable is a script or an unverified interpreter"); return; }
+      if (!options.record.launcherSignature) { unavailable("launcher identity could not be verified"); return; }
+      const signature = processSignature(child.pid);
+      if (!signature) { unavailable("native process identity could not be verified"); return; }
+      childSignature = signature;
+      attestation = recordClaudeNative(options.stateDir, options.record, child.pid, signature, warning => console.error(warning)).catch(() => undefined);
+    });
+    child.once("error", error => resolveResult({ status: null, signal: null, error }));
+    child.once("exit", async (status, signal) => {
+      await attestation;
+      if (options.record) {
+        const saved = readClaudeNative(options.stateDir, options.record);
+        if (saved && typeof child.pid === "number" && saved.nativePid === child.pid && saved.nativeSignature === childSignature) removeClaudeNative(options.stateDir, options.record);
+      } // this child's observed exit, after its last bounded write
+      resolveResult({ status, signal });
+    });
+  });
 }
 
 export interface StatusLineTee {