@staix/agent-hub 0.12.45 → 0.14.0

package/src/cli/output.ts

@@ -5,6 +5,7 @@ import { cells, TABLES, table, fitLine, wrap, duration, relative, plural, termin
 import { taskProgress } from "../ui/task-progress.ts";
 import { backendLabel } from "./status-lines.ts";
 import { formatReport, formatTaskReport, type Report, type TaskReport } from "../hub/report.ts";
+import type { Counter, LimitsResult, TotalResult, UsageResult } from "../hub/usage-rollup.ts";
 
 export interface DoctorCheck { section: "Tools" | "Hub" | "Config" | "Models" | "Memory"; level: "ok" | "warn" | "fail" | "unknown"; name: string; detail: string }
 export interface StatusOutput {
@@ -17,7 +18,7 @@ export interface StatusOutput {
   isolatedChecks?: { pending?: number; orphans?: string[]; unknownReceipts?: readonly string[]; maintenanceUnavailable?: boolean };
   memoryProfile?: { profile?: string; generation?: string; state?: string; agentMemVersion?: string; skippedRows?: number; error?: string };
   taskWip?: Record<string, { wip: number; wipLimit: number }>;
-  pid?: number; controlPort?: number; cwd?: string; version?: string; peers: Record<string, any>; roleInfo?: Record<string, any>; budget?: Record<string, any>; planner?: { peers?: string[]; source?: string };
+  pid?: number; controlPort?: number; cwd?: string; version?: string; peers: Record<string, any>; roleInfo?: Record<string, any>; actionPolicyInfo?: Record<string, { note: string; enforceable: boolean }>; budget?: Record<string, any>; planner?: { peers?: string[]; source?: string };
   tasks?: Record<string, number>; models?: { backends?: any[] }; permissionDefaults?: any[]; deliveryError?: string; crash?: string[];
 }
 export interface BudgetOutput { budget: Record<string, any>; gate?: number }
@@ -245,9 +246,13 @@ export function renderStatus(data: StatusOutput, columns?: number, now = Date.no
     }
     if (p.toolsOnly) out.push(...detail(definitionOf(id)?.attach?.pullOnlyForms?.includes("tui") && p.pullOnly ? "pull-only" : "tools-only", flat(p.toolsOnly).replace(/^(?:tools-only|pull-only):\s*/, ""), columns, "attention"));
     if (p.pullOnly && definitionOf(id)?.attach?.pullOnlyForms?.includes("tui")) out.push(...detail(`${id} last read`, typeof p.lastInboxAt === "number" ? relative(p.lastInboxAt, now) : "never", columns, "muted"));
+    const actionPolicy = data.actionPolicyInfo?.[id];
+    if (actionPolicy?.note) out.push(...detail(`${id} action policy`, actionPolicy.note, columns, actionPolicy.enforceable ? "muted" : "attention"));
+    if (typeof p.reviewerUnavailable === "string" && p.reviewerUnavailable) out.push(...detail("reviewer", flat(p.reviewerUnavailable), columns, "failure")); // #722: the cause class, never a path
     if (p.permissionNote) out.push(...detail("permission", p.permissionNote, columns, "muted"));
     if (typeof p.statusNotice?.message === "string" && p.statusNotice.message) out.push(...detail("status notice", p.statusNotice.message, columns, "attention"));
     if (p.requestedModel && p.servedBy && p.requestedModel !== p.servedBy) out.push(...detail("requested model", p.requestedModel, columns));
+    if (typeof p.modelSource === "string" && p.modelSource) out.push(...detail("model source", flat(p.modelSource), columns, "muted")); // an extra Jcode instance (#685): names only, never a URL or token
     if (typeof p.importantWaitingSince === "number" && p.importantWaitingNote) out.push(...detail("important waiting", `${p.importantWaitingNote.replace(/^\d+ important messages? waiting/, "important messages waiting")}`, columns, "attention"));
     if (typeof p.oldestQueuedAt === "number") out.push(...detail(`${id} oldest queued`, relative(p.oldestQueuedAt, now), columns, "muted"));
     return out;
@@ -264,10 +269,55 @@ export function renderStatus(data: StatusOutput, columns?: number, now = Date.no
   if (counts) out.push([], ...lines(`TASKS  ${counts} (ahub board)`, columns));
   return out;
 }
-export function renderBoard(tasks: any[], columns?: number, now = Date.now(), _full = false, allTasks: any[] | null = tasks): Span[][] {
+// #724: short next-step codes for the compact board, keyed on the blocker texts of src/hub/sdlc.ts; the full advice stays in --full and ahub task show.
+const STAGE_CODES: [string, string][] = [["issue identity missing", "issue?"], ["PR identity missing", "PR?"], ["PR is not open", "PR closed"], ["current PR evidence unknown", "PR state?"],
+  ["required check", "CI?"], ["local gate", "gate?"], ["current head has not been reviewed", "review?"], ["GitHub review approval", "approval?"], ["review requests", "requests?"],
+  ["review threads", "threads?"], ["open important review findings", "findings"], ["person may inspect merge readiness", "ready"]];
+export function stageCode(next: string): string {
+  const known = STAGE_CODES.find(([prefix]) => next.startsWith(prefix));
+  return known ? known[1] : width(next) <= 12 ? next : characters(next).slice(0, 9).join("") + "...";
+}
+const BOARD_LEGEND = "STAGE: [#---] SDLC progress, stage: next step. issue? no issue, PR? no PR, CI? checks, review? not reviewed, threads? open threads. Full advice: ahub board --full.";
+const ellipsis = (text: string, room: number) => width(text) <= room ? text : room <= 3 ? ".".repeat(Math.max(0, room)) : (() => { let out = ""; for (const unit of characters(text)) { if (width(out + unit) > room - 3) break; out += unit; } return out + "..."; })();
+/** #724: one line per task. TITLE goes last and is cut to the room left; at a narrow width REVIEWER, CLASS and AGE give way first. */
+function compactBoard(tasks: any[], data: OutputCell[][], columns: number, staged: boolean): Span[][] {
+  const head = ["ID", "STATE", "OWNER", "REVIEWER", "CLASS", "AGE", "AFTER", ...(staged ? ["STAGE"] : []), "TITLE"];
+  let table = tasks.map((task, i) => {
+    const row = data[i]!, deps: number[] = task.deps ?? [];
+    const after = deps.length ? `#${deps[0]}${deps.length > 1 ? `,+${deps.length - 1}` : ""}` : "-";
+    const meter = /^\[[^\]]*\](?: cancelled)?/.exec(row[7]?.text ?? "")?.[0] ?? "[----]";
+    const stage = task.lifecycle ? `${meter} ${task.lifecycle.stage}: ${stageCode(String(task.lifecycle.next ?? ""))}` : meter;
+    const short = task.lifecycle ? `${meter} ${stageCode(String(task.lifecycle.next ?? ""))}` : meter;
+    return [row[0]!, row[1]!, row[2]!, row[3]!, row[4]!, row[5]!, span(after, undefined, true), ...(staged ? [{ ...span(stage, row[7]!.tone, true), short }] : []), span(flat(task.title))];
+  });
+  let names = [...head];
+  const drop = (name: string) => { const at = names.indexOf(name); if (at < 0) return; names = names.filter((_, i) => i !== at); table = table.map(row => row.filter((_, i) => i !== at)); };
+  for (const name of [...names]) if (name !== "TITLE" && table.every(row => flat(row[names.indexOf(name)]?.text) === "-")) drop(name);
+  const room = () => { const t = names.indexOf("TITLE"); return columns - names.reduce((sum, name, i) => i === t ? sum : sum + Math.max(width(name), ...table.map(row => width(flat(row[i]!.text)))), 0) - 2 * (names.length - 1); };
+  const want = Math.min(30, Math.max(...table.map(row => width(row[row.length - 1]!.text))));
+  for (const name of ["REVIEWER", "CLASS", "AGE", "STAGE"]) if (room() < want) {
+    // STAGE is never dropped: it falls back to the meter and the code, the stage name being the meter's position.
+    if (name !== "STAGE") drop(name);
+    else { const at = names.indexOf("STAGE"); if (at >= 0) table = table.map(row => row.map((cell, i) => i === at ? { ...cell, text: (cell as OutputCell & { short?: string }).short ?? cell.text } : cell)); }
+  }
+  // Still too narrow (a long instance id as OWNER): AFTER gives way, then OWNER is cut, so the row never becomes linked bands.
+  if (room() < 8) drop("AFTER");
+  const owner = names.indexOf("OWNER");
+  if (room() < 8 && owner >= 0) { const cut = Math.max(5, Math.max(...table.map(row => width(flat(row[owner]!.text)))) - (8 - room())); table = table.map(row => row.map((cell, i) => i === owner ? { ...cell, text: ellipsis(flat(cell.text), cut) } : cell)); }
+  const titleRoom = Math.max(5, room());
+  // A PII row keeps its whole "ahub task show" hint when 8 columns of title remain; the cut title is never wrapped.
+  table = table.map((row, i) => { const pii = `  (ahub task show ${tasks[i].id})`, hint = tasks[i].signals?.includes("pii") && titleRoom - width(pii) >= 8 ? pii : ""; return [...row.slice(0, -1), { ...row[row.length - 1]!, text: ellipsis(row[row.length - 1]!.text, Math.max(4, titleRoom - width(hint))) + hint }]; });
+  return rows(names, table, columns);
+}
+export function renderBoard(tasks: any[], columns?: number, now = Date.now(), full = false, allTasks: any[] | null = tasks): Span[][] {
   if (!tasks.length) return [[span("no tasks")]];
   const s = initialConsoleState(); s.panel = 3; s.tasks = tasks;
   const stages = allTasks === null ? undefined : new Map(taskProgress(boardColumnContext(tasks, allTasks)).stages.map(stage => [stage.id, stage]));
+  const counts = [...new Set(tasks.map(task => task.state))].map(state => `${tasks.filter(task => task.state === state).length} ${state}`).join(", ");
+  if (!full && columns !== undefined) {
+    const data = tasks.map(task => { const row = cells(s, task, false, now, stages); row[2] = span(row[2]!.text, peerTone(task.owner ?? "")); row[3] = span(row[3]!.text, peerTone(task.reviewer ?? "")); return row; });
+    return [...compactBoard(tasks, data, columns, allTasks !== null), [], ...lines(`${plural(tasks.length, "task")}: ${counts}`, columns), ...(allTasks !== null ? lines(BOARD_LEGEND, columns, "muted") : [])];
+  }
   const data = tasks.map(task => {
     const row = cells(s, task, false, now, stages);
     row[2] = span(row[2]!.text, peerTone(task.owner ?? ""));
@@ -276,7 +326,6 @@ export function renderBoard(tasks: any[], columns?: number, now = Date.now(), _f
     if (allTasks === null) row.pop();
     return row;
   });
-  const counts = [...new Set(tasks.map(task => task.state))].map(state => `${tasks.filter(task => task.state === state).length} ${state}`).join(", ");
   return [...rows(allTasks === null ? TABLES[3]!.slice(0, -1) : [...TABLES[3]!], data, columns), [], ...lines(`${plural(tasks.length, "task")}: ${counts}`, columns)];
 }
 export function renderBudget(data: BudgetOutput, columns?: number, now = Date.now(), _full = false): Span[][] {
@@ -431,3 +480,42 @@ export function renderReport(report: Report | TaskReport, columns?: number, now
   }
   return out;
 }
+
+// ---- ahub usage (#683 U2): every number names its source; an unknown number prints `unknown`, never 0 ----------------------------------------------
+const SOURCE_NAME: Record<Counter["source"], string> = { native: "native", count: "hub count", manual: "manual", partial: "partial, at least", unknown: "unknown" };
+/** `1234 (native)`, `1234 (hub count)`, or `unknown`: a missing counter is never shown as zero. */
+export const usageNumber = (c: Counter): string => c.value === null ? "unknown" : `${c.value} (${SOURCE_NAME[c.source]})`;
+const usageCell = (c: Counter): OutputCell => c.value === null ? span("unknown", "muted") : span(usageNumber(c), "number");
+
+export function renderUsage(result: UsageResult, columns?: number): Span[][] {
+  const out = lines(`usage by ${result.by}: ${result.coverage.records} records, ${result.coverage.withUsage} with provider counters, ${result.coverage.withoutUsage} without`, columns, "muted");
+  const header = ["KEY", "TOTAL", "WITHOUT CACHE", "CACHE READ", "INPUT", "OUTPUT", "REASONING", "HUB COUNT"];
+  const row = (r: UsageResult["rows"][number]) => [span(r.pii ? `${r.key} [pii]` : r.key), usageCell(r.total), usageCell(r.totalWithoutCache), usageCell(r.cacheRead), usageCell(r.input), usageCell(r.output), usageCell(r.reasoning), usageCell(r.counted)];
+  const all = [...result.rows, ...(result.unattributed ? [result.unattributed] : [])];
+  if (!all.length) return [...out, ...lines("no usage recorded in this period", columns)];
+  return [...out, [], ...rows(header, all.map(row), columns, undefined, true),
+    ...lines("TOTAL is the provider's own total, cache reads included; WITHOUT CACHE removes them. HUB COUNT is what the hub counted itself and covers peers that report no usage record. unknown is never zero.", columns, "muted")];
+}
+
+export function renderLimits(result: LimitsResult, current: unknown, columns?: number): Span[][] {
+  const out = lines(`limit history: ${result.truncated ? `the newest ${result.shown} of ${result.total}` : `${result.total}`} events, ${result.open.length} open pause${result.open.length === 1 ? "" : "s"}`, columns, "muted");
+  if (result.truncated) out.push(...lines(`${result.omitted} older events are not shown: use --limit <n> (up to ${result.maxLimit}) for more`, columns, "attention"));
+  for (const o of result.open) out.push(...lines(`open pause: ${o.peer} ${o.window} since ${o.since}, resets ${new Date(o.resetsAt).toISOString()}`, columns, "attention"));
+  for (const o of result.endedUnknown) out.push(...lines(`pause ended, end unknown: ${o.peer} ${o.window} since ${o.since} (the hub no longer holds it, for example after ahub reset; no resume was recorded)`, columns, "muted"));
+  const windows = current && typeof current === "object" ? Object.entries(current as Record<string, { windows?: { id: string; used: number; resetsAt?: number }[] }>) : [];
+  const live = windows.flatMap(([peer, b]) => (b?.windows ?? []).map(w => [span(peer), span(w.id), span(`${Math.round(w.used * 100)}%`, "number"), span(w.resetsAt ? new Date(w.resetsAt).toISOString() : "unknown", w.resetsAt ? undefined : "muted")]));
+  if (live.length) out.push([], ...lines("current windows", columns, "strong"), ...rows(["PEER", "WINDOW", "USED", "RESETS"], live, columns, undefined, true));
+  const hist = result.history.map(h => [span(h.at), span(h.type.replace("budget_", "").replace("quota_reset", "reset")), span(h.peer), span(h.window), span(Object.entries(h.detail).map(([k, v]) => `${k} ${v}`).join(", "), "muted")]);
+  if (hist.length) out.push([], ...lines("history", columns, "strong"), ...rows(["AT", "EVENT", "PEER", "WINDOW", "DETAIL"], hist, columns, undefined, true));
+  return out;
+}
+
+export function renderTotal(result: TotalResult, columns?: number): Span[][] {
+  const out = lines(`lifetime development tokens since ${result.since ?? "the first event"}`, columns, "muted");
+  const table = result.peers.map(p => [span(p.peer), usageCell(p.tokens), usageCell(p.withoutCache), usageCell(p.cacheRead)]);
+  table.push([span("ALL PEERS", "strong"), usageCell(result.overall.tokens), usageCell(result.overall.withoutCache), usageCell(result.overall.cacheRead)]);
+  const left = (label: string, peers: string[]) => peers.length ? lines(`${label} leaves out ${peers.join(", ")} (unknown, not counted as 0): a lower bound`, columns, "attention") : [];
+  return [...out, [], ...rows(["PEER", "TOTAL", "WITHOUT CACHE", "CACHE READ"], table, columns, undefined, true),
+    ...left("ALL PEERS TOTAL", result.overall.tokens.source === "partial" ? result.unknownPeers.tokens : []), ...left("ALL PEERS CACHE READ", result.overall.cacheRead.source === "partial" ? result.unknownPeers.cacheRead : []),
+    ...lines("A peer with no provider counters (for example jcode, kimi) shows the hub's own count where one exists, otherwise unknown. The overall WITHOUT CACHE is unknown unless every peer's cache split is known.", columns, "muted")];
+}

package/src/cli/preview.ts

@@ -21,7 +21,7 @@ export function launcherPreview(tool: "claude" | "codex" | "kimi" | "pi" | "qwen
     if (mode >= 0 && args[mode + 1] !== "headless") throw new Error("extra instances require headless mode");
     if (mode < 0 && !args.includes("--headless")) args.push("--mode", "headless");
   }
-  const result = preview({ tool, args, cwd, stateDir, cliDir: import.meta.dir, unattended, config, definition,
+  const result = preview({ tool, args, cwd, stateDir, cliDir: import.meta.dir, unattended, config, definition, ...(selected.instance ? { instance: selected.instance } : {}),
     baseEnvNames: Object.keys(childEnv()).concat(["AGENTHUB_STATE_DIR", "AGENTHUB_PROJECT_DIR"]),
     helpers: { buildLaunch: (native, argv, ctx) => buildLaunch(native, argv, { ...ctx, ...(selected.instance ? { instance: selected.instance } : {}) }), claudeObservationHooks, buildKimiLaunch, buildKimiTuiLaunch, nativeLaunchEnv, childEnv,
       startModeOf, kimiMcpPlan, jcodeCommand, jcodeTuiCommand, qwenSessionId, relayModelIds, buildPiLaunch },

package/src/cli/sdlc-release-guard.ts

@@ -0,0 +1,82 @@
+/** Literal release targets only. Parsing never executes a command or reads the repository. */
+export type ReleaseGuardRequest =
+  | { kind: "tag-push"; version: string; tag: string; sourceRef: string; remote: string }
+  | { kind: "gh-release"; version: string; tag: string; target?: string }
+  | { kind: "npm-publish" };
+export interface ReleasePushUpdate { localRef: string; localOid: string; remoteRef: string; remoteOid: string; version: string; }
+type Refusal = { ok: false; reason: string };
+export type ReleaseGuardParse = { ok: true; request: ReleaseGuardRequest } | Refusal;
+export type ReleasePushParse = { ok: true; remoteName: string; remoteUrl: string; updates: ReleasePushUpdate[]; stdin: string } | Refusal;
+const refuse = (): Refusal => ({ ok: false, reason: "release target is ambiguous, unsupported or invalid" });
+const SEMVER = /^(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)(?:-[0-9A-Za-z.-]+)?(?:[+][0-9A-Za-z.-]+)?$/;
+const oid = (value: string) => /^[0-9a-f]{40}$/.test(value);
+const zero = (value: string) => /^0{40}$/.test(value);
+const literal = (value: string) => value.length > 0 && value.length <= 4096 && !/[\s\0-\x1f\x7f$`*?\\]/.test(value);
+const ref = (value: string) => literal(value) && !value.startsWith("-") && !value.includes("..") && !value.includes("@{") && !value.includes("//") && !value.endsWith("/") && !value.endsWith(".") && !value.endsWith(".lock") && !"~^:[]()".split("").some(char => value.includes(char));
+const versionOf = (tag: string): string | undefined => tag.startsWith("v") && SEMVER.test(tag.slice(1)) ? tag.slice(1) : undefined;
+
+// Hook values are opaque Git data, not shell source. Unicode and shell-looking
+// characters are valid in refs; only Git's forbidden ref syntax is rejected.
+const hookText = (value: string) => value.length > 0 && value.length <= 4096 && !/[\p{Cc}]/u.test(value);
+const hookRef = (value: string) => hookText(value) && !/[\0-\x20\x7f]/.test(value) && !"~^:?*[\\".split("").some(char => value.includes(char)) && !value.includes("..") && !value.includes("@{") && !value.includes("//") && !value.endsWith("/") && !value.endsWith(".") && !value.split("/").some(part => !part || part.startsWith(".") || part.endsWith(".lock"));
+
+export function parseReleaseGuardArgv(argv: readonly string[]): ReleaseGuardParse {
+  if (!Array.isArray(argv) || !argv.length || argv.length > 128 || !argv.every(word => typeof word === "string" && word.length <= 4096 && !/[\0-\x1f\x7f]/.test(word)) || Buffer.byteLength(argv.join("\0")) > 16 * 1024) return refuse();
+  const [program, ...args] = argv;
+  if (program === "git" && args[0] === "push") {
+    if (args.length !== 3 || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(args[1] ?? "")) return refuse();
+    const spec = args[2]!, parts = spec.split(":");
+    if (parts.length > 2 || spec.startsWith("+")) return refuse();
+    const destination = parts.length === 2 ? parts[1]! : parts[0]!;
+    const tag = destination.startsWith("refs/tags/") ? destination.slice(10) : destination;
+    const version = versionOf(tag), sourceRef = parts[0]!;
+    if (!version || !ref(sourceRef) || parts.length === 2 && !destination.startsWith("refs/tags/")) return refuse();
+    return { ok: true, request: { kind: "tag-push", version, tag, sourceRef, remote: args[1]! } };
+  }
+  if (program === "gh" && args[0] === "release" && args[1] === "create") {
+    const tag = args[2] ?? "", version = versionOf(tag);
+    if (!version) return refuse();
+    let target: string | undefined;
+    const valued = new Set(["--title", "-t", "--notes", "-n", "--notes-file", "-F", "--notes-start-tag", "--target"]);
+    const flags = new Set(["--verify-tag", "--generate-notes", "--draft", "-d", "--prerelease", "-p", "--fail-on-no-commits"]);
+    for (let i = 3; i < args.length; i++) {
+      const flag = args[i]!;
+      if (flags.has(flag)) continue;
+      if (!valued.has(flag) || args[i + 1] === undefined) return refuse();
+      const value = args[++i]!;
+      if (flag === "--target") { if (target !== undefined || !ref(value)) return refuse(); target = value; }
+    }
+    return { ok: true, request: { kind: "gh-release", version, tag, ...(target === undefined ? {} : { target }) } };
+  }
+  if (program === "npm" && args[0] === "publish") {
+    const flags = new Set(["--provenance", "--ignore-scripts", "--dry-run"]);
+    for (let i = 1; i < args.length; i++) {
+      if (flags.has(args[i]!)) continue;
+      if (args[i] === "--access" && ["public", "restricted"].includes(args[i + 1] ?? "")) { i++; continue; }
+      if (args[i] === "--tag" && /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(args[i + 1] ?? "")) { i++; continue; }
+      return refuse();
+    }
+    return { ok: true, request: { kind: "npm-publish" } };
+  }
+  return refuse();
+}
+
+/** Validate every hook row before selecting version-tag updates. Preserve the exact original input. */
+export function parseReleasePushUpdates(remoteName: string, remoteUrl: string, stdin: string): ReleasePushParse {
+  if (typeof remoteName !== "string" || typeof remoteUrl !== "string" || typeof stdin !== "string" || !hookText(remoteName) || !hookText(remoteUrl) || Buffer.byteLength(stdin) > 128 * 1024) return refuse();
+  const lines = stdin.endsWith("\n") ? stdin.slice(0, -1).split("\n") : stdin.split("\n");
+  if (stdin === "") lines.length = 0;
+  if (lines.length > 128) return refuse();
+  const updates: ReleasePushUpdate[] = [];
+  for (const line of lines) {
+    const fields = line.split(" ");
+    if (fields.length !== 4) return refuse();
+    const [localRef, localOid, remoteRef, remoteOid] = fields as [string, string, string, string];
+    if ((!hookRef(localRef) && localRef !== "(delete)") || !hookRef(remoteRef) || !remoteRef.startsWith("refs/") || !oid(localOid) || !oid(remoteOid)) return refuse();
+    if (!remoteRef.startsWith("refs/tags/v")) continue;
+    const version = versionOf(remoteRef.slice(10));
+    if (!version || zero(localOid) || localRef === "(delete)") return refuse();
+    updates.push({ localRef, localOid, remoteRef, remoteOid, version });
+  }
+  return { ok: true, remoteName, remoteUrl, updates, stdin };
+}

package/src/cli/status-lines.ts

@@ -1,7 +1,7 @@
 import type { ContextView } from "../hub/context-window.ts";
 // What `ahub status` prints for a peer and for a model backend, kept pure so it can be checked.
 
-export interface PeerRow { permissionMode?: string; context?: ContextView; state?: string; queued?: number; queuedImportant?: number; needsReview?: number; heldBy?: string; holdNote?: string; liveAccepted?: string[]; oldestQueuedAt?: number; importantWaitingSince?: number; importantWaitingNote?: string; attached?: boolean; toolsOnly?: string; pullOnly?: boolean; lastInboxAt?: number | null; permissionNote?: string; paused?: string; servedBy?: string; requestedModel?: string }
+export interface PeerRow { permissionMode?: string; context?: ContextView; state?: string; queued?: number; queuedImportant?: number; needsReview?: number; heldBy?: string; holdNote?: string; liveAccepted?: string[]; oldestQueuedAt?: number; importantWaitingSince?: number; importantWaitingNote?: string; attached?: boolean; toolsOnly?: string; pullOnly?: boolean; lastInboxAt?: number | null; permissionNote?: string; reviewerUnavailable?: string; paused?: string; servedBy?: string; requestedModel?: string }
 export interface BackendRow { kind?: string; alias?: string; state?: string; active?: number; requestedModel?: string; actualModel?: string; provider?: string; coolingUntil?: string; failures?: number; failingUntil?: string }
 
 /** Aliases are already namespaced ("dgx/coding"); only an alias that is not gets its kind in front of it. */

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));
+}