@staix/agent-hub 0.12.44 → 0.13.0

package/src/cli/upgrade-labels.ts

@@ -20,7 +20,7 @@ export function operationLines(op: RecoveryOperation, runner: number | "unknown"
   const held = runner === "unknown" ? "; whether a runner holds it cannot be read" : runner ? `; runner ${runner} is working` : op.phase === "running" ? "; no runner holds it (the last one stopped mid-step)" : "";
   const lines = [`${op.plan.kind} to ${op.plan.version}: operation ${op.id}`, `  ${op.phase} at "${stepLabel(op.step)}", updated ${ago(now - op.updatedAt)} ago${held}`];
   for (const p of op.projects) {
-    const effects = Object.entries(p.terminals).map(([key, value]) => key.startsWith("restored:") ? `${key} ${restoreReceiptStatus(value)}` : value === "pending" || value === "failed" ? `${key} ${value}` : key);
+    const effects = Object.entries(p.terminals).map(([key, value]) => key.startsWith("restored:") ? `${key} ${restoreReceiptStatus(value, { authority: "historical" })}` : value === "pending" || value === "failed" ? `${key} ${value}` : key);
     lines.push(`  ${p.id}  ${p.phase}${effects.length ? `  (${effects.join(", ")})` : ""}${p.restarts?.length ? `  restarts ${p.restarts.length}` : ""}`);
   }
   // The error ends with the commands status would print; the menu below offers them instead.

package/src/cli/upgrade-presentation.ts

@@ -76,7 +76,7 @@ export function renderOperation(op: RecoveryOperation, runner: number | "unknown
       if (key.startsWith("restored:")) {
         let outcome = "recorded outcome unavailable";
         try {
-          const state = restoreReceiptStatus(value);
+          const state = restoreReceiptStatus(value, { authority: "historical" }); // display only: a revoked declaration must not hide the receipt (#225)
           outcome = state === "done" ? "session restored" : state === "failed" ? "session restoration needs attention" : state.startsWith("waiting:") ? "waiting for the recorded session to attach" : "session restoration is pending";
         } catch { /* Malformed historical metadata is unknown, never successful. */ }
         output.push(...lines(`  ${key.slice("restored:".length)}: ${outcome}`, "muted", options));

package/src/cli/upgrade-restore-state.ts

@@ -66,8 +66,9 @@ export function decodeRestoreReceipt(value: unknown, options: { authority?: "cur
   return { state: "done", binding: terminalBinding(value, historical) };
 }
 
-export function restoreReceiptStatus(value: unknown): RestoreReceiptStatus {
-  const receipt = decodeRestoreReceipt(value);
+/** The authority is the caller's: a decision reads the current one, a screen that only shows what was recorded reads the historical one (#225). */
+export function restoreReceiptStatus(value: unknown, options: { authority?: "current" | "historical" } = {}): RestoreReceiptStatus {
+  const receipt = decodeRestoreReceipt(value, options);
   return !receipt ? "unstarted" : receipt.state === "waiting" ? `waiting:${receipt.origin}` : receipt.state;
 }
 export function canChooseFresh(value: unknown): boolean {

package/src/cli/upgrade-runtime.ts

@@ -145,6 +145,7 @@ export async function endPlannedPeer(planned: PlannedProject, peer: RecoveryPeer
 /** Declared identities cannot be reinterpreted against an older running source's unbound peer rows. */
 export function instanceRecoverySourceRefusal(projectRoot: string, features: unknown, observedPeers?: unknown): string | undefined {
   const bound = readInstanceConfig(projectRoot);
+  if (bound.adapter_modules?.length && !(Array.isArray(features) && features.includes("external_adapter_modules"))) return "source lacks external_adapter_modules; restart with a supporting source before recovering module peers";
   const configured = Object.keys(bound.adapters ?? {});
   const configuredIds = [...configured, ...Object.entries(bound.instances ?? {}).filter(([, entry]) => configured.includes(entry.kind)).map(([id]) => id)];
   if (configuredIds.length && !(Array.isArray(features) && features.every(feature => typeof feature === "string") && features.includes("configured_acp"))) {
@@ -159,7 +160,7 @@ export function instanceRecoverySourceRefusal(projectRoot: string, features: unk
     if (peers.every(([, peer]) => !!peer && typeof peer === "object" && typeof (peer as { state?: unknown }).state === "string") &&
       !peers.some(([id, peer]) => declared.includes(id) && (peer as { state: string }).state !== "offline")) return undefined;
   }
-  return "source lacks peer_instances support for this project's declared instances; restart the source with a supporting agent-hub version before retrying recovery; for a first upgrade, end any extra native sessions and temporarily remove the instance declarations, upgrade the source, then declare them again; legacy peer identities were not reinterpreted";
+  return "source lacks peer_instances support and a declared instance of this project may be live; restart the source with a supporting agent-hub version before retrying recovery; for a first upgrade, end the extra native sessions first (a source whose declared instances are all offline proceeds without further steps); only if one cannot be ended, temporarily remove its declaration, upgrade the source, then declare it again; legacy peer identities were not reinterpreted";
 }
 
 export async function inspectRecovery(project: Project, targetFeatures?: readonly string[], purpose?: "cleanup"): Promise<Inspection> {
@@ -626,6 +627,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
         return { ...target, ...(op.targetFeatures === undefined ? {} : { targetFeatures: [...op.targetFeatures] }) };
       }
       if (cached && op.targetFeatures !== undefined) {
+        if (!op.targetFeatures.includes("external_adapter_modules") && op.plan.projects.some(planned => typeof planned.project?.root === "string" && (readInstanceConfig(planned.project.root).adapter_modules?.length ?? 0) > 0)) throw new FinalRefusal("target lacks external_adapter_modules; module peers require a supporting target before recovery effects");
         if (!op.targetFeatures.includes("configured_acp") && op.plan.projects.some(planned => typeof planned.project?.root === "string" && Object.keys(readInstanceConfig(planned.project.root).adapters ?? {}).length > 0)) throw new FinalRefusal("target lacks configured_acp; configured adapters require a supporting target before recovery effects");
         if (!op.targetFeatures.includes("peer_instances") && op.plan.projects.some(planned => typeof planned.project?.root === "string" && Object.keys(readInstanceConfig(planned.project.root).instances ?? {}).length > 0)) throw new FinalRefusal("target lacks peer_instances; declared project instances require a supporting target before recovery effects");
         return { ...target, targetFeatures: [...op.targetFeatures] };
@@ -638,6 +640,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
       if (!metadata || typeof metadata !== "object" || !Number.isInteger(metadata.protocol)) throw new Error(`the staged target's control protocol could not be read (probe exit ${probe.code}); staged package retained, runtimes unchanged; resume again once it can run`);
       if (!Array.isArray(metadata.features) || !metadata.features.every((feature: unknown) => typeof feature === "string" && feature.length > 0)) throw new Error("the staged target features could not be read; staged package retained, runtimes unchanged");
       const targetFeatures: readonly string[] = [...metadata.features];
+      if (!targetFeatures.includes("external_adapter_modules") && op.plan.projects.some(planned => typeof planned.project?.root === "string" && (readInstanceConfig(planned.project.root).adapter_modules?.length ?? 0) > 0)) throw new FinalRefusal("target lacks external_adapter_modules; module peers require a supporting target before recovery effects");
       if (!targetFeatures.includes("configured_acp") && op.plan.projects.some(planned => typeof planned.project?.root === "string" && Object.keys(readInstanceConfig(planned.project.root).adapters ?? {}).length > 0)) throw new FinalRefusal("target lacks configured_acp; configured adapters require a supporting target before recovery effects");
       if (metadata.protocol !== PROTOCOL) throw new FinalRefusal("target protocol requires a newer coordinator; staged package retained, runtimes unchanged");
       if (!targetFeatures.includes("peer_instances") && op.plan.projects.some(planned => typeof planned.project?.root === "string" && Object.keys(readInstanceConfig(planned.project.root).instances ?? {}).length > 0)) throw new FinalRefusal("target lacks peer_instances; declared project instances require a supporting target before recovery effects");

package/src/hub/action-class.ts

@@ -0,0 +1,362 @@
+import { basename, isAbsolute, relative, resolve } from "node:path";
+
+export const ACTION_CLASSES = ["publish", "external-write", "destroy", "install"] as const;
+export type ActionClass = typeof ACTION_CLASSES[number];
+
+const SHELL_TOOLS = new Set(["bash", "shell", "shell_command", "exec_command", "run_shell_command"]);
+const LIMIT = 16_384;
+type Command = { words: string[]; outputs: string[] };
+
+/** Bound the whole input before accepting any prefix, including unsupported suffixes. */
+function segmentLimit(text: string): boolean {
+  let quote = "", count = 0;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i]!;
+    if (c === "\\" && quote !== "'") { i++; continue; }
+    if (quote) { if (quote === c) quote = ""; continue; }
+    if (c === "'" || c === '"') { quote = c; continue; }
+    if (c === "#" && (i === 0 || /[ \t\r\n;]/.test(text[i - 1]!))) {
+      while (i < text.length && text[i] !== "\n") i++;
+    }
+    if (i < text.length && ";|&\n".includes(text[i]!)) {
+      // FD duplication is an operator, not another command.
+      if (text[i] === "&" && [">", "<"].includes(text[i - 1] ?? "")) continue;
+      if (++count > 64) return false;
+      if ((c === "|" || c === "&") && text[i + 1] === c) i++;
+    }
+  }
+  return true;
+}
+
+/** Literal shell words only; unsupported syntax discards only its unfinished segment. */
+function commands(text: string): Command[] | undefined {
+  if (text.length > LIMIT || text.includes("\0") || !segmentLimit(text)) return;
+  const result: Command[] = [];
+  let words: string[] = [], outputs: string[] = [], word = "", active = false, quote = "";
+  let redirect: false | "overwrite" | "skip" = false;
+  const flush = () => {
+    if (!active) return;
+    if (redirect === "overwrite") outputs.push(word);
+    else if (!redirect) words.push(word);
+    word = ""; active = false; redirect = false;
+  };
+  const finish = () => { flush(); if (words.length || outputs.length) result.push({ words, outputs }); words = []; outputs = []; };
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i]!;
+    if (quote === "'") { if (c === "'") quote = ""; else word += c; continue; }
+    if (c === "\\") {
+      const next = text[++i];
+      if (next === undefined) return result;
+      if (quote === '"' && !['$', '`', '"', "\\", "\n"].includes(next)) word += "\\";
+      if (next !== "\n") word += next;
+      active = true; continue;
+    }
+    if (c === "$" || c === "`") return result;
+    if (quote) { if (c === quote) quote = ""; else word += c; continue; }
+    if (c === "'" || c === '"') { quote = c; active = true; continue; }
+    if (c === "#" && !active) { while (i < text.length && text[i] !== "\n") i++; finish(); continue; }
+    if ("(){}".includes(c)) {
+      if (redirect && !active) return result;
+      finish(); continue;
+    }
+    if (c === ">" || c === "<") {
+      if (redirect && !active) return result;
+      if (redirect) flush();
+      if (c === "<" && text[i + 1] === "<") return result;
+      if (active && /^\d+$/.test(word)) { word = ""; active = false; } else flush();
+      if (text[i + 1] === "&") {
+        const duplicate = text.slice(i + 2).match(/^(?:\d+|-)(?=$|[ \t\r\n;|&(){}<>])/);
+        if (!duplicate) return result;
+        i += 1 + duplicate[0].length; continue;
+      }
+      redirect = c === "<" || text[i + 1] === ">" ? "skip" : "overwrite";
+      if (text[i + 1] === ">" || text[i + 1] === "|") i++;
+      continue;
+    }
+    if (/[ \t\r]/.test(c)) { flush(); continue; }
+    if (";|&\n".includes(c)) {
+      if (redirect && !active) return result;
+      finish();
+      if (text[i + 1] === c && (c === "|" || c === "&")) i++;
+      continue;
+    }
+    word += c; active = true;
+    if (words.length + outputs.length > 256) return result;
+  }
+  if (quote || (redirect && !active)) return result;
+  finish();
+  return result;
+}
+
+function object(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+function outside(target: string, root: string, cwd: string): boolean {
+  if (!isAbsolute(root) || !target || /[$`]/.test(target)) return false;
+  if (target.startsWith("~") || !cwd && !isAbsolute(target)) return true;
+  const rel = relative(resolve(root), resolve(cwd, target));
+  return rel === ".." || rel.startsWith("../") || isAbsolute(rel);
+}
+function flags(words: string[], letter: string): boolean {
+  const end = words.indexOf("--");
+  return words.slice(0, end < 0 ? undefined : end).some(w => /^-[^-]/.test(w) && w.slice(1).includes(letter));
+}
+function operands(words: string[]): string[] {
+  const end = words.indexOf("--");
+  return end < 0 ? words.filter(w => !w.startsWith("-")) : [...words.slice(0, end).filter(w => !w.startsWith("-")), ...words.slice(end + 1)];
+}
+function option(words: string[], short: string, long: string): string | undefined {
+  for (let i = 0; i < words.length; i++) {
+    const w = words[i]!;
+    if (w === "--") break;
+    if (w === short || w === long) return words[i + 1];
+    if (w.startsWith(`${long}=`)) return w.slice(long.length + 1);
+    if (w.startsWith(short) && w.length > short.length) return w.slice(short.length);
+  }
+  return;
+}
+/** Known option values are opaque. Unknown prefix options retain every plausible action head. */
+function commandHeads(words: string[], values: readonly string[], booleans: readonly string[], actions: readonly string[]): Array<{ name: string; args: string[] }> {
+  const heads: Array<{ name: string; args: string[] }> = [];
+  let uncertain = false, literal = false;
+  for (let i = 0; i < words.length; i++) {
+    const word = words[i]!;
+    if (!literal && word === "--") { literal = true; continue; }
+    if (!literal && word.startsWith("-")) {
+      if (!uncertain && ["--help", "--version", "-h", "-V"].includes(word)) return [];
+      if (values.includes(word)) { if (!uncertain) i++; continue; }
+      if (values.some(key => key.startsWith("--") ? word.startsWith(`${key}=`) : word.startsWith(key) && word.length > key.length)) continue;
+      if (!booleans.includes(word)) uncertain = true;
+      continue;
+    }
+    if (!uncertain) return [{ name: word, args: words.slice(i + 1) }];
+    if (actions.includes(word)) heads.push({ name: word, args: words.slice(i + 1) });
+  }
+  return heads;
+}
+
+/** Exclude patterns and path operands cannot impersonate clean's force/dry-run options. */
+function forcedClean(words: string[]): boolean {
+  let force = false, dry = false;
+  for (let i = 0; i < words.length; i++) {
+    const word = words[i]!;
+    if (word === "--") break;
+    if (word === "--exclude") { i++; continue; }
+    if (word.startsWith("--exclude=")) continue;
+    if (word === "--force") force = true;
+    else if (word === "--dry-run") dry = true;
+    else if (/^-[^-]/.test(word)) {
+      for (let at = 1; at < word.length; at++) {
+        const flag = word[at]!;
+        if (flag === "e") { if (at === word.length - 1) i++; break; }
+        if (flag === "f") force = true;
+        if (flag === "n") dry = true;
+      }
+    }
+  }
+  return force && !dry;
+}
+
+/** Peel only known transparent argv wrappers; no aliases or executable discovery. */
+function unwrapped(input: string[]): string[] {
+  const words = [...input];
+  for (let step = 0; step < 32; step++) {
+    while (/^[A-Za-z_][A-Za-z0-9_]*=/.test(words[0] ?? "")) words.shift();
+    const name = basename(words[0] ?? "");
+    if (["!", "if", "then", "elif", "else"].includes(name)) { words.shift(); continue; }
+    if (["fi", "do", "done"].includes(name)) return [];
+    if (!["sudo", "time", "timeout", "nohup", "exec", "xargs", "nice", "env", "command"].includes(name)) return words;
+    words.shift();
+    const values: Record<string, string[]> = {
+      sudo: ["-u", "-g", "-h", "-p", "-C", "-T", "--user", "--group", "--host", "--prompt"],
+      time: ["-f", "-o", "--format", "--output"],
+      timeout: ["-s", "-k", "--signal", "--kill-after"],
+      exec: ["-a"], xargs: ["-n", "-P", "-I", "-L", "-s", "-E", "-d", "--max-args", "--max-procs", "--replace", "--delimiter"],
+      nice: ["-n", "--adjustment"], env: ["-u", "--unset"],
+    };
+    while (words[0]?.startsWith("-")) {
+      const flag = words.shift()!;
+      if (flag === "--") break;
+      if (name === "command" && (flag === "-v" || flag === "-V")) return [];
+      if ((values[name] ?? []).includes(flag)) { if (!words.length) return []; words.shift(); }
+      else if (flag.startsWith("--") && !flag.includes("=") && !["--ignore-environment", "--foreground", "--preserve-status", "--no-run-if-empty", "--verbose"].includes(flag)) return [];
+    }
+    if (name === "timeout") {
+      if (!/^\d+(?:\.\d+)?[smhd]?$/.test(words.shift() ?? "")) return [];
+    }
+  }
+  return [];
+}
+
+/** Scan curl options once: data, headers and other option values never become options. */
+function curlWrites(input: string[]): boolean {
+  const longValues = new Set([
+    "request", "data", "data-ascii", "data-binary", "data-raw", "data-urlencode", "json", "form", "form-string", "upload-file",
+    "url-query", "header", "proxy-header", "output", "output-dir", "user-agent", "user", "proxy-user", "cookie", "cookie-jar", "referer", "url",
+    "resolve", "connect-to", "config", "cacert", "capath", "cert", "cert-type", "key", "key-type", "pass", "proxy", "preproxy",
+    "interface", "max-time", "connect-timeout", "limit-rate", "range", "request-target", "unix-socket", "abstract-unix-socket",
+    "write-out", "trace", "trace-ascii", "dump-header", "stderr", "netrc-file", "ftp-method", "ftp-port", "oauth2-bearer",
+    "proxy-cacert", "proxy-cert", "proxy-key", "socks5", "socks5-hostname", "retry", "retry-delay", "retry-max-time", "local-port",
+  ]);
+  let method: string | undefined, data = false, upload = false, get = false, head = false, uncertain = false, writeMethod = false;
+  const booleanOptions = new Set(["get", "head", "compressed", "location", "insecure", "silent", "show-error", "fail", "fail-with-body", "globoff", "verbose", "include", "remote-name", "path-as-is", "create-dirs", "progress-meter", "progress-bar", "http1.1", "http2", "http3"]);
+  // An unknown option may consume a following read-looking token. It cannot erase known write evidence.
+  const writes = () => uncertain && (data || upload || writeMethod) || (method !== undefined ? !["GET", "HEAD"].includes(method.toUpperCase()) : !head && (upload || data && !get));
+  for (let i = 0; i < input.length; i++) {
+    const arg = input[i]!;
+    if (arg === "--") break;
+    if (arg === "--next" || arg === "-:") {
+      if (writes()) return true;
+      method = undefined; data = upload = get = head = uncertain = writeMethod = false;
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      const equal = arg.indexOf("=");
+      const name = arg.slice(2, equal < 0 ? undefined : equal);
+      if (name === "get" || name === "no-get") get = name === "get";
+      else if (name === "head" || name === "no-head") head = name === "head";
+      if (!longValues.has(name)) { if (!booleanOptions.has(name.replace(/^no-/, ""))) uncertain = true; continue; }
+      const value = equal < 0 ? input[++i] : arg.slice(equal + 1);
+      if (value === undefined) continue;
+      if (name === "request") { method = value; writeMethod ||= !["GET", "HEAD"].includes(value.toUpperCase()); }
+      else if (name === "upload-file") upload = true;
+      else if (name === "json" || name.startsWith("data") || name === "form" || name === "form-string") data = true;
+      continue;
+    }
+    if (!/^-[^-]/.test(arg)) continue;
+    for (let at = 1; at < arg.length; at++) {
+      const flag = arg[at]!;
+      if (flag === "G") get = true;
+      if (flag === "I") head = true;
+      // These short options consume the rest of this word, or the next whole word.
+      if (!"XdFTHoAuUbecrxEKPmCwDQztYy".includes(flag)) continue;
+      const value = arg.slice(at + 1) || input[++i];
+      if (value !== undefined) {
+        if (flag === "X") { method = value; writeMethod ||= !["GET", "HEAD"].includes(value.toUpperCase()); }
+        else if (flag === "d" || flag === "F") data = true;
+        else if (flag === "T") upload = true;
+      }
+      break;
+    }
+  }
+  return writes();
+}
+
+function sequence(parsed: Command[], root: string, initial: string[], found: Set<ActionClass>, depth = 0): void {
+  const cwd = new Set(initial);
+  for (const command of parsed) {
+    classify(command, root, [...cwd], found, depth);
+    const [program, ...args] = unwrapped(command.words);
+    const target = args[0] === "--" ? args[1] : args[0];
+    // Retain both outcomes: cd may fail, or be in a pipeline/conditional branch.
+    if (program === "cd" && (!target || target.startsWith("~"))) {
+      if (!cwd.has("") && cwd.size >= 128) cwd.delete(cwd.values().next().value!);
+      cwd.add("");
+    }
+    else if (program === "cd" && target && !target.startsWith("-") && !"$`*?[]".split("").some(c => target.includes(c))) {
+      for (const current of [...cwd]) {
+        if (cwd.size >= 128) break;
+        cwd.add(current || isAbsolute(target) ? resolve(current, target) : "");
+      }
+    }
+  }
+}
+function classify(command: Command, root: string, cwd: string[], found: Set<ActionClass>, depth = 0): void {
+  const words = unwrapped(command.words);
+  const program = basename(words.shift() ?? "");
+  if (["sh", "bash", "zsh"].includes(program) && depth < 2) {
+    const shell = [...words];
+    while (["--noprofile", "--norc"].includes(shell[0] ?? "")) shell.shift();
+    const mode = shell.shift();
+    if (mode && /^-[A-Za-z]*c[A-Za-z]*$/.test(mode)) {
+      if (shell[0] === "--") shell.shift();
+      const nested = shell[0] === undefined ? undefined : commands(shell[0]);
+      if (nested) sequence(nested, root, cwd, found, depth + 1);
+    }
+  }
+  if (command.outputs.some(p => cwd.some(at => outside(p, root, at)))) found.add("destroy");
+  if (program === "git") {
+    const heads = commandHeads(words, ["-C", "-c", "--git-dir", "--work-tree", "--namespace", "--config-env"],
+      ["-P", "-p", "--no-pager", "--paginate", "--literal-pathspecs", "--bare", "--no-optional-locks", "--no-replace-objects"], ["push", "reset", "clean", "branch"]);
+    for (const { name: sub, args } of heads) {
+      if (sub === "push") found.add("publish");
+      if (sub === "reset" && args.some(w => w === "--hard" || w.startsWith("--hard="))) found.add("destroy");
+      if (sub === "clean" && forcedClean(args)) found.add("destroy");
+      if (sub === "branch" && (flags(args, "D") || args.includes("--delete") && args.includes("--force"))) found.add("destroy");
+    }
+  }
+  if (["npm", "cargo", "pnpm", "yarn", "bun"].includes(program)) {
+    const valuesByProgram: Record<string, string[]> = {
+      npm: ["--registry", "--prefix", "-C", "--cache", "--userconfig", "--globalconfig", "--loglevel", "--workspace", "-w"],
+      pnpm: ["--registry", "--dir", "-C", "--filter", "-F", "--store-dir", "--reporter", "--loglevel"],
+      yarn: ["--registry", "--cwd", "--cache-folder", "--mutex", "--use-yarnrc", "--modules-folder", "--network-concurrency", "--network-timeout"],
+      cargo: ["--color", "--config", "--manifest-path", "--target-dir"],
+      bun: ["--registry", "--cwd", "-C", "--filter", "-F", "--env-file", "--config", "-c", "--cache-dir"],
+    };
+    const values = valuesByProgram[program]!;
+    const booleans = ["--global", "-g", "--offline", "--locked", "--frozen", "--silent", "--quiet", "-q", "--verbose", "-v"];
+    const actions = ["publish", "install", "i", "add", "global", "npm"];
+    const heads = commandHeads(words, values, booleans, actions);
+    for (const head of heads) {
+      const candidates = program === "yarn" && head.name === "npm" ? commandHeads(head.args, values, booleans, actions) : [head];
+      for (const { name: sub, args } of candidates) {
+        if (sub === "publish") found.add("publish");
+        const global = words.includes("--global") || flags(words, "g");
+        if ((program === "cargo" && sub === "install") || (["install", "i", "add"].includes(sub) && global) || (program === "yarn" && sub === "global" && args[0] === "add")) found.add("install");
+      }
+    }
+  }
+  if (program === "pipx" && words[0] === "install" || program === "brew" && ["install", "reinstall"].includes(words[0] ?? "") || ["pip", "pip3"].includes(program) && words[0] === "install" && words.includes("--user")) found.add("install");
+  if (program === "gh") {
+    if (words[0] === "release" && ["create", "upload", "edit", "delete"].includes(words[1] ?? "")) found.add("publish");
+    if (["issue", "pr", "gist"].includes(words[0] ?? "") && ["create", "comment", "edit", "close", "reopen", "merge", "review", "delete"].includes(words[1] ?? "")) found.add("external-write");
+    if (words[0] === "api") {
+      const method = option(words, "-X", "--method");
+      const field = words.some(w => w === "-f" || w === "-F" || w.startsWith("-f") || w.startsWith("-F") || w === "--input" || w.startsWith("--input=") || w.startsWith("--field") || w.startsWith("--raw-field"));
+      if (method ? !["GET", "HEAD"].includes(method.toUpperCase()) : field) found.add("external-write");
+    }
+  }
+  if (program === "curl" && curlWrites(words)) found.add("external-write");
+  if (["http", "https"].includes(program) && words.some(w => /^(?:POST|PUT|PATCH|DELETE|OPTIONS|TRACE|CONNECT)$/.test(w))) found.add("external-write");
+  if (["mail", "mailx", "sendmail"].includes(program) && operands(words).length > 0) found.add("external-write");
+  if (["slack", "telegram", "discord"].includes(program) && words.some(w => ["send", "post", "chat.postMessage"].includes(w))) found.add("external-write");
+  if (program === "rm" && (flags(words, "r") || flags(words, "R") || words.includes("--recursive")) && operands(words).some(p => cwd.some(at => outside(p, root, at)))) found.add("destroy");
+  if (["cp", "mv"].includes(program) && (flags(words, "f") || words.includes("--force"))) {
+    const target = option(words, "-t", "--target-directory") ?? operands(words).at(-1);
+    if (target && cwd.some(at => outside(target, root, at))) found.add("destroy");
+  }
+}
+
+/** Adds information only; an empty result always retains the native permission policy.
+ * ponytail: literal bounded shell/argv forms only; aliases, functions, expansion,
+ * interpreter programs and symlink targets need a richer observed contract.
+ * Home targets are conservatively outside without resolving a personal home.
+ * Unsupported segments retain only preceding complete commands.
+ * Literal cd retains both success/failure cwd candidates (at most 128); it may
+ * overclassify a later relative write and is not a shell control-flow proof.
+ */
+export function classifyAction(tool: string, args: unknown, executionRoot: string): ActionClass[] {
+  if (typeof tool !== "string" || tool.length > 128 || typeof executionRoot !== "string" || executionRoot.length > LIMIT) return [];
+  if (typeof args === "string") {
+    if (args.length > LIMIT) return [];
+    try { args = JSON.parse(args) as unknown; } catch { args = { command: args }; }
+  }
+  const input = object(args);
+  if (!input) return [];
+  const found = new Set<ActionClass>();
+  if (["http", "http_request", "fetch"].includes(tool.toLowerCase()) && typeof input.method === "string" && /^[A-Za-z]+$/.test(input.method) && !["GET", "HEAD"].includes(input.method.toUpperCase())) found.add("external-write");
+  const boundedArgv = (value: unknown): value is string[] => Array.isArray(value) && value.length <= 256 && value.every(w => typeof w === "string" && w.length <= LIMIT) && value.join("").length <= LIMIT;
+  const location = input.cwd ?? input.workdir;
+  const cwd = typeof location === "string" && location.startsWith("~") ? "" : typeof location === "string" && location.length <= LIMIT && !/[$`]/.test(location) ? resolve(executionRoot, location) : executionRoot;
+  if (tool.toLowerCase() === "git" && boundedArgv(input.args)) classify({ words: ["git", ...input.args], outputs: [] }, executionRoot, [cwd], found);
+  if (SHELL_TOOLS.has(tool.toLowerCase())) {
+    const raw = input.command ?? input.cmd;
+    if (typeof raw === "string") {
+      const parsed = commands(raw);
+      if (parsed) sequence(parsed, executionRoot, [cwd], found);
+    } else if (boundedArgv(raw)) {
+      classify({ words: raw, outputs: [] }, executionRoot, [cwd], found);
+    }
+  }
+  return ACTION_CLASSES.filter(value => found.has(value));
+}

package/src/hub/action-policy.ts

@@ -0,0 +1,106 @@
+import { ACTION_CLASSES, type ActionClass } from "./action-class.ts";
+import { sanitize } from "./envelope.ts";
+
+export interface ActionPolicyConfig { enabled: boolean; always_ask: ActionClass[]; budgets: Record<ActionClass, number> }
+const DEFAULT_BUDGETS: Record<ActionClass, number> = { publish: 1, destroy: 3, "external-write": 5, install: 2 };
+/** Defaults are host policy; overrides belong only in untracked config.local.json.
+ * ponytail: startup adopts that local policy without a retained person confirmation.
+ * Before adapter enforcement (#312/#313), bind weakened startup policy to person
+ * confirmation or surface it as attention; slice 1 never enforces these grants.
+ */
+export function actionPolicyConfig(value?: unknown): ActionPolicyConfig {
+  const fail = (): never => { throw new Error("action_policy: expected enabled, always_ask and class budgets (integers 0..1000)"); };
+  if (value === undefined) return { enabled: true, always_ask: [...ACTION_CLASSES], budgets: { ...DEFAULT_BUDGETS } };
+  if (!value || typeof value !== "object" || Array.isArray(value)) return fail();
+  const raw = value as Record<string, unknown>;
+  if (Object.keys(raw).some(key => !["enabled", "always_ask", "budgets"].includes(key))) return fail();
+  if (raw.enabled !== undefined && typeof raw.enabled !== "boolean") return fail();
+  const classes = raw.always_ask === undefined ? ACTION_CLASSES : raw.always_ask;
+  if (!Array.isArray(classes) || classes.length > ACTION_CLASSES.length || new Set(classes).size !== classes.length || classes.some(key => !ACTION_CLASSES.includes(key))) return fail();
+  const budgets = { ...DEFAULT_BUDGETS };
+  if (raw.budgets !== undefined) {
+    if (!raw.budgets || typeof raw.budgets !== "object" || Array.isArray(raw.budgets)) return fail();
+    for (const [key, amount] of Object.entries(raw.budgets)) {
+      if (!ACTION_CLASSES.includes(key as ActionClass) || typeof amount !== "number" || !Number.isSafeInteger(amount) || amount < 0 || amount > 1000) return fail();
+      budgets[key as ActionClass] = amount;
+    }
+  }
+  return { enabled: raw.enabled ?? true, always_ask: [...classes], budgets } as ActionPolicyConfig;
+}
+
+export interface ActionSessionBudget { readonly peer: string; readonly session: string }
+export interface ActionChallenge { readonly classes: readonly ActionClass[] }
+export type ActionDecision = { kind: "native" } | { kind: "ask"; classes: ActionClass[]; challenge?: ActionChallenge } | { kind: "budget"; classes: ActionClass[] };
+interface Session { handle: ActionSessionBudget; policy: string; remaining: Record<ActionClass, number> }
+const empty = (): Record<ActionClass, number> => ({ publish: 0, destroy: 0, "external-write": 0, install: 0 });
+/** Host-only ledger: session ids and policy come from current runtime ports, never a tool argument. */
+export class ActionBudgets {
+  private sessions = new Map<string, Session>();
+  private challenges = new WeakMap<ActionChallenge, { handle: ActionSessionBudget; policy: string; classes: ActionClass[] }>();
+  constructor(private readonly config: () => ActionPolicyConfig | undefined, private readonly currentSession: (peer: string) => string | undefined) {}
+  bindSession(peer: string, session: string): ActionSessionBudget | undefined {
+    if (!session || this.currentSession(peer) !== session) return undefined;
+    const previous = this.sessions.get(peer);
+    if (previous?.handle.session === session) return previous.handle;
+    const handle = Object.freeze({ peer, session });
+    this.sessions.set(peer, { handle, policy: "", remaining: empty() });
+    return handle;
+  }
+  revoke(peer: string): void { this.sessions.delete(peer); }
+  policyChanged(): void {
+    for (const state of this.sessions.values()) { state.policy = ""; state.remaining = empty(); }
+    this.challenges = new WeakMap();
+  }
+  private current(handle: ActionSessionBudget | undefined): Session | undefined {
+    if (!handle) return undefined;
+    const state = this.sessions.get(handle.peer);
+    if (state?.handle !== handle || this.currentSession(handle.peer) !== handle.session) return undefined;
+    const policy = JSON.stringify(actionPolicyConfig(this.config()));
+    if (state.policy !== policy) { state.policy = policy; state.remaining = empty(); }
+    return state;
+  }
+  private selected(actions: readonly ActionClass[]): ActionClass[] {
+    const config = actionPolicyConfig(this.config());
+    return config.enabled ? ACTION_CLASSES.filter(key => actions.includes(key) && config.always_ask.includes(key)) : [];
+  }
+  /** A budget decision consumes every selected class atomically; native never grants permission. */
+  request(handle: ActionSessionBudget | undefined, actions: readonly ActionClass[]): ActionDecision {
+    const state = this.current(handle), classes = this.selected(actions);
+    if (!classes.length) return { kind: "native" };
+    if (!state) return { kind: "ask", classes };
+    if (classes.some(key => state.remaining[key] <= 0)) {
+      const challenge = Object.freeze({ classes: Object.freeze([...classes]) });
+      this.challenges.set(challenge, { handle: state.handle, policy: state.policy, classes: [...classes] });
+      return { kind: "ask", classes, challenge };
+    }
+    for (const key of classes) state.remaining[key]--;
+    return { kind: "budget", classes };
+  }
+  /** Explicit class-budget approval only, never an ordinary allow_once; this invocation consumes slot one. */
+  approve(challenge: ActionChallenge | undefined): boolean {
+    if (!challenge) return false;
+    const grant = this.challenges.get(challenge); this.challenges.delete(challenge);
+    if (!grant) return false;
+    const state = this.current(grant.handle), config = actionPolicyConfig(this.config());
+    if (!state || state.policy !== grant.policy) return false;
+    for (const key of grant.classes) state.remaining[key] = Math.max(0, config.budgets[key] - 1);
+    return true;
+  }
+  /** Read-only projection: no session is created, rebound or reset by a status poll. */
+  status(peer: string, enforced: boolean) {
+    const config = actionPolicyConfig(this.config()), state = this.sessions.get(peer);
+    const bound = !!state && this.currentSession(peer) === state.handle.session && state.policy === JSON.stringify(config);
+    return { enabled: config.enabled, alwaysAsk: [...config.always_ask], limits: { ...config.budgets }, remaining: bound ? { ...state.remaining } : empty(), sessionBound: bound,
+      enforceable: enforced, note: !enforced ? `always-ask not enforceable: adapter integration pending${config.enabled ? "" : "; policy disabled"}` : config.enabled ? "always-ask active" : "always-ask disabled" };
+  }
+}
+
+/** Adapter integrations must pass the host's publicView and current command/private-turn screens. */
+export function actionApprovalText<T>(classes: readonly ActionClass[], command: string, task: T | undefined,
+  ports: { publicView(task: T): Record<string, unknown>; private: boolean; commandView(command: string): string | undefined }): string {
+  const view = task === undefined ? undefined : ports.publicView(task);
+  const title = typeof view?.title === "string" ? sanitize(view.title).replace(/[\p{Cc}\p{Cf}]/gu, " ").slice(0, 160) : undefined;
+  const shown = ports.private ? undefined : ports.commandView(command);
+  const line = shown === undefined ? "[private command withheld]" : sanitize(shown).replace(/[\p{Cc}\p{Cf}]/gu, " ").slice(0, 512);
+  return `Action approval (${ACTION_CLASSES.filter(key => classes.includes(key)).join(", ")})${title ? `; task ${title}` : ""}: ${line}`;
+}