@staix/agent-hub 0.15.0 → 0.17.0

package/src/cli/memory.ts

@@ -1,15 +1,32 @@
+import { TaskRepositories } from "../hub/task-repository.ts";
+import type { TaskPlan, TaskRefs } from "../hub/board.ts";
+import { Database } from "bun:sqlite";
+import { lstatSync } from "node:fs";
+import { join } from "node:path";
+import { CodeFacts } from "../hub/code-facts.ts";
+import { HUB_DB_BUSY_TIMEOUT_MS } from "../hub/db-timeout.ts";
+import { hubGitEnv, hubGitSync } from "../hub/git.ts";
+import { stateDirFor } from "../hub/control-client.ts";
+import { isDenied } from "../local/deny.ts";
+import { foldSegment } from "../hub/permission-mode.ts";
+import { matchesPolicyLexically } from "../hub/path-policy.ts";
+import { memoryAnchorTaskIdentity, memoryStaleAnchors, unavailableMemoryStaleAnchors, type MemoryStaleAnchorReport, type MemoryTaskPrivacy } from "../hub/memory-stale-anchors.ts";
+import { MEMORY_SYMBOL_START_BUDGET_MS } from "../hub/memory-symbols.ts";
 import { detectCliIdentity } from "./identity.ts";
 import { createStalenessProbe } from "../hub/memory-staleness.ts";
-import { looksSecret, memoryProjectKey, type MemoryStore } from "@staix/agent-mem";
+import { looksSecret, memoryProjectKey, pathCandidates, readProfileJSON, resolveShardProfile, type MemoryStore } from "@staix/agent-mem";
 import type { SyncOptions } from "@staix/agent-mem";
-import { MEMORY_USAGE as CORE_MEMORY_USAGE, rawMemoryCommand, rawGoalCommand } from "@staix/agent-mem";
+import { memoryUsage, goalUsage, rawMemoryCommand, rawGoalCommand } from "@staix/agent-mem";
+
+/** The hub's command names in agent-mem usage and refusal text (agent-mem 0.7.0 defaults to `amem`). */
+const AHUB_NAMES = { memory: "ahub memory", goal: "ahub goal" };
 import { mentionsPrivatePath, promotionScreen, withoutPii } from "../hub/memory-policy.ts";
 import { currentRouting, detectSignals } from "../hub/routing.ts";
 import { loadConfig } from "../hub/daemon.ts";
-import { bindProfileMemory, memoryProjectFor, memoryProjectForStore, openProfileMemory, MEMORY_PROFILE_UNAVAILABLE, MEMORY_SPLIT_INCOMPLETE, type MemoryProfileReceipt, type ProfileMemoryOptions } from "../hub/memory-profile.ts";
+import { bindProfileMemory, memoryProjectFor, memoryProjectForStore, openProfileMemory, MemoryProfileBinding, MEMORY_PROFILE_UNAVAILABLE, MEMORY_SPLIT_INCOMPLETE, type MemoryProfileReceipt, type ProfileMemoryOptions } from "../hub/memory-profile.ts";
 
-export { GOAL_USAGE } from "@staix/agent-mem";
-export const MEMORY_USAGE = `${CORE_MEMORY_USAGE} | decay [--days N] [--json] | profile-check [--json]`;
+export const GOAL_USAGE = goalUsage(AHUB_NAMES.goal);
+export const MEMORY_USAGE = `${memoryUsage(AHUB_NAMES.memory)} | decay [--days N] [--json] | profile-check [--json]`;
 
 const fail = (message: string): never => { throw new Error(message); };
 /** The project's config, or none when there is no valid one (reading memory needs none). */
@@ -75,7 +92,7 @@ export async function memoryCommand(args: string[], cwd: string, opts: { store?:
     screen: promotionScreen(project, cwd, () => currentRouting(cwd), privatePaths) }, cwd);
   try {
     context.binding.assertCurrent();
-    const text = await rawMemoryCommand(args, cwd, { ...opts, project, store: context.store, open: () => context.store,
+    const text = await rawMemoryCommand(args, cwd, { ...opts, names: AHUB_NAMES, project, store: context.store, open: () => context.store,
       readable: notes => {
       const paths = privatePaths(), visible = withoutPii(notes, currentRouting(cwd), cwd, paths);
       if (args[0] !== "show" || args.includes("--json")) return visible;
@@ -99,9 +116,104 @@ export async function goalCommand(args: string[], cwd: string, opts: { store?: M
   const context = commandStores(opts.store, { project }, cwd);
   try {
     context.binding.assertCurrent();
-    const text = await rawGoalCommand(args, cwd, { ...opts, project, store: context.store, open: () => context.store,
+    const text = await rawGoalCommand(args, cwd, { ...opts, names: AHUB_NAMES, project, store: context.store, open: () => context.store,
       clean: (title, milestones, project) => !looksSecret(`${title}\n${milestones.join("\n")}`) && withoutPii([{ title, text: milestones.join("\n"), project }], currentRouting(cwd), cwd, policy()).length > 0,
     });
     return profileOutput(text, args.includes("--json"), context.binding.status(context.store), person);
   } finally { if (context.owned) context.store.close(); }
 }
+
+
+interface StaleAnchorCommandOptions {
+  store?: MemoryStore;
+  facts?: Pick<CodeFacts, "exists">;
+  /** Trusted host test seam; never read from CLI arguments or project configuration. */
+  createFacts?: () => Pick<CodeFacts, "exists" | "close">;
+  stateDir?: string;
+  head?: () => string | undefined;
+  taskPrivacy?: (key: string) => MemoryTaskPrivacy;
+  now?: () => number;
+}
+/** Unlike an ordinary core open, inspection must not initialize a missing profile, machine or shard. */
+function existingInspectionProfile(project: string, cwd: string): boolean {
+  try {
+    const binding = new MemoryProfileBinding({ project, projectKey: memoryProjectKey(cwd) });
+    const profiles = [binding.profile, ...(binding.profile.sharded ? [resolveShardProfile(binding.home, { user: true })] : [])];
+    for (const profile of profiles) {
+      const machineFile = join(profile.sharded ? profile.home : profile.dir, "machine.json"), machine = lstatSync(machineFile);
+      if (!machine.isFile() || machine.isSymbolicLink()) return false;
+      const metadata = readProfileJSON(machineFile, 4096) as { id?: unknown } | undefined;
+      if (!metadata || typeof metadata.id !== "string" || !/^[a-f0-9]{16}$/.test(metadata.id)) return false;
+      const logDirectory = lstatSync(join(profile.dir, "log"));
+      const localDirectory = lstatSync(join(profile.dir, "local"));
+      if (!logDirectory.isDirectory() || logDirectory.isSymbolicLink() || !localDirectory.isDirectory() || localDirectory.isSymbolicLink()) return false;
+    }
+    binding.assertCurrent(); return true;
+  } catch { return false; }
+}
+
+/** Host-only doctor report: selected amem reads may maintain derived indexes/leases, never notes or candidates. */
+export async function memoryStaleAnchorsCommand(cwd: string, opts: StaleAnchorCommandOptions = {}): Promise<MemoryStaleAnchorReport> {
+  let ownedFacts: Pick<CodeFacts, "exists" | "close"> | undefined;
+  let context: ReturnType<typeof commandStores> | undefined;
+  try {
+    const project = projectOf(cwd, opts.store);
+    if (!opts.store && !existingInspectionProfile(project, cwd)) return unavailableMemoryStaleAnchors();
+    context = commandStores(opts.store, { project, projectKey: memoryProjectKey(cwd), deferPromotions: true }, cwd);
+    const config = () => loadConfig(cwd);
+    const publicMetadataText = (text: string): boolean => {
+      try {
+        const c = config(), paths = [...(c.pii?.paths ?? []), ...c.local.deny];
+        return !looksSecret(text) && !detectSignals({ title: "", detail: text, refs: {} }, currentRouting(cwd), cwd).includes("pii")
+          && !mentionsPrivatePath(text, [], paths, cwd)
+          && !pathCandidates(text).some(path => isDenied(path, c.local.deny) || isDenied(foldSegment(path), c.local.deny.map(foldSegment)));
+      } catch { return false; }
+    };
+    const clock = opts.now ?? performance.now.bind(performance), metadataDeadline = clock() + MEMORY_SYMBOL_START_BUDGET_MS;
+    const blockedTasks = new Map<string, "private" | "unknown">(), repositories = new TaskRepositories(cwd); let taskSourceUnavailable = false;
+    const taskPrivacy = opts.taskPrivacy ?? ((key: string): MemoryTaskPrivacy => {
+      const identity = memoryAnchorTaskIdentity(key, project); if (!identity) return "unknown";
+      const blocked = blockedTasks.get(key); if (blocked) return blocked;
+      if (taskSourceUnavailable || clock() >= metadataDeadline) return "unknown";
+      let db: Database | undefined;
+      try {
+        const file = join(opts.stateDir ?? stateDirFor(cwd), "hub.db"), stat = lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink()) { taskSourceUnavailable = true; return "unknown"; }
+        db = new Database(file, { readonly: true, create: false });
+        db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`);
+        const row = db.query(`SELECT id,created,signals,title,detail,refs,plan FROM tasks WHERE id=? AND created=?
+          AND length(signals)<=65536 AND length(title)<=300 AND length(detail)<=8000 AND length(refs)<=65536 AND length(plan)<=65536`).get(identity.id, identity.created) as { id: number; created: number; signals: string; title: string; detail: string; refs: string; plan: string } | null;
+        if (!row || row.id !== identity.id || row.created !== identity.created) { blockedTasks.set(key, "unknown"); return "unknown"; }
+        const signals: unknown = JSON.parse(row.signals), refs: unknown = JSON.parse(row.refs), plan: unknown = JSON.parse(row.plan);
+        if (!Array.isArray(signals) || !signals.every(signal => typeof signal === "string") || !refs || typeof refs !== "object" || Array.isArray(refs) || !plan || typeof plan !== "object" || Array.isArray(plan)) { blockedTasks.set(key, "unknown"); return "unknown"; }
+        const raw = [row.title, row.detail];
+        JSON.stringify({ refs, plan }, (key: string, value: unknown) => { if (key) raw.push(key); if (typeof value === "string") raw.push(value); return value; });
+        if (signals.includes("pii") || signals.includes("pii_path") || !publicMetadataText(raw.join("\n"))) { blockedTasks.set(key, "private"); return "private"; }
+        const paths = [...Object.values(refs), ...Object.values(plan)].flatMap(value => Array.isArray(value) ? value.filter((item): item is string => typeof item === "string") : []);
+        const c = config();
+        if (paths.some(path => isDenied(path, c.local.deny) || matchesPolicyLexically(cwd, path, [...(c.pii?.paths ?? []), ...c.local.deny]))) { blockedTasks.set(key, "private"); return "private"; }
+        const scope = repositories.scope(refs as TaskRefs);
+        if (scope.key !== repositories.project.key || repositories.mismatch(refs as TaskRefs, plan as TaskPlan)) { blockedTasks.set(key, "unknown"); return "unknown"; }
+        return "public";
+      } catch { taskSourceUnavailable = true; return "unknown"; }
+      finally { db?.close(); }
+    });
+    const head = opts.head ?? (() => {
+      try {
+        const result = hubGitSync(["-C", cwd, "rev-parse", "--verify", "HEAD"], { encoding: "utf8", env: hubGitEnv(process.env, { repositoryIsolation: true }), timeout: 1000, maxBuffer: 4096 });
+        const value = result.stdout.trim(); return result.status === 0 && /^[a-f0-9]{40}$/.test(value) ? value : undefined;
+      } catch { return undefined; }
+    });
+    const facts = opts.facts ?? (ownedFacts = opts.createFacts?.() ?? new CodeFacts({ timeoutMs: MEMORY_SYMBOL_START_BUDGET_MS }));
+    const binding = context.binding;
+    return await memoryStaleAnchors({ cwd, project, store: context.store, head, now: opts.now, taskPrivacy, publicMetadataText,
+      assertCurrent: () => binding.assertCurrent(),
+      context: () => ({ cwd, project, repo: project, deny: config().local.deny, allowed: publicMetadataText }),
+      exists: (repo, at, name) => facts.exists(repo, at, name),
+      finishQueries: async () => { if (ownedFacts) { await ownedFacts.close(); ownedFacts = undefined; } } });
+  } catch { return unavailableMemoryStaleAnchors(); }
+  finally {
+    try { if (ownedFacts) await ownedFacts.close(); } catch { /* Optional cleanup failure remains neutral, including a second failed close. */ }
+    try { if (context?.owned) context.store.close(); } catch { /* Inspection must still return its neutral report. */ }
+  }
+}

package/src/cli/output.ts

@@ -1,4 +1,5 @@
 import { definitionOf } from "../adapters/registry.ts";
+import { windowKind } from "../hub/window-kind.ts";
 import { boardColumns, type BoardPeerInput } from "../ui/task-board.ts";
 import { peerStyle } from "../ui/peer-palette.ts";
 import { cells, TABLES, table, fitLine, wrap, duration, relative, plural, terminalText, initialConsoleState, stateTone, type Span, type Tone } from "./console-state.ts";
@@ -16,12 +17,14 @@ export interface StatusOutput {
   taskStalls?: readonly { task: number; cause: { kind: string; peer?: string; dependency?: number; code: string } }[];
   pendingTaskOffers?: readonly { task: number; peer: string }[];
   isolatedChecks?: { pending?: number; orphans?: string[]; unknownReceipts?: readonly string[]; maintenanceUnavailable?: boolean };
+  memoryRead?: { truncated: boolean; scanned: number; limit: number };
   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>; 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 }
+/** `peers`: one note per peer that shows no number, and why (no quota, nothing read yet); absent from an older hub. */
+export interface BudgetOutput { budget: Record<string, any>; gate?: number; peers?: { peer: string; kind?: string; note: string }[] }
 export interface RosterRow { peer: string; on: boolean; startMode: string; state: string; queued: number; tasks: number }
 export function renderRoster(data: RosterRow[], columns?: number): Span[][] {
   return rows(["PEER", "ROSTER", "START", "STATE", "Q", "TASKS"], data.map(row => [span(row.peer, "info", true), span(row.on ? "on" : "off", row.on ? "success" : "muted", true), span(row.startMode, undefined, true), span(row.state, stateTone(row.state), true), span(row.queued, undefined, true), span(row.tasks, undefined, true)]), columns);
@@ -207,6 +210,7 @@ export function renderStatus(data: StatusOutput, columns?: number, now = Date.no
     const profile = memory.profile === "generation" ? `generation ${memory.generation?.slice(0, 8) ?? "unknown"}` : memory.profile ?? "unbound";
     out.push(...detail("memory", `${profile}; ${memory.state ?? "unknown"}; agent-mem ${memory.agentMemVersion ?? "unknown"}${memory.skippedRows ? `; malformed legacy rows skipped: ${memory.skippedRows}` : ""}${memory.error ? `; ${memory.error}` : ""}`, columns, memory.state === "unavailable" ? "attention" : undefined));
   }
+  if (data.memoryRead?.truncated) out.push(...detail("memory view", `truncated: newest ${data.memoryRead.limit} project candidates considered`, columns, "attention"));
   if (data.planner) out.push(...detail("planner", `${data.planner.peers?.join(", ") || "nobody"} (${data.planner.source ?? "unknown"})${data.planner.source === "automatic" || data.planner.source === "none" ? "; pin it with ahub settings set planner <peer>" : ""}`, columns, data.planner.source === "none" ? "attention" : undefined));
   if (data.deliveryError) out.push(...detail("delivery storage", `${data.deliveryError}; dispatch is stopped`, columns, "failure"));
   for (const pending of data.permissionDefaults ?? []) out.push(...detail("permission default", `${pending.peer}: never-ask from ${pending.source}, stays ask until a person confirms in ahub console`, columns, "attention"));
@@ -358,9 +362,13 @@ export function renderBoard(tasks: any[], columns?: number, now = Date.now(), fu
 }
 export function renderBudget(data: BudgetOutput, columns?: number, now = Date.now(), _full = false): Span[][] {
   const out: Span[][] = [];
-  const windows = Object.entries(data.budget).flatMap(([peer, b]) => (b.windows ?? []).map((w: any) => [span(peer, peerTone(peer)), span(w.id), span(`${Math.round(w.used * 100)}%`, "number"), span(typeof w.resetsAt === "number" ? relative(w.resetsAt, now) : "-", "muted"), span(w.source ?? "unknown", "muted"), span(typeof w.at === "number" ? relative(w.at, now) : "unknown", "muted"), span(w.stale ? "stale" : "fresh", w.stale ? "attention" : undefined)]));
-  if (windows.length) out.push(...rows(["PEER", "WINDOW", "USED", "RESETS", "SOURCE", "MEASURED", "STATE"], windows, columns));
-  else out.push(...lines(`no quota readings yet (gate ${data.gate ?? "unknown"}). Sources: Codex rate limits, Claude's status line (ahub claude), ahub budget set.`, columns));
+  // KIND names what the number is (#285): the provider's own (native), tokens the hub counted against a ceiling (count), or a person's (manual).
+  // A window without a kind, from an older hub, is classified by `windowKind`. A fresh window that does not gate says so in STATE.
+  const windows = Object.entries(data.budget).flatMap(([peer, b]) => (b.windows ?? []).map((w: any) => [span(peer, peerTone(peer)), span(w.id), span(`${Math.round(w.used * 100)}%`, "number"), span(typeof w.resetsAt === "number" ? relative(w.resetsAt, now) : "-", "muted"), span(windowKind({ id: w.id, source: w.source ?? "", kind: w.kind }), "muted"), span(w.source ?? "unknown", "muted"), span(typeof w.at === "number" ? relative(w.at, now) : "unknown", "muted"), span(w.stale ? "stale" : w.superseded ? "info only" : "fresh", w.stale ? "attention" : undefined)]));
+  if (windows.length) out.push(...rows(["PEER", "WINDOW", "USED", "RESETS", "KIND", "SOURCE", "MEASURED", "STATE"], windows, columns));
+  else if (!data.peers?.length) out.push(...lines(`no quota readings yet (gate ${data.gate ?? "unknown"}). Sources: Codex rate limits, Claude's status line (ahub claude), ahub budget set.`, columns));
+  // A peer with no number says why, in its own line, so a peer without quota is not mistaken for one that has not reported.
+  for (const note of data.peers ?? []) out.push(...detail(note.peer, note.note, columns, peerTone(note.peer)));
   for (const [peer, b] of Object.entries(data.budget)) if (b.paused) out.push(...detail(`paused ${peer}`, `${b.paused.reason ?? "budget"}${typeof b.paused.resetsAt === "number" ? `; resumes ${relative(b.paused.resetsAt, now)}` : ""}`, columns, "attention"));
   return out;
 }

package/src/cli/upgrade.ts

@@ -143,8 +143,8 @@ export interface RecoveryOperation {
   /** Positive typed store observation; disposal rechecks it before accepting a repaired-session loss. */
   missingRecordedSession?: { projectId: string; peer: RecoveryNativePeer; sessionId: string; kind: "rollout" | "transcript"; checkedPath?: string };
   freshOverride?: { peer: RecoveryNativePeer; evidence: NonNullable<RecoveryOperation["missingRecordedSession"]>; checked: "missing"; at: number };
-  /** #215: every human disposition, in order. Operator reasons only; never task or message text. */
-  audit?: { at: number; action: "fresh-session" | "stop-and-archive"; reason: string; peer?: string; projects: string[] }[];
+  /** #215: every human disposition, in order. Operator reasons only; never task or message text. #776: `cause` is the operation's own `error` at that moment, the text the receipt already held. */
+  audit?: { at: number; action: "fresh-session" | "stop-and-archive"; reason: string; peer?: string; cause?: string; projects: string[] }[];
   disposition?: { choice: "stop-and-archive"; at: number; projects: Record<string, string>; continuity?: Record<string, "not-archived" | "unavailable"> };
   /** #215: a refusal no resume can get past was recorded (FinalRefusal); `next` no longer offers resume. */
   final?: boolean;
@@ -1070,7 +1070,8 @@ export async function disposeRecovery(id: string, choice: { fresh: string } | {
     delete op.blockedReattachment;
     delete op.presentationCause;
     abandoned(op); // #227: in the same write as the disposition
-    (op.audit ??= []).push({ at, action: "stop-and-archive", reason, projects: acts.map((a) => a.planned.project.id) });
+    // #776: the error that blocked the operation is cleared on disposal, so the audit keeps it.
+    (op.audit ??= []).push({ at, action: "stop-and-archive", reason, ...(op.error ? { cause: op.error } : {}), projects: acts.map((a) => a.planned.project.id) });
     // Recorded before the first act: a crash inside a stop leaves a disposition that resume refuses to override.
     delete op.failure;
     op.updatedAt = driver.now(); writeOperation(id, op, home);

package/src/hub/action-class.ts

@@ -5,7 +5,8 @@ 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[] };
+/** `nested`: the commands of each substitution in the segment (`$(...)`, a backtick). They run in a subshell, so their `cd` never moves the outer cwd. */
+type Command = { words: string[]; outputs: string[]; nested?: Command[][] };
 
 /** Bound the whole input before accepting any prefix, including unsupported suffixes. */
 function segmentLimit(text: string): boolean {
@@ -28,8 +29,79 @@ function segmentLimit(text: string): boolean {
   return true;
 }
 
-/** Literal shell words only; unsupported syntax discards only its unfinished segment. */
-function commands(text: string): Command[] | undefined {
+/**
+ * An expansion (`$VAR`, `${...}`, `$(...)`, a backtick) stands in a word as this one character. The input itself may not contain it
+ * (`commands` refuses a NUL), so a word has it only where the hub put it: the word's value is unknown (#762).
+ */
+const OPAQUE = "\0";
+const opaque = (word: string | undefined): boolean => word !== undefined && word.includes(OPAQUE);
+
+/** The index after the bracket that closes `text[at]` (`(` or `{`), quotes and nested expansions respected, or -1 when it never closes. */
+function matching(text: string, at: number, nest = 0): number {
+  if (nest > 16) return -1;
+  const open = text[at]!, close = open === "(" ? ")" : "}";
+  let depth = 0;
+  for (let i = at; i < text.length; i++) {
+    const c = text[i]!;
+    if (c === "\\") { i++; continue; }
+    if (c === "'") { const end = text.indexOf("'", i + 1); if (end < 0) return -1; i = end; continue; }
+    if (c === "`") { const end = text.indexOf("`", i + 1); if (end < 0) return -1; i = end; continue; }
+    if (c === '"') {
+      for (i++; i < text.length && text[i] !== '"'; i++) {
+        if (text[i] === "\\") i++;
+        else if (text[i] === "$" && (text[i + 1] === "(" || text[i + 1] === "{")) { const end = matching(text, i + 1, nest + 1); if (end < 0) return -1; i = end - 1; }
+      }
+      if (i >= text.length) return -1;
+      continue;
+    }
+    if (c === "$" && (text[i + 1] === "(" || text[i + 1] === "{") && i + 1 !== at) { const end = matching(text, i + 1, nest + 1); if (end < 0) return -1; i = end - 1; continue; }
+    if (c === open) depth++;
+    else if (c === close && --depth === 0) return i + 1;
+  }
+  return -1;
+}
+
+/**
+ * The expansion that starts at `text[at]` (a `$` or a backtick): where it ends, the command texts it runs (`inners`: `$(...)` and a backtick
+ * run their text; `${...}` runs only the substitutions nested in its parameter text, never the text itself), and `drop` for a `$"` that only
+ * opens a quote. Undefined for a `$` that is a literal dollar. An expansion that never closes ends at the end of the text.
+ */
+function expansion(text: string, at: number, quoted: boolean, nest = 0): { end: number; inners: string[]; drop?: true } | undefined {
+  if (text[at] === "`") {
+    for (let i = at + 1; i < text.length; i++) {
+      if (text[i] === "\\") { i++; continue; }
+      if (text[i] === "`") return { end: i + 1, inners: [text.slice(at + 1, i)] };
+    }
+    return { end: text.length, inners: [] };
+  }
+  const next = text[at + 1];
+  if (next === "(") {
+    const end = matching(text, at + 1);
+    return end < 0 ? { end: text.length, inners: [] } : { end, inners: [text.slice(at + 2, end - 1)] };
+  }
+  if (next === "{") {                                       // parameter text is data: only the substitutions inside it run
+    const end = matching(text, at + 1);
+    const body = end < 0 ? text.slice(at + 2) : text.slice(at + 2, end - 1), inners: string[] = [];
+    for (let i = 0; i < body.length && nest < 4; i++) {
+      if (body[i] === "\\") { i++; continue; }
+      if (body[i] !== "$" && body[i] !== "`") continue;
+      const inner = expansion(body, i, false, nest + 1);
+      if (inner) { inners.push(...inner.inners); i = inner.end - 1; }
+    }
+    return { end: end < 0 ? text.length : end, inners };
+  }
+  if (next === "'") {                                       // $'...': ANSI-C quoting, whose escapes build the word
+    for (let i = at + 2; i < text.length; i++) { if (text[i] === "\\") i++; else if (text[i] === "'") return { end: i + 1, inners: [] }; }
+    return { end: text.length, inners: [] };
+  }
+  if (next === '"') return quoted ? undefined : { end: at + 1, inners: [], drop: true };
+  if (next !== undefined && /[A-Za-z_]/.test(next)) { let end = at + 2; while (end < text.length && /[A-Za-z0-9_]/.test(text[end]!)) end++; return { end, inners: [] }; }
+  if (next !== undefined && /[0-9@*#?$!-]/.test(next)) return { end: at + 2, inners: [] };
+  return undefined;
+}
+
+/** Shell words, literal where they can be read. An expansion becomes an opaque word and the commands it runs are read too; unsupported syntax discards only its unfinished segment. */
+function commands(text: string, nest = 0): Command[] | undefined {
   if (text.length > LIMIT || text.includes("\0") || !segmentLimit(text)) return;
   const result: Command[] = [];
   let words: string[] = [], outputs: string[] = [], word = "", active = false, quote = "";
@@ -40,7 +112,8 @@ function commands(text: string): Command[] | undefined {
     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 = []; };
+  let nested: Command[][] = [];
+  const finish = () => { flush(); if (words.length || outputs.length || nested.length) result.push({ words, outputs, ...(nested.length ? { nested } : {}) }); words = []; outputs = []; nested = []; };
   for (let i = 0; i < text.length; i++) {
     const c = text[i]!;
     if (quote === "'") { if (c === "'") quote = ""; else word += c; continue; }
@@ -51,7 +124,13 @@ function commands(text: string): Command[] | undefined {
       if (next !== "\n") word += next;
       active = true; continue;
     }
-    if (c === "$" || c === "`") return result;
+    if (c === "$" || c === "`") {
+      const found = expansion(text, i, quote === '"');
+      if (!found) { word += c; active = true; continue; }         // a lone `$` is a literal dollar
+      if (nest < 4) for (const text of found.inners) { const inner = commands(text, nest + 1); if (inner?.length) nested.push(inner); }
+      if (!found.drop) { word += OPAQUE; active = true; }
+      i = found.end - 1; continue;
+    }
     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; }
@@ -97,6 +176,14 @@ function outside(target: string, root: string, cwd: string): boolean {
   const rel = relative(resolve(root), resolve(cwd, target));
   return rel === ".." || rel.startsWith("../") || isAbsolute(rel);
 }
+/**
+ * A word that starts with an expansion may expand to a dash word (`$OPTS` as `-rf`), so a class that depends on a flag counts it as that flag
+ * (#762). Only the words before `--` can be options. A word that merely has an expansion later (`build/$X`, `--name=$X`) cannot start one.
+ */
+function mayBeFlag(words: readonly string[]): boolean {
+  const end = words.indexOf("--");
+  return words.slice(0, end < 0 ? undefined : end).some(w => w.startsWith(OPAQUE));
+}
 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));
@@ -130,7 +217,7 @@ function commandHeads(words: string[], values: readonly string[], booleans: read
       continue;
     }
     if (!uncertain) return [{ name: word, args: words.slice(i + 1) }];
-    if (actions.includes(word)) heads.push({ name: word, args: words.slice(i + 1) });
+    if (actions.includes(word) || opaque(word)) heads.push({ name: word, args: words.slice(i + 1) });
   }
   return heads;
 }
@@ -153,6 +240,7 @@ function forcedClean(words: string[]): boolean {
         if (flag === "n") dry = true;
       }
     }
+    else if (word.startsWith(OPAQUE)) force = true;   // an expansion may be `-f`; a literal dry run still wins (#762)
   }
   return force && !dry;
 }
@@ -182,12 +270,110 @@ function unwrapped(input: string[]): string[] {
       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 [];
+      const duration = words.shift() ?? "";
+      if (!/^\d+(?:\.\d+)?[smhd]?$/.test(duration) && !opaque(duration)) return [];
     }
   }
   return [];
 }
 
+/**
+ * Whether every definition of a GraphQL document is a read: a `query` (or shorthand `{...}`) or a `fragment`. Strings and comments are skipped, so
+ * a keyword inside one counts for nothing. A `mutation`, a `subscription`, any other top-level word, unbalanced text or no operation is false:
+ * unknown is never a read.
+ */
+function graphqlQueryOnly(text: string): boolean {
+  const skipString = (at: number): number => {              // `at` is the opening quote; the index after the string, or -1 when it never ends
+    // A block string ends at its first `"""`: GraphQL's escaped `\"""` ends it later, so a lexer that ends early only turns a read into a write (the strict direction).
+    if (text.startsWith('"""', at)) { const end = text.indexOf('"""', at + 3); return end < 0 ? -1 : end + 3; }
+    // GraphQL's line terminators are LF, CR and CRLF, and none may appear in a single-line string: ending early is the strict direction.
+    for (let i = at + 1; i < text.length; i++) { if (text[i] === "\\") { i++; if (text[i] === "\n" || text[i] === "\r") return -1; } else if (text[i] === '"') return i + 1; else if (text[i] === "\n" || text[i] === "\r") return -1; }
+    return -1;
+  };
+  const skipComment = (at: number): number => { let i = at; while (i < text.length && text[i] !== "\n" && text[i] !== "\r") i++; return i; };   // a comment ends at LF or CR (so also CRLF), never later than GraphQL ends it
+  const closers: Record<string, string> = { "{": "}", "(": ")", "[": "]" };
+  const skipBlock = (at: number): number => {             // `at` is an opening bracket; the index after its matching close, or -1
+    const close = closers[text[at]!]!;
+    for (let i = at + 1; i < text.length; i++) {
+      const c = text[i]!;
+      if (c === '"') { const end = skipString(i); if (end < 0) return -1; i = end - 1; }
+      else if (c === "#") i = skipComment(i) - 1;
+      else if (c in closers) { const end = skipBlock(i); if (end < 0) return -1; i = end - 1; }
+      else if (c === "}" || c === ")" || c === "]") return c === close ? i + 1 : -1;
+    }
+    return -1;
+  };
+  let start = true, operations = 0;                          // `start`: the next token begins a top-level definition
+  for (let i = 0; i < text.length;) {
+    const c = text[i]!;
+    if (/[\s,\uFEFF]/.test(c)) { i++; continue; }
+    if (c === "#") { i = skipComment(i); continue; }
+    if (c === "{") { const end = skipBlock(i); if (end < 0) return false; if (start) operations++; i = end; start = true; continue; }   // shorthand query, or the body that ends a definition
+    if (c === "(") { if (start) return false; const end = skipBlock(i); if (end < 0) return false; i = end; continue; }
+    const name = /^[A-Za-z_][A-Za-z0-9_]*/.exec(text.slice(i, i + 256))?.[0];
+    if (name) {
+      if (start) { if (name === "query") operations++; else if (name !== "fragment") return false; start = false; }
+      i += name.length; continue;
+    }
+    if (!start && (c === "@" || c === ":")) { i++; continue; }   // a directive, or `fragment X on Y`; nothing else is read at the top level
+    return false;
+  }
+  return start && operations > 0;
+}
+
+/**
+ * `gh api graphql` with fields (#756): undefined when the call does not name the graphql endpoint, true only for ONE literal `query` field whose
+ * every operation is a read. A query from a file or stdin (`@file`, `--input`), a second `query` field, an option this does not know,
+ * another positional and every unparsable document are false: the caller keeps them external-write.
+ */
+function ghGraphqlRead(words: string[]): boolean | undefined {
+  const rest = words.slice(1);                                   // `words` is `api ...`
+  if (!rest.includes("graphql")) return undefined;
+  const fieldOptions = ["-f", "-F", "--field", "--raw-field"];
+  const valued = ["-H", "--header", "--hostname", "-q", "--jq", "-t", "--template", "--cache", "-p", "--preview", "-X", "--method"];
+  const booleans = ["--paginate", "--slurp", "--silent", "-i", "--include", "--verbose"];
+  const positional: string[] = [], queries: string[] = [];
+  for (let i = 0; i < rest.length; i++) {
+    const word = rest[i]!;
+    if (word === "--" || !word.startsWith("-")) { positional.push(word); continue; }
+    let field: string | undefined;
+    if (fieldOptions.includes(word)) { field = rest[++i]; if (field === undefined) return false; }
+    else if (word.startsWith("--field=") || word.startsWith("--raw-field=")) field = word.slice(word.indexOf("=") + 1);
+    else if (/^-[fF][^=]/.test(word)) field = word.slice(2);
+    else if (valued.includes(word)) { if (++i >= rest.length) return false; }
+    else if (valued.some(key => key.startsWith("--") ? word.startsWith(`${key}=`) : /^-[HqtpX]./.test(word) && word.startsWith(key))) continue;
+    else if (!booleans.includes(word)) return false;
+    if (field !== undefined) {
+      const eq = field.indexOf("=");
+      if (eq < 0) return false;
+      if (field.slice(0, eq) === "query") queries.push(field.slice(eq + 1));
+    }
+  }
+  const method = option(rest, "-X", "--method");
+  if (method !== undefined && method.toUpperCase() !== "POST") return false;
+  const [query] = queries;
+  if (queries.some(opaque)) return false;                                 // an expansion can close a brace or add an operation: unknown is never a read
+  if (positional.length !== 1 || positional[0] !== "graphql" || queries.length !== 1 || query === undefined || query.startsWith("@")) return false;
+  return graphqlQueryOnly(query);
+}
+
+/**
+ * `gh api` with a word the hub cannot read where an option may stand (#762): an option name with an expansion in it, or a later operand that
+ * starts with one (`gh api repos/o/r $FLAGS`, which can hold `-X POST`). The endpoint (the first operand) and the values of the known valued
+ * options are data. Method, field and query values are judged by the ordinary rules, where an unknown method is never GET.
+ */
+function ghApiDynamic(words: string[]): boolean {
+  const valued = ["-H", "--header", "--hostname", "-q", "--jq", "-t", "--template", "--cache", "-p", "--preview", "-X", "--method", "-f", "-F", "--field", "--raw-field", "--input"];
+  let operands = 0;
+  for (let i = 1; i < words.length; i++) {
+    const word = words[i]!;
+    if (word === "--") return words.slice(i + 1).some((w, n) => opaque(w) && operands + n > 0);
+    if (word.startsWith("-")) { if (opaque(word)) return true; if (valued.includes(word)) i++; continue; }
+    if (operands++ > 0 && word.startsWith(OPAQUE)) return true;
+  }
+  return false;
+}
+
 /** Scan curl options once: data, headers and other option values never become options. */
 function curlWrites(input: string[]): boolean {
   const longValues = new Set([
@@ -249,7 +435,7 @@ function sequence(parsed: Command[], root: string, initial: string[], found: Set
     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 (program === "cd" && (!target || target.startsWith("~") || opaque(target))) {   // an unknown directory is an unknown cwd
       if (!cwd.has("") && cwd.size >= 128) cwd.delete(cwd.values().next().value!);
       cwd.add("");
     }
@@ -262,6 +448,7 @@ function sequence(parsed: Command[], root: string, initial: string[], found: Set
   }
 }
 function classify(command: Command, root: string, cwd: string[], found: Set<ActionClass>, depth = 0): void {
+  for (const group of command.nested ?? []) sequence(group, root, cwd, found, depth);   // a substitution's own cwd state; only its classes come back
   const words = unwrapped(command.words);
   const program = basename(words.shift() ?? "");
   if (["sh", "bash", "zsh"].includes(program) && depth < 2) {
@@ -270,7 +457,7 @@ function classify(command: Command, root: string, cwd: string[], found: Set<Acti
     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]);
+      const nested = shell[0] === undefined ? undefined : commands(shell[0].replaceAll(OPAQUE, "$_"));
       if (nested) sequence(nested, root, cwd, found, depth + 1);
     }
   }
@@ -278,11 +465,12 @@ function classify(command: Command, root: string, cwd: string[], found: Set<Acti
   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"]);
+    if (heads.some(head => opaque(head.name))) { found.add("publish"); found.add("destroy"); }   // `git $CMD`: the strictest classes git reaches (#762)
     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 === "reset" && (args.some(w => w === "--hard" || w.startsWith("--hard=")) || mayBeFlag(args))) 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 (sub === "branch" && (flags(args, "D") || args.includes("--delete") && args.includes("--force") || mayBeFlag(args))) found.add("destroy");
     }
   }
   if (["npm", "cargo", "pnpm", "yarn", "bun"].includes(program)) {
@@ -300,8 +488,9 @@ function classify(command: Command, root: string, cwd: string[], found: Set<Acti
     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 (opaque(sub) && program !== "bun") { found.add("publish"); found.add("install"); }   // `npm $CMD`; bun runs a file by default, so its expansion is no subcommand (#762)
         if (sub === "publish") found.add("publish");
-        const global = words.includes("--global") || flags(words, "g");
+        const global = words.includes("--global") || flags(words, "g") || mayBeFlag(words);
         if ((program === "cargo" && sub === "install") || (["install", "i", "add"].includes(sub) && global) || (program === "yarn" && sub === "global" && args[0] === "add")) found.add("install");
       }
     }
@@ -310,20 +499,25 @@ function classify(command: Command, root: string, cwd: string[], found: Set<Acti
   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") {
+    if (opaque(words[0])) { found.add("publish"); found.add("external-write"); }   // `gh $GROUP ...`: the strictest classes gh reaches (#762)
+    else if (opaque(words[1]) && ["release"].includes(words[0] ?? "")) found.add("publish");
+    else if (opaque(words[1]) && ["issue", "pr", "gist", "run", "workflow", "repo", "secret", "variable", "label"].includes(words[0] ?? "")) found.add("external-write");
+    if (words[0] === "repo" && ["delete", "archive", "edit"].includes(words[1] ?? "") || ["secret", "variable"].includes(words[0] ?? "") && ["set", "delete"].includes(words[1] ?? "") || words[0] === "label" && ["create", "edit", "delete"].includes(words[1] ?? "")) found.add("external-write");
+    if (words[0] === "run" && ["rerun", "cancel", "delete"].includes(words[1] ?? "") || words[0] === "workflow" && ["run", "enable", "disable"].includes(words[1] ?? "")) found.add("external-write");
+    if (words[0] === "api" && ghGraphqlRead(words) !== true) {   // a GraphQL document of queries only is a read (#756); everything else keeps the REST rule
       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 (method ? !["GET", "HEAD"].includes(method.toUpperCase()) : field || ghApiDynamic(words)) 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"))) {
+  if (program === "rm" && (flags(words, "r") || flags(words, "R") || words.includes("--recursive") || operands(words).length > 1 && mayBeFlag(words)) && operands(words).some(p => opaque(p) /* an expansion may hold `..` or an absolute path (#762) */ || cwd.some(at => outside(p, root, at)))) found.add("destroy");
+  if (["cp", "mv"].includes(program) && (flags(words, "f") || words.includes("--force") || words.length > 2 && mayBeFlag(words.slice(0, -1)))) {   // with two words the first cannot be a flag: `cp -f x` has no target
     const target = option(words, "-t", "--target-directory") ?? operands(words).at(-1);
-    if (target && cwd.some(at => outside(target, root, at))) found.add("destroy");
+    if (target && (opaque(target) || cwd.some(at => outside(target, root, at)))) found.add("destroy");
   }
 }
 

package/src/hub/action-enforce.ts

@@ -1,5 +1,5 @@
 import { ACTION_CLASSES, classifyAction, type ActionClass } from "./action-class.ts";
-import { actionApprovalText, actionPolicyConfig, type ActionBudgets, type ActionPolicyConfig } from "./action-policy.ts";
+import { actionApprovalView, actionPolicyConfig, type ActionBudgets, type ActionPolicyConfig } from "./action-policy.ts";
 import type { ActionGateVerdict } from "../adapters/acp.ts";
 
 /**
@@ -66,14 +66,22 @@ export interface ActionGatePorts<T> {
  * within an approved class budget, and every unclassed call, return undefined and follow the permission mode as before (the budget
  * spends here, once per request).
  */
-export function actionGate<T>(ports: ActionGatePorts<T>, peer: string): (call: ActionCall, session: string) => ActionGateVerdict | undefined {
-  return (call, session) => {
+export function actionGate<T>(ports: ActionGatePorts<T>, peer: string): (call: ActionCall, session: string, onPremToolTitle?: string) => ActionGateVerdict | undefined {
+  return (call, session, onPremToolTitle) => {
     const classes = classifyCall(call, ports.root(peer));
     if (!classes.length) return undefined;
     const decision = ports.budgets.request(ports.budgets.bindSession(peer, session), classes);
     if (decision.kind !== "ask") return undefined; // native, or within an approved class budget
-    const title = actionApprovalText(decision.classes, commandText(call.input), ports.task(peer), {
-      publicView: task => ports.publicView(task), private: ports.isPrivate(peer), commandView: command => ports.nameable(command) ? command : undefined });
+    // Only the host's local/Pi permit callback supplies this full title. Match the exact executed tool form before bypassing public redaction.
+    const input = call.input && typeof call.input === "object" && !Array.isArray(call.input) ? call.input as Record<string, unknown> : undefined;
+    const expected = call.names.includes("bash") && typeof input?.command === "string" ? `bash: ${input.command}`
+      : call.names.includes("git") && Array.isArray(input?.args) && input.args.every(word => typeof word === "string") ? `git ${input.args.join(" ")}` : undefined;
+    const complete = expected !== undefined && expected === onPremToolTitle;
+    const view = onPremToolTitle === undefined ? actionApprovalView(decision.classes, commandText(call.input), ports.task(peer), {
+      publicView: task => ports.publicView(task), private: ports.isPrivate(peer), commandView: command => ports.nameable(command) ? command : undefined })
+      : { title: `Action approval (${decision.classes.join(", ")})\n${complete ? onPremToolTitle : "[complete command unavailable]"}`, complete };
+    const { title } = view;
+    if (!view.complete) return { title, denyOnly: true };
     const challenge = decision.challenge, limits = actionPolicyConfig(ports.policy()).budgets;
     // A budget of one is this call alone: the ordinary allow already says that, so no second choice is offered for it.
     if (!challenge || !decision.classes.some(key => limits[key] > 1)) return { title };