@staix/agent-hub 0.14.0 → 0.16.0

package/src/cli/main.ts

@@ -1,4 +1,6 @@
 #!/usr/bin/env bun
+import type { DeliverableRow } from "../hub/tasks.ts";
+import { kimiSourceRow } from "../hub/budget-notes.ts";
 import { hubGitSync, hubGitEnv } from "../hub/git.ts";
 import { parseReleaseGuardArgv, parseReleasePushUpdates } from "./sdlc-release-guard.ts";
 import { validReleaseVersion } from "../hub/sdlc-release-authorization.ts";
@@ -18,6 +20,7 @@ import { matchesPolicy } from "../hub/path-policy.ts";
 import { projectedDiff } from "../hub/projected-diff.ts";
 import { TextProjections } from "../hub/text-projection.ts";
 import { terminalText } from "./console-state.ts";
+import { parseSettingsEditArgs, runSettingsEdit, SETTINGS_EDIT_USAGE } from "./settings-edit.ts";
 import { petView, readPet, renderPet } from "./pet.ts";
 import { startPetWindow, closePetWindow } from "../pet/window.ts";
 import { loadPetConfig, savePetPalette } from "./pet-config.ts";
@@ -36,7 +39,7 @@ import { chmodSync, existsSync, readFileSync, renameSync, writeFileSync } from "
 import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
 import { basename, dirname, join, relative, resolve } from "node:path";
-import { ControlClient, readControl } from "../hub/control-client.ts";
+import { retryLaunchConnect, ControlClient, readControl } from "../hub/control-client.ts";
 import { loadConfig } from "../hub/daemon.ts";
 import { factsHook } from "./facts-hook.ts";
 import { hubHome, projectContext, projectRoot, realPath } from "../hub/project.ts";
@@ -45,7 +48,6 @@ import { inspectProject, startProject, stopProject, runProjectDaemon } from "../
 import { processLiveness, processSignature } from "../pi/process-signature.ts";
 import { openManager, startManager, stopManager } from "../hub/manager.ts";
 import { OmniRoute } from "../omniroute/client.ts";
-import { MemoryClient } from "../memory/client.ts";
 import { init, planInit } from "./init.ts";
 import { launcherPreview } from "./preview.ts";
 import { instanceLaunchArguments, requirePeerInstances, requireActiveInstance, cleanupStaleClaudeSettings, cleanupClaudeSettings, buildLaunch, buildKimiTuiLaunch, claudeObservationHooks, nativeLaunchEnv, recordClaudeLaunch, runClaudeLaunch, type ClaudeLaunchRecord, UNATTENDED_WARNING } from "./launch.ts";
@@ -74,8 +76,9 @@ import { parseSince, readEvents } from "../hub/events.ts";
 import { armRuns, benchCompare, benchCsv, benchReport, formatCompare, formatReport as formatBenchReport, formatRuns, MEMORY_MODES, readRuns, runSummary, sameSuite, type MemoryMode } from "../hub/bench.ts";
 import { benchPreflight, defaultIo, runBench } from "./bench.ts";
 import { ADDONS, isAddon, type AddonName } from "../hub/tooling.ts";
-import { goalCommand, memoryCommand } from "./memory.ts";
-import { selectedMemoryProfile } from "../hub/memory-profile.ts";
+import { goalCommand, memoryCommand, memoryStaleAnchorsCommand } from "./memory.ts";
+import { formatMemoryStaleAnchors } from "../hub/memory-stale-anchors.ts";
+import { AGENT_MEM_VERSION, assertAgentMemVersion, selectedMemoryProfile } from "../hub/memory-profile.ts";
 import { checkMemoryProfiles, formatMemoryProfileCheck } from "../hub/memory-profile-check.ts";
 import { addonReport, appendRecords, formatAddons, formatResearch, LABELS, labelTarget, RESEARCH_SCHEMA, projectKey, readStores, researchReport, taskRecords, toCsv, type Label, type TaskRecord } from "../hub/research.ts";
 import { summarize, summarizeByTask } from "../hub/report.ts";
@@ -89,7 +92,7 @@ import { agentShellCause, classifyPeerCommand, cliCommandLabel, detectCliIdentit
 import { recordCliAudit, recordDelegatedCliAudit } from "./identity-audit.ts";
 import { runConsole } from "./console.ts";
 import { paint, permissionBoundary, resolveColor, wrap, type Span } from "./console-state.ts";
-import { outputWidth, renderRoster, renderStatus, renderBoard, renderBoardColumns, boardColumnModel, renderBudget, renderDoctor, renderProjects, renderQueue, renderTurns, renderOrphans, renderQueueShow, renderModelsStatus, renderExecutionBudgetStatus, renderReport, renderUsage, renderLimits, renderTotal, type DoctorCheck } from "./output.ts";
+import { outputWidth, renderRoster, renderStatus, renderBoard, renderBacklog, renderBoardColumns, boardColumnModel, renderBudget, renderDoctor, renderProjects, renderQueue, renderTurns, renderOrphans, renderQueueShow, renderModelsStatus, renderExecutionBudgetStatus, renderReport, renderUsage, renderLimits, renderTotal, type DoctorCheck } from "./output.ts";
 import { renderHelp, configuredAcpHelp } from "./help.ts";
 import { renderTailEvent } from "./tail-render.ts";
 import { archiveProblem, archiveState, damagedState, failureText, MANIFEST, planReset, resetLines, resetRuntime, startState, type ResetPlan } from "./reset.ts";
@@ -274,13 +277,15 @@ function printOutput(lines: Span[][], color: boolean): void {
 }
 const unattendedEnv = process.env.AGENTHUB_UNATTENDED === "1";
 const lifecycle = { inspectProject, startProject, stopProject };
-const connect = async () => {
+const connect = async (timeoutMs = 3000) => {
   assertDelegatedAuditConsumer();
   if (delegatedAuditHub && !delegatedConnectionTaken) { delegatedConnectionTaken = true; return delegatedAuditHub; }
   return ControlClient.connect(stateDir, identity.role === "tools" ? { role: "tools", peer: identity.peer, projectRoot: cwd }
-    : { role: "console", projectRoot: cwd, ...(delegatedAuditHub ? { instanceId: delegatedAuditHub.instanceId } : {}) });
+    : { role: "console", projectRoot: cwd, ...(delegatedAuditHub ? { instanceId: delegatedAuditHub.instanceId } : {}) }, timeoutMs);
 };
 
+const connectLaunch = () => retryLaunchConnect(connect, () => console.error("hub busy, retrying"));
+
 function registeredProject(): Project {
   const registry = new Registry();
   try { return registry.register(cwd, stateDir); }
@@ -943,7 +948,7 @@ const commands: Record<string, () => Promise<void> | void> = {
     // Preserve the original guard before native effects; previews remain read-only and precede this guard.
     if (entry.lifecycleAdmission && !args.includes("--print-command") && !args.includes("--dry-run")) assertLifecycleAvailable();
     const nativeConnect = async () => {
-      const hub = await connect();
+      const hub = await connectLaunch();
       try { if (selectedInstance) { requirePeerInstances(hub.features); requireActiveInstance((await hub.request({ t: "status" })).status, selectedInstance); } return hub; }
       catch (error) { hub.close(); throw error; }
     };
@@ -955,7 +960,10 @@ const commands: Record<string, () => Promise<void> | void> = {
       projectConfig, connect: nativeConnect, fail,
       exec: (bin, argv, tool) => exec(bin, argv, tool, context.executionCwd),
       execWithEnv: (bin, argv, env) => execWithEnv(bin, argv, env, selectedInstance ?? entry.command, context.executionCwd), takeFlags,
-      helpers: { launcherPreview: (tool, raw, projectRoot, state, unattended) => launcherPreview(tool, raw, projectRoot, state, unattended, selectedInstance), readControl, recordTerminalLaunch, prepareTerminalLaunch, registerTerminalLaunch, recoveryLock, processSignature,
+      helpers: { resolveExecutionCwd: peer => {
+        const current = readInstanceRoleConfig(cwd);
+        return resolveInstanceExecutionCwd(cwd, peer, current.instances, effectiveInstanceRoles(peer, current.instances, current.roles, current.catalog), current.catalog);
+      }, launcherPreview: (tool, raw, projectRoot, state, unattended) => launcherPreview(tool, raw, projectRoot, state, unattended, selectedInstance), readControl, recordTerminalLaunch, prepareTerminalLaunch, registerTerminalLaunch, recoveryLock, processSignature,
         buildLaunch, claudeObservationHooks, recordClaudeLaunch, cleanupStaleClaudeSettings, cleanupClaudeSettings,
         nativeLaunchEnv, runClaudeLaunch, childEnv, qwenSessionId, configureJcodeMcp, configureKimiMcp,
         buildKimiTuiLaunch, startModeOf },
@@ -1134,14 +1142,22 @@ const commands: Record<string, () => Promise<void> | void> = {
     const res = await hub.request({ t: "budget", ...(set ? { set } : {}) });
     hub.close();
     if (!res.ok) fail(res.error);
-    const data = { budget: res.budget, gate: res.gate };
+    const data = { budget: res.budget, ...(res.peers ? { peers: res.peers } : {}), gate: res.gate };
     if (options.json) return console.log(JSON.stringify(data, null, 2));
     printOutput(renderBudget(data, options.columns, Date.now(), options.full), options.color);
   },
 
   backlog: async () => {
     const [sub, id, revision, value, ...reason] = args;
-    if (sub === "list" && args.length === 1) return console.log(await taskOp("hub_backlog_list", {}));
+    if (sub === "list" && outputArguments().length === 1) {
+      // #399: a table by default; --json prints the hub's listing unchanged, and a refusal is printed as it came.
+      const options = outputOptions(), raw = await taskOp("hub_backlog_list", {});
+      if (options.json) return console.log(raw);
+      let cards: unknown;
+      try { cards = JSON.parse(raw); } catch { return console.log(raw); }
+      if (!Array.isArray(cards)) return console.log(raw);
+      return printOutput(renderBacklog(cards, options.columns, Date.now(), options.full), options.color);
+    }
     if (sub === "groom" && args.length === 1) return console.log(await taskOp("hub_planner_groom", {}));
     if (["return", "return-untouched"].includes(sub ?? "") && /^[1-9]\d*$/.test(id ?? "") && /^\d+$/.test(revision ?? "") && args.length >= 4) {
       return console.log(await taskOp("hub_backlog_return_untouched", { id: Number(id), revision: Number(revision), reason: args.slice(3).join(" ") }));
@@ -1181,6 +1197,27 @@ const commands: Record<string, () => Promise<void> | void> = {
     console.log(await taskOp("release_change", { name, revision: Number(revision), fields }));
   },
 
+  deliverables: async () => {
+    // #317: what each task delivered and what a reviewer approved, by id, hash and size (a path only where the PII screen allows it). Person only: the daemon refuses an agent.
+    const options = outputOptions();
+    const { one, rest } = takeFlags(args, ["--task"], []);
+    const approved = rest.includes("--approved"), check = rest.includes("--check");
+    const extra = rest.filter(arg => !["--json", "--full", "--approved", "--check"].includes(arg) && !arg.startsWith("--color="));
+    const task = one["--task"] === undefined ? undefined : Number(one["--task"]);
+    // takeFlags keeps the last of a repeated flag: for a command that selects a task that would silently drop one of two named tasks.
+    if (args.filter(arg => arg === "--task").length > 1) fail("usage: ahub deliverables [--task <id>] [--approved] [--check] [--json] [--color=auto|always|never] (--task takes one id)");
+    if (extra.length || (one["--task"] !== undefined && !/^[1-9]\d*$/.test(one["--task"])) || (task !== undefined && !Number.isSafeInteger(task))) fail("usage: ahub deliverables [--task <id>] [--approved] [--check] [--json] [--color=auto|always|never]");
+    const rows = JSON.parse(await taskOp("deliverables", { ...(task === undefined ? {} : { task }), ...(approved ? { approved: true } : {}), ...(check ? { check: true } : {}) })) as DeliverableRow[];
+    if (options.json) return console.log(JSON.stringify(rows, null, 2));
+    if (!rows.length) return console.log(task === undefined ? `no ${approved ? "approved " : ""}deliverables on the board` : `task #${task} has no ${approved ? "approved " : ""}deliverables`);
+    for (const row of rows) {
+      const flag = row.checked ? ({ changed: " (changed since review)", missing: " (a file is missing)", unknown: " (could not be measured)", unchanged: " (unchanged)" } as const)[row.result ?? "unknown"] : "";
+      console.log(`${row.title} [${row.state}${flag}]`);                                   // `title` is the hub's publicTitle: it already starts with `#<id>`
+      for (const file of row.files) console.log(`  ${file.id}  ${file.path ?? "(private)"}  ${file.format}${file.version ? ` ${file.version}` : ""}  ${file.bytes} B  sha256 ${file.sha256}${file.state ? `  ${file.state}` : ""}`);
+    }
+    if (!check) console.log("(hashes are the board's records; add --check to measure the files now)");
+  },
+
   board: async () => {
     if (args[0] === "import") {
       if (args[1] !== "github" || (args.length - 2) % 2 !== 0) fail("usage: ahub board import github --label <label> [--milestone <milestone>] [--repo <owner/repo>]");
@@ -1366,8 +1403,8 @@ const commands: Record<string, () => Promise<void> | void> = {
     if (sub === "assign") {
       const { one, rest: positional } = takeFlags(rest, ["--role", "--revision"], []);
       const role = one["--role"] ?? "owner", rawRevision = one["--revision"], revision = rawRevision === undefined ? undefined : Number(rawRevision);
-      if (positional.length !== 2 || !["owner", "reviewer"].includes(role) || (rawRevision !== undefined && (!/^\d+$/.test(rawRevision) || !Number.isSafeInteger(revision)))) fail("usage: ahub task assign <id> <peer> [--role owner|reviewer] [--revision N]");
-      return console.log(await taskOp(revision === undefined ? "task_assign" : "task_assign_checked", { id: positional[0], peer: positional[1], ...(role === "reviewer" ? { role } : {}), ...(revision === undefined ? {} : { revision }) }));
+      if (positional.length !== 2 || !["owner", "reviewer", "planner"].includes(role) || (rawRevision !== undefined && (!/^\d+$/.test(rawRevision) || !Number.isSafeInteger(revision)))) fail("usage: ahub task assign <id> <peer> [--role owner|reviewer|planner] [--revision N]");
+      return console.log(await taskOp(revision === undefined ? "task_assign" : "task_assign_checked", { id: positional[0], peer: positional[1], ...(role !== "owner" ? { role } : {}), ...(revision === undefined ? {} : { revision }) }));
     }
     if (sub === "unassign") {
       const { one, rest: positional } = takeFlags(rest, ["--role", "--revision"], []);
@@ -1509,7 +1546,31 @@ const commands: Record<string, () => Promise<void> | void> = {
     } finally { hub.close(); }
   },
   settings: async () => {
-    const usage = "usage: ahub settings [list] [--json] | get <key> [--json] | set <key> <value|inherit> [--yes] [--preview] | undo | reload";
+    // #689: structural config edits (instances, review, snapshots, approvals, context.gate, sdlc.toml) and their backups. The hub validates and writes.
+    if (args[0] === "edit" || args[0] === "backups") {
+      // A command line the parser refuses never reaches the hub, not even as a connection.
+      const early = args[0] === "backups" ? (args.length > 2 || (args[1] !== undefined && args[1] !== "--json") ? SETTINGS_EDIT_USAGE : undefined) : (() => { const parsed = parseSettingsEditArgs(args.slice(1)); return typeof parsed === "string" ? parsed : undefined; })();
+      if (early) fail(early);
+      const hub = await connect();
+      try {
+        const rl = process.stdin.isTTY ? createInterface({ input: process.stdin, output: process.stdout }) : undefined;
+        const usage = await runSettingsEdit(args, {
+          request: async message => {
+            const reply = await hub.request(message, 35_000);
+            if (reply.ok !== true) {
+              const error = String(reply.error ?? "config edit refused");
+              fail(/unknown (?:control )?(?:message|request|command)(?:\b|:)|this hub does not know "config_edit/i.test(error) ? `${error}; upgrade and restart the running hub to use ahub settings edit` : error);
+            }
+            return reply;
+          },
+          ask: async prompt => { if (!rl) return null; try { return await rl.question(prompt); } catch { return null; } },
+          print: line => console.log(terminalText(line)),
+        }).finally(() => rl?.close());
+        if (usage) fail(usage);
+      } finally { hub.close(); }
+      return;
+    }
+    const usage = "usage: ahub settings [list] [--json] | get <key> [--json] | set <key> <value|inherit> [--yes] [--preview] | undo | reload | edit <file> ... | backups";
     const flags = args.filter((arg) => arg.startsWith("--")), [sub = "list", key, text, ...extra] = args.filter((arg) => !arg.startsWith("--"));
     const allowed: Record<string, string[]> = { list: ["--json"], get: ["--json"], set: ["--yes", "--preview", "--now"], undo: [], reload: [] };
     if (!Object.hasOwn(allowed, sub) || flags.some((flag) => !allowed[sub]!.includes(flag)) || extra.length) fail(usage);
@@ -2063,6 +2124,12 @@ const commands: Record<string, () => Promise<void> | void> = {
 
   doctor: async () => {
     const options = outputOptions();
+    if (args.includes("--stale-anchors")) {
+      if (args.some(arg => arg !== "--stale-anchors" && arg !== "--json")) fail("usage: ahub doctor --stale-anchors [--json]");
+      const report = await memoryStaleAnchorsCommand(cwd, { stateDir });
+      console.log(options.json ? JSON.stringify(report, null, 2) : formatMemoryStaleAnchors(report));
+      return;
+    }
     if (args.includes("--orphans")) return orphanDoctor(args.includes("--kill"), options);
     const version = (bin: string) => {
       const res = spawnSync(bin, ["--version"], { encoding: "utf8" });
@@ -2090,6 +2157,10 @@ const commands: Record<string, () => Promise<void> | void> = {
           const { status } = await hub.request({ t: "status" });
           const pending = Object.values(status.peers as Record<string, PeerRow>).reduce((n, peer) => n + (peer.needsReview ?? 0), 0);
           row(!status.deliveryError && pending === 0, "delivery recovery", status.deliveryError ?? (pending ? `${pending} deliveries need review; run ahub queue list` : "journal healthy; no deliveries need review"));
+          // #285 AC10: where Kimi's number comes from, and whether the hub can trust it right now. An older hub answers without `kimiSource`: no row, not a failure.
+          const quota = await hub.request({ t: "budget" });
+          const kimiRow = quota.ok ? kimiSourceRow(quota.kimiSource) : undefined;
+          if (kimiRow) row(kimiRow.ok, "kimi usage source", kimiRow.detail);
           const observed = await hub.request({ t: "recovery", op: "inspect", expectedInstanceId: status.instanceId });
           for (const peer of Object.values(observed.recovery?.peers ?? {}) as { id: string; state: string; sessionId?: string; threadId?: string }[]) {
             const check = nativeDoctorRecoveryIdentity(peer);
@@ -2144,9 +2215,9 @@ const commands: Record<string, () => Promise<void> | void> = {
         row(mlx.state === "ready" || mlx.state === "stopped", "pi mlx", `${mlx.state}${mlx.model ? ` (${mlx.model})` : ""}${mlx.lastError ? `: ${mlx.lastError}` : ""}`);
       }
 
-      const memory = new MemoryClient();
-      const mem = await memory.health();
-      row(mem.ok, "memory worker", mem.ok ? `claude-mem ${mem.version ?? ""} at ${memory.url}` : `unavailable at ${memory.url} (the hub works without it)`);
+      let memoryLibraryReady = false;
+      try { assertAgentMemVersion({ name: "@staix/agent-mem", version: AGENT_MEM_VERSION }); memoryLibraryReady = true; } catch { /* report the failed exact pin without opening a store */ }
+      row(memoryLibraryReady, "memory library", memoryLibraryReady ? `amem ${AGENT_MEM_VERSION}; in-process, no claude-mem worker` : "installed amem does not match the exact dependency pin");
       const bridge = spawnSync("dot", ["ai", "memory", "status"], { encoding: "utf8" });
       const out = bridge.error ? "" : bridge.stdout.replace(/\x1b\[[0-9;]*m/g, "");
       for (const tool of DOCTOR_MEMORY_CAPTURE_PEERS) {
@@ -2222,7 +2293,8 @@ async function runConductorCommand(): Promise<void> {
     op = args[0] === "assign" ? "hub_task_assign" : "hub_task_escalate";
     const { one, rest: positional } = takeFlags(args.slice(1), args[0] === "assign" ? ["--role"] : [], []);
     const role = one["--role"] ?? "owner";
-    if (!positional[0] || positional.length !== (args[0] === "assign" ? 2 : 1) || !["owner", "reviewer"].includes(role)) fail("usage: ahub task assign <id> <peer> [--role owner|reviewer] | escalate <id>");
+    if (!positional[0] || positional.length !== (args[0] === "assign" ? 2 : 1) || !["owner", "reviewer", "planner"].includes(role)) fail("usage: ahub task assign <id> <peer> [--role owner|reviewer|planner] | escalate <id>");
+    if (role === "planner") fail("only the person may name a task planner");
     input = { id: Number(positional[0]), ...(args[0] === "assign" ? { peer: positional[1], ...(role === "reviewer" ? { role } : {}) } : {}) };
   } else if (cmd === "pause" || cmd === "resume") {
     if (args.length !== 1) fail(`usage: ahub ${cmd} <peer>`);
@@ -2254,7 +2326,7 @@ async function runConductorCommand(): Promise<void> {
 const runConfigured = configuredCommand ? async () => {
   const selection = parseConfiguredAcpArguments(cmd, args, projectCatalog, declaredInstances);
   if (!selection.preview) assertLifecycleAvailable();
-  await runConfiguredAcpEntry({ kind: cmd, raw: args, catalog: projectCatalog, instances: declaredInstances, connect, print: text => console.log(text), operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
+  await runConfiguredAcpEntry({ kind: cmd, raw: args, catalog: projectCatalog, instances: declaredInstances, connect: connectLaunch, print: text => console.log(text), operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
 } : undefined;
 const run = identity.role === "tools" && commandAccess === "conductor" ? runConductorCommand : (Object.hasOwn(commands, cmd) ? commands[cmd] : undefined) ?? runConfigured ?? (() => fail(`unknown command "${cmd}"; run ahub help`));
 try {

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"));
@@ -249,6 +253,7 @@ export function renderStatus(data: StatusOutput, columns?: number, now = Date.no
     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.ownerIsolationNote) out.push(...detail("owner isolation", p.ownerIsolationNote, columns, "attention"));
     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));
@@ -279,6 +284,33 @@ export function stageCode(next: string): string {
 }
 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 + "..."; })();
+/**
+ * #399: `ahub backlog list` as a table: one line per card, by rank (unranked last) then id. With a width, TITLE goes last and is
+ * cut like the compact board, and AGE then CLASS give way first on a narrow terminal; without one (piped) or with full, titles are whole.
+ */
+export function renderBacklog(cards: any[], columns?: number, now = Date.now(), full = false): Span[][] {
+  if (!cards.length) return [[span("no backlog cards")]];
+  const sorted = [...cards].sort((a, b) => (typeof a.rank === "number" ? a.rank : Infinity) - (typeof b.rank === "number" ? b.rank : Infinity) || a.id - b.id);
+  let names = ["RANK", "ID", "PRI", "RESERVED", "AFTER", "CLASS", "AGE", "TITLE"];
+  let table: OutputCell[][] = sorted.map(card => {
+    const deps: number[] = Array.isArray(card.deps) ? card.deps : [];
+    return [span(typeof card.rank === "number" ? card.rank : "-", "muted", true), span(`#${card.id}`, "info", true), span(typeof card.priority === "number" ? `P${card.priority}` : "-", undefined, true),
+      span(card.reserved ?? "-", peerTone(card.reserved ?? ""), true), span(deps.length ? (full || columns === undefined ? deps.map(id => `#${id}`).join(",") : `#${deps[0]}${deps.length > 1 ? `,+${deps.length - 1}` : ""}`) : "-", undefined, true), span(card.class ?? "-", undefined, true),
+      span(typeof card.created === "number" ? duration(now - card.created) : "-", "muted", true), span(flat(card.title))];
+  });
+  if (!full && columns !== undefined) {
+    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)); };
+    const room = () => columns - names.reduce((sum, name, i) => name === "TITLE" ? 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 ["AGE", "CLASS", "PRI"]) if (room() < want) drop(name);
+    const titleRoom = Math.max(5, room());
+    table = table.map(row => [...row.slice(0, -1), { ...row[row.length - 1]!, text: ellipsis(row[row.length - 1]!.text, titleRoom) }]);
+  }
+  const owners = new Map<string, number>();
+  for (const card of sorted) owners.set(card.reserved ?? "unreserved", (owners.get(card.reserved ?? "unreserved") ?? 0) + 1);
+  const summary = `${plural(sorted.length, "backlog card")}; reserved: ${[...owners].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).map(([owner, n]) => `${owner} ${n}`).join(", ")}`;
+  return [...rows(names, table, columns), [], ...lines(summary, columns)];
+}
 /** #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"];
@@ -330,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/reset.ts

@@ -11,7 +11,7 @@ import { HUB_DB_BUSY_TIMEOUT_MS } from "../hub/db-timeout.ts";
 /** Agent session resume pointers. `pi-sessions/` holds Pi transcripts, history rather than pointers, and stays. */
 export const SESSION_POINTERS = ["sessions.json", "claude-session.json", "claude-context.json"];
 /** The fixed pointers plus each Claude instance's own session and context files (#450 I3). */
-const sessionPointers = (stateDir: string): string[] => [...SESSION_POINTERS, ...(existsSync(stateDir) ? readdirSync(stateDir).filter(name => /^claude-(session|context)\.[a-z][a-z0-9-]{0,31}\.json$/.test(name)) : [])];
+const sessionPointers = (stateDir: string): string[] => [...SESSION_POINTERS, ...(existsSync(stateDir) ? readdirSync(stateDir).filter(name => /^claude-(session|context|task-sessions)\.[a-z][a-z0-9-]{0,31}\.json$/.test(name)) : [])];
 /** What a running daemon publishes; a daemon that did not stop cleanly (crash, SIGKILL, forced exit) leaves it. */
 export const MANIFEST = ["status.json", "control-token", "hub.pid"];
 

package/src/cli/settings-edit.ts

@@ -0,0 +1,89 @@
+/** #689: `ahub settings edit` and `ahub settings backups`. Parsing and rendering only; the hub validates, previews and writes. */
+export interface SettingsEditArgs { file: "config.local.json" | "sdlc.toml"; set: { path: string[]; value: unknown }[]; reason?: string; preview: boolean; yes: boolean }
+export const SETTINGS_EDIT_USAGE = "usage: ahub settings edit <config.local.json|sdlc.toml> (set <path> <json> | remove <path>)... [--reason <text>] [--preview] [--yes] | ahub settings backups [--json]";
+
+/** The request a command line asks for, or the usage line. Values are JSON, so a string needs its quotes. */
+export function parseSettingsEditArgs(argv: readonly string[]): SettingsEditArgs | string {
+  const [file, ...rest] = argv;
+  if (file !== "config.local.json" && file !== "sdlc.toml") return SETTINGS_EDIT_USAGE;
+  const set: SettingsEditArgs["set"] = [];
+  let reason: string | undefined, preview = false, yes = false;
+  const path = (text: string | undefined): string[] | undefined => {
+    if (!text || text.startsWith(".") || text.endsWith(".") || text.includes("..")) return undefined;
+    return text.split(".");
+  };
+  for (let index = 0; index < rest.length; index++) {
+    const word = rest[index]!;
+    if (word === "--preview") preview = true;
+    else if (word === "--yes") yes = true;
+    else if (word === "--reason") { reason = rest[++index]; if (reason === undefined) return SETTINGS_EDIT_USAGE; }
+    else if (word === "set") {
+      const target = path(rest[++index]), text = rest[++index];
+      if (!target || text === undefined) return SETTINGS_EDIT_USAGE;
+      try { set.push({ path: target, value: JSON.parse(text) }); } catch { return SETTINGS_EDIT_USAGE; }
+    } else if (word === "remove") {
+      const target = path(rest[++index]);
+      if (!target) return SETTINGS_EDIT_USAGE;
+      set.push({ path: target, value: null });
+    } else return SETTINGS_EDIT_USAGE;
+  }
+  if (!set.length) return SETTINGS_EDIT_USAGE;
+  return { file, set, ...(reason !== undefined ? { reason } : {}), preview, yes };
+}
+
+/** What a person reads before confirming: the diff lines, the warning of a tier 3 key and the word to type. */
+export function renderEditPreview(reply: { ok?: unknown; lines?: unknown; warning?: unknown; confirm?: unknown }): string[] {
+  const lines = Array.isArray(reply.lines) ? reply.lines.map(line => String(line)) : [];
+  if (typeof reply.warning === "string") lines.push(`warning: ${reply.warning}`);
+  if (typeof reply.confirm === "string") lines.push(`type ${reply.confirm} to confirm`);
+  return lines;
+}
+
+export interface SettingsEditPorts {
+  request: (message: Record<string, unknown>) => Promise<Record<string, unknown>>;
+  /** Asks one line on a terminal; null when there is none. */
+  ask: (prompt: string) => Promise<string | null>;
+  print: (line: string) => void;
+}
+/**
+ * The whole command, with its ports injected. The person's terminal is the only place a tier 3 key can be changed, and only by
+ * typing the key's name: `--yes` confirms an ordinary structural edit and never a tier 3 one.
+ */
+export async function runSettingsEdit(argv: readonly string[], ports: SettingsEditPorts): Promise<string | undefined> {
+  const { request, ask, print } = ports;
+  if (argv[0] === "backups") {
+    if (argv.length > 2 || (argv[1] !== undefined && argv[1] !== "--json")) return SETTINGS_EDIT_USAGE;
+    const view = await request({ t: "config_edit_get" });
+    const backups = Array.isArray(view.backups) ? view.backups as { name: string; file: string; at: number; bytes: number }[] : [];
+    if (argv[1] === "--json") print(JSON.stringify(backups, null, 2));
+    else if (!backups.length) print("no config backups yet");
+    else for (const item of backups) print(`${new Date(item.at).toISOString()}  ${item.file}  ${item.bytes} bytes  ${item.name}`);
+    return undefined;
+  }
+  const parsed = parseSettingsEditArgs(argv[0] === "edit" ? argv.slice(1) : argv);
+  if (typeof parsed === "string") return parsed;
+  const view = await request({ t: "config_edit_get" });
+  const revisions = view.revisions as Record<string, string> | undefined;
+  const revision = revisions?.[parsed.file];
+  if (typeof revision !== "string") return "the running hub does not report config revisions: upgrade and restart it to use ahub settings edit";
+  const body = { file: parsed.file, revision, set: parsed.set };
+  const preview = await request({ t: "config_edit_preview", edit: body });
+  for (const line of renderEditPreview(preview)) print(line);
+  if (parsed.preview) { print("preview only; nothing was changed"); return undefined; }
+  const typed = typeof preview.confirm === "string" ? preview.confirm : undefined;
+  let confirm: string | undefined;
+  if (typed) {
+    const answer = await ask(`Type ${typed} to confirm: `);
+    if (answer === null) return "not a terminal: a key that runs code or locates secrets is confirmed by typing its name; nothing was changed";
+    if (answer.trim() !== typed) { print("nothing was changed"); return undefined; }
+    confirm = typed;
+  } else if (!parsed.yes) {
+    const answer = await ask("Write this change? [y/N] ");
+    if (answer === null) return "not a terminal: nothing was changed; rerun with --yes after reviewing the preview";
+    if (!/^(y|yes)$/i.test(answer.trim())) { print("nothing was changed"); return undefined; }
+  }
+  const result = await request({ t: "config_edit_apply", edit: body, ...(confirm ? { confirm } : {}), ...(parsed.reason !== undefined ? { reason: parsed.reason } : {}) });
+  print(String(result.text ?? "config written"));
+  if (Array.isArray(result.restartPending) && result.restartPending.length) print(`restart pending: ${result.restartPending.join(", ")}; restart the hub (ahub restart) to apply`);
+  return undefined;
+}