@staix/agent-hub 0.12.45 → 0.14.0

package/src/hub/daemon.ts

@@ -1,3 +1,8 @@
+import { InboxPolling } from "./inbox-polling.ts";
+import { ActionBudgets, actionPolicyConfig, type ActionPolicyConfig } from "./action-policy.ts";
+import { ReleaseAuthorizations, releaseAuthorizationError } from "./sdlc-release-authorization.ts";
+import { parseReleaseGuardArgv, parseReleasePushUpdates } from "../cli/sdlc-release-guard.ts";
+import type { DocEvidence } from "./sdlc-release.ts";
 import { loadExternalAdapterDefinitions, readAdapterModuleDeclarations, type AdapterModuleDeclaration } from "../adapters/external-modules.ts";
 import { WsPeer, isWsPeer } from "../adapters/channel-peer.ts";
 import { ownerToolEffect, canonicalWriteUnknown } from "./no-writes.ts";
@@ -19,11 +24,13 @@ import { needs, type NeedsInput } from "../ui/needs.ts";
 import { loadPetConfig } from "../pet/config.ts";
 import { projectionConfig, TextProjections, type ProjectionConfig } from "./text-projection.ts";
 import { policyPaths, matchesPolicy } from "./path-policy.ts";
-import { buildReviewBrief } from "./review-brief.ts";
+import { CodeFacts, type CodeFactResult, type CodeSymbol } from "./code-facts.ts";
+import { buildReviewBrief, withCodeSymbols } from "./review-brief.ts";
 import { profileName, projectProfile, resolveProfile, mergeProfileOverrides, type ProfileName } from "./profiles.ts";
 import { catalogAssignments, loadRoleCatalog, selectedRoles, roleIdentity } from "./roles.ts";
 import { ActivityRing } from "./activity.ts";
-import { JcodeOptionMismatch, isJcodePeer, type JcodePeer } from "../adapters/jcode.ts";
+import { JcodeOptionMismatch, isJcodePeer, jcodeVersionAsync, type JcodePeer } from "../adapters/jcode.ts";
+import { VERSION_REFUSAL, describe, isCompatId } from "../adapters/compat.ts";
 import { jcodeMcpReady } from "../cli/jcode-mcp.ts";
 import { loadSdlc, readSpecEdit, sdlcGh } from "./sdlc.ts";
 import { claudePeer as defaultChannelPeer, claudeStateFile, ownTerminalRow, pathEvidence, transcriptPersisted } from "./claude-state.ts";
@@ -33,7 +40,7 @@ import { RecoveryDeferredHubError } from "./deferred-hub.ts";
 import { databaseBusySite, isDatabaseBusy, RecoveryDatabaseBusy } from "./recovery-error.ts";
 import { ADAPTERS, DEFAULT_REVIEW_POOL, REVIEW_POOL_KINDS, QUOTA_HANDOFF_PLATFORMS, NATIVE_CONFIG_BLOCKS, nativeConfigurationDefaults, mergeNativeConfiguration, retainNativeRouting, DAEMON_PORTS, definitionOf, createProjectAdapterCatalog } from "../adapters/registry.ts";
 import { isSupportedPeer as registrySupportedPeer, definitionOf as builtinDefinitionOf, KNOWN_PEERS as BASE_KNOWN_PEERS, SUPPORTED_PEERS as BASE_SUPPORTED_PEERS, STARTABLE_PEERS as BASE_STARTABLE_PEERS } from "../adapters/registry.ts";
-import { instanceDefinitionOf, effectiveInstanceRoles, instancePeerIds, validateInstances, type InstancesConfig } from "./instances.ts";
+import { checkJcodeInstanceHomes, instanceDefinitionOf, effectiveInstanceRoles, instancePeerIds, validateInstances, type InstancesConfig } from "./instances.ts";
 import { INSTANCE_CONFIG_FILES, readInstanceConfig, readInstanceConfigLayers, readInstanceRoleConfig } from "./instance-config.ts";
 import { instanceBudgetHooks, projectBudgetHeadroom } from "./instance-budget.ts";
 import { resolveInstanceExecutionCwd } from "./instance-execution.ts";
@@ -68,7 +75,7 @@ import { profile, proxyEnv, type SandboxNetwork } from "../local/sandbox.ts";
 import { DEFAULT_NETWORK_ALLOW, startEgressProxy, type EgressProxy } from "../local/proxy.ts";
 import { runTool, toolResultFailed, TOOL_SCHEMAS, type ToolApproval, type ApprovalObserver, type ToolContext } from "../local/tools.ts";
 import { isLocalPeer, type LocalPeer } from "../adapters/local-worker.ts";
-import { isReviewerPrintPeer, type ReviewerPrintPeer } from "../adapters/reviewer-print.ts";
+import { isReviewerPrintPeer, reviewerUnavailableReason, ReviewerUnavailableError, type ReviewerPrintPeer } from "../adapters/reviewer-print.ts";
 import { createReviewerMcpSession } from "../adapters/reviewer-mcp.ts";
 import { reviewerPoolConfig } from "./reviewer-pool-config.ts";
 import { reviewDiff } from "../adapters/claude-print.ts";
@@ -76,6 +83,7 @@ import { Capture, skipTools } from "../memory/capture.ts";
 import { DEFAULT_OMNIROUTE, OmniRoute, type OmniRouteConfig } from "../omniroute/client.ts";
 import { Briefs } from "../memory/brief.ts";
 import { Board, isClosedTaskState, taskProposalAt, taskHasStarted, CLASSES, type Task, type TaskClass } from "./board.ts";
+import { UsageRollup, USAGE_GROUPS, LIMITS_MAX, type UsageGroup } from "./usage-rollup.ts";
 import { Budget, readNativeQuota, DEFAULT_BUDGET, type BudgetConfig } from "./budget.ts";
 import { HUB } from "./envelope.ts";
 import { recallMemoryLines, trimToTokens } from "../memory/recall.ts";
@@ -98,7 +106,8 @@ import { projectSettings, checkSettingValue, ignoredLine, pendingUndo, pendingUn
 import { Bus } from "./bus.ts";
 import { attribute, deliveryTask, type TaskAttribution } from "./attribution.ts";
 import { DeliveryJournal } from "./delivery-journal.ts";
-import { startDashboard, type DashboardSession } from "./ui.ts";
+import { startDashboard, dashboardView, type DashboardSession } from "./ui.ts";
+import { codeGroup } from "./task-code-group.ts";
 import { DAEMON_FEATURES, PROTOCOL, stateDirFor } from "./control-client.ts";
 import { MAX_HOP, newEnvelope, parseMarker, replyParent, sanitize, USER, type Envelope, type PeerId, type Priority } from "./envelope.ts";
 import { BasePeer, DEFAULT_WATCHDOG_MS, type PeerAdapter } from "./peers.ts";
@@ -145,6 +154,7 @@ export interface HubConfig {
   jcode_cmd: string[];
   jcode_home: string;
   jcode_provider_profile: string;
+  action_policy?: ActionPolicyConfig;
   permission_modes: Record<string, PermissionMode>;
   protect_instruction_files: boolean;
   /** Loader-owned provenance of requested defaults, before machine-local filtering. */
@@ -218,6 +228,7 @@ const nativeDefaults = nativeConfigurationDefaults({ home: homedir(), env: proce
 export const DEFAULT_CONFIG: HubConfig = {
   watchdog_ms: DEFAULT_WATCHDOG_MS,
   ...nativeDefaults.commands,
+  action_policy: actionPolicyConfig(),
   permission_modes: {},
   protect_instruction_files: false,
   ...nativeDefaults.proxy,
@@ -263,7 +274,7 @@ const PEER_ID = /^[a-z][a-z0-9-]{0,31}$/;
 /** The shared project config, then the machine's own file, which overrides it block by block (issue #17). */
 const CONFIG_FILES = INSTANCE_CONFIG_FILES;
 export interface ConfigLayer { name: typeof CONFIG_FILES[number]; raw: Record<string, any> }
-const CONFIG_BLOCKS = ["memory", "roster", "roles", "catalog_roles", "pii", "data", "conductor", "budget", "context", "inference", "omniroute", ...NATIVE_CONFIG_BLOCKS, "approvals", "tasks", "task_sweep", "checks", "snapshots", "research", "bench", "limits", "review", "recovery", "capabilities", "mlx", "permission_modes", "peers", "terminal", "pet"];
+const CONFIG_BLOCKS = ["action_policy", "memory", "roster", "roles", "catalog_roles", "pii", "data", "conductor", "budget", "context", "inference", "omniroute", ...NATIVE_CONFIG_BLOCKS, "approvals", "tasks", "task_sweep", "checks", "snapshots", "research", "bench", "limits", "review", "recovery", "capabilities", "mlx", "permission_modes", "peers", "terminal", "pet"];
 
 /** Connection-time policy refresh reads role/feed fields only, never launches or machine-local configuration. */
 export function loadConductorPolicy(cwd: string, layers?: readonly ConfigLayer[]): { roles: Record<string, string[]>; conductor: HubConfig["conductor"]; planner?: string; notices?: string[] } {
@@ -280,9 +291,10 @@ export function loadConductorPolicy(cwd: string, layers?: readonly ConfigLayer[]
       if (!file.roles || typeof file.roles !== "object" || Array.isArray(file.roles)) throw new Error("roles must be an object of peer role lists");
       for (const [peer, assigned] of Object.entries(file.roles)) {
         conductorPeer({ [peer]: assigned });
-        const ceiling = definitionOf(peer)?.routing?.allowedRoles;
+        const definition = definitionOf(peer), ceiling = definition?.routing?.allowedRoles;
         const declared = assigned as string[];
-        roles[peer] = ceiling ? declared.filter(role => ceiling.includes(role)) : declared;
+        // #525 R1: planner needs a kind that can plan (projection.plannerEligible); such an entry is dropped with the ceiling notice, never thrown.
+        roles[peer] = (ceiling ? declared.filter(role => ceiling.includes(role)) : declared).filter(role => role !== "planner" || !definition || definition.projection?.plannerEligible === true);
         if (roles[peer]!.length !== declared.length) notices.push(`roles.${peer}: ignored roles outside the adapter ceiling`);
       }
     }
@@ -358,6 +370,7 @@ export function loadConfig(cwd: string, layers?: readonly ConfigLayer[], routing
     if (file.jcode_home !== undefined && (typeof file.jcode_home !== "string" || !isAbsolute(file.jcode_home))) throw new Error("jcode_home must be an absolute path");
     for (const key of ["jcode_home", "jcode_provider_profile"]) if (file[key] !== undefined && typeof file[key] !== "string") throw new Error(`${key} must be a string`);
     if (file.qwen_cmd !== undefined && (!Array.isArray(file.qwen_cmd) || !file.qwen_cmd.length || file.qwen_cmd.some((word: unknown) => typeof word !== "string" || !word))) throw new Error("qwen_cmd must be a nonempty executable argv");
+    actionPolicyConfig(file.action_policy);
     instructionProtection(file.protect_instruction_files);
     permissionDefaults(file.permission_modes, instances, adapterCatalog); // malformed declarations fail even when trust would drop them
     peerStartConfig(file.peers, instances, adapterCatalog);
@@ -421,6 +434,7 @@ export function loadConfig(cwd: string, layers?: readonly ConfigLayer[], routing
     ...(file.text_projection !== undefined ? { text_projection: projectionConfig(file.text_projection) } : {}),
     ...(file.pii !== undefined ? { pii: { paths: policyPaths(file.pii.paths, "pii.paths") } } : {}),
     ...(file.data !== undefined ? { data: { readonly: policyPaths(file.data.readonly, "data.readonly") } } : {}),
+    action_policy: actionPolicyConfig(file.action_policy),
     permission_modes: { ...instancePermissions, ...permissionDefaults(file.permission_modes, instances, adapterCatalog) },
     protect_instruction_files: instructionProtection(file.protect_instruction_files),
     permission_default_sources: appliedPermissionSources,
@@ -486,6 +500,8 @@ export interface DaemonOptions {
   checkoutBranch?: typeof mainCheckoutBranch;
   /** Host-only admission transport; never selected by project config or tools. */
   releaseHostAdmission?: (cwd: string) => Promise<ReleaseHostAdmission>;
+  /** Host-only evidence seam; never supplied by project config or control messages. */
+  releaseDocEvidence?: (root: string) => Promise<DocEvidence | undefined>;
   projectId?: string;
   instanceId?: string;
   cwd: string;
@@ -507,6 +523,10 @@ export interface DaemonOptions {
   orphanWatchMs?: number;
   /** Deterministic task-sweep time; the production default is Date.now. */
   taskSweepNow?: () => number;
+  /** Test seam: the period of the SDLC band evaluation, default five minutes. */
+  bandsEveryMs?: number;
+  /** Test seam: an extra hold on the SDLC band evaluation, like a storage error. */
+  bandsHeld?: () => boolean;
   /** How long a research record waits after an approval for the task's open turns to end (#247). Tests shrink this. */
   researchGraceMs?: number;
   /** Tests observe timer-driven sync without opening a remote; production uses the package sync. */
@@ -532,10 +552,29 @@ interface Client {
 type Sock = ServerWebSocket<Client>;
 
 
+/**
+ * #713: why `ahub queue resolve` was refused, from a closed list: the bus and the journal throw their own messages, and only these causes are named, never
+ * free text from an error (an id or a body would leak). An error that is none of them keeps the old generic sentence.
+ */
+const RESOLUTION_CAUSES: [RegExp, string][] = [
+  [/active delivery/i, "active delivery: it was handed to the peer and is not settled yet; wait for it, or resolve it once it is needs_review"],
+  [/peer busy/i, "peer busy: the peer is working, and only a queued delivery can be discarded meanwhile"],
+  [/stale delivery revision/i, "stale revision: the delivery changed since you read it; run ahub queue show again"],
+  [/unknown delivery|delivery not found/i, "unknown delivery: no such delivery id"],
+  [/already terminal|already resolved/i, "already resolved: the delivery is settled"],
+  [/already scheduled/i, "queued delivery is already scheduled: discard it, or wait for its turn"],
+  [/queue is full/i, "recipient queue is full: resolve or discard some of its queued work first"],
+  [/journal unavailable/i, "delivery journal unavailable: the hub cannot record a resolution right now"],
+];
+export function resolutionRefusal(error: unknown): string {
+  const text = error instanceof Error ? error.message : String(error);
+  return RESOLUTION_CAUSES.find(([pattern]) => pattern.test(text))?.[1] ?? "resolution refused: inspect ahub queue show for the delivery's state";
+}
+
 export async function startDaemon(opts: DaemonOptions) {
   const projectId = opts.projectId ?? randomUUID();
   const instanceId = opts.instanceId ?? randomUUID();
-  const startupCleanup: (() => void)[] = [];
+  const startupCleanup: (() => void | Promise<void>)[] = [];
   let ready = false;
   try {
   let startupLayers: ReturnType<typeof readInstanceConfigLayers>;
@@ -555,6 +594,7 @@ export async function startDaemon(opts: DaemonOptions) {
   const adapterCatalog = createProjectAdapterCatalog(loadedConfig.adapters, externalDefinitions);
   const configuredIds = adapterCatalog.definitions.filter(d => !builtinDefinitionOf(d.kind)).map(d => d.kind);
   const declarations = validateInstances(loadedConfig.instances, adapterCatalog);
+  checkJcodeInstanceHomes(declarations, loadedConfig.jcode_home); // #685: one native home per Jcode, at startup and never partially
   const extraIds = Object.keys(declarations);
   // #450 I3: channel extras (Claude) attach from the person's terminal; the hub never starts them and their hello is admitted.
   const channelExtras = extraIds.filter(id => adapterCatalog.definitionOf(id, declarations)?.attach?.externalHello === true);
@@ -914,6 +954,26 @@ export async function startDaemon(opts: DaemonOptions) {
     if (refused) log(`limits: ${env.from}: ${refused}`);
     return refused;
   };
+  /**
+   * #685: the provider, model and profile names an extra Jcode instance was declared with, for status, doctor and the dashboard,
+   * exactly as the person wrote them (they authenticate inside Jcode). Never a URL, a token or the native home path.
+   */
+  const jcodeModelSource = (id: string): { modelSource?: string } => {
+    const instance = declarations[id];
+    if (!instance || definitionOf(id)?.instances?.nativeHome !== true) return {};
+    return { modelSource: [instance.provider, instance.model, instance.provider_profile && `profile ${instance.provider_profile}`].filter(Boolean).join(" ") || "native default" };
+  };
+  /**
+   * #685 scope update 2: the read-only start preflight for an extra Jcode instance. The declared home must exist as a directory the
+   * person owns (the hub never creates it, and reads or writes nothing inside it). The reason names the instance, never the path.
+   */
+  const jcodeHomeRefusal = (id: string, home: string): string | undefined => {
+    let info: ReturnType<typeof statSync> | undefined;
+    try { info = statSync(home); } catch { /* reported below */ }
+    if (!info?.isDirectory()) return `${id}: its jcode_home is not an existing directory; the person creates it and signs in to Jcode against it first`;
+    if (typeof process.getuid === "function" && info.uid !== process.getuid()) return `${id}: its jcode_home is not owned by the person running the hub`;
+    return undefined;
+  };
   /** This hub run's start: offline owners count from it (issue #6), split predictions read tasks since (issue #109). */
   const hubStartedAt = Date.now();
   // The bus exists before `Tasks`, which knows whether a queued notice still matters (issue #106).
@@ -1119,6 +1179,8 @@ export async function startDaemon(opts: DaemonOptions) {
   let modelRelay: ModelRelay | undefined;
   const piReceiptLedgers = new Map<string, PiToolReceipts>();
   const modelRelays = new Map<string, ModelRelay>();
+  /** #368: the owned Jcode launch of each Jcode peer, from creation (its MCP child connects while `start()` runs, before the bus has the peer). */
+  const jcodeLaunches = new Map<string, JcodePeer>();
   const globalModelRelay = (relay: ModelRelay) => { modelRelay = relay; };
   const nativeStateDir = (peer: string) => declarations[peer] ? join(opts.stateDir, "instances", peer) : opts.stateDir;
   const instanceAppPorts = new Map<string, number>();
@@ -1158,8 +1220,12 @@ export async function startDaemon(opts: DaemonOptions) {
     event({ type: "conduct", peer: action.actor, action: action.action, ...(action.task === undefined ? {} : { task: action.task }), ...(action.peer ? { target: action.peer } : {}) });
     try { notify(`conductor ${action.actor}: ${action.action}${action.task === undefined ? "" : ` #${action.task}`}${action.peer ? ` ${action.peer}` : ""}`); } catch { /* never throw after a task/hold write */ }
   };
+  const inboxPolling = new InboxPolling();
   const board = new Board(join(opts.stateDir, "hub.db"));
+  const codeFacts = new CodeFacts();
+  const reviewSymbols = new Map<string, CodeFactResult<CodeSymbol[]>>();
   startupCleanup.push(() => board.close());
+  startupCleanup.push(() => codeFacts.close());
   const supervision = new SupervisionFeed({
     conductor: () => conductorPeer(config.roles) ?? undefined,
     scope: () => config.conductor?.feed ?? "own",
@@ -1358,9 +1424,19 @@ export async function startDaemon(opts: DaemonOptions) {
     projectedReview: task => reviewProjection(task),
     ownerWrites: (task, since) => ownerWriteEvidence(task, since),
     ownerAccepted: task => captureOwnerWriteStart(task),
+    prepareReviewBrief: async task => {
+      if (tasks.isPii(task) || !task.refs.commit) return;
+      const root = executionRoot(task.owner ?? "");
+      const brief = buildReviewBrief(root, task.refs.commit, { privatePath: path => isDenied(path, config.local.deny) || matchesPolicy(root, path, config.pii?.paths ?? [], true), nameable: tasks.nameable });
+      if ("unavailable" in brief) return;
+      const key = JSON.stringify([root, brief.head, brief.mergeBase]);
+      reviewSymbols.set(key, await codeFacts.changedSymbols(root, brief.mergeBase, brief.head));
+      if (reviewSymbols.size > 64) reviewSymbols.delete(reviewSymbols.keys().next().value!);
+    },
     reviewBrief: task => {
       const root = executionRoot(task.owner ?? "");
-      return buildReviewBrief(root, task.refs.commit, { privatePath: path => isDenied(path, config.local.deny) || matchesPolicy(root, path, config.pii?.paths ?? [], true), nameable: tasks.nameable });
+      const brief = buildReviewBrief(root, task.refs.commit, { privatePath: path => isDenied(path, config.local.deny) || matchesPolicy(root, path, config.pii?.paths ?? [], true), nameable: tasks.nameable });
+      return "unavailable" in brief ? brief : withCodeSymbols(brief, reviewSymbols.get(JSON.stringify([root, brief.head, brief.mergeBase])) ?? { state: "unknown" }, task.plan?.symbols, tasks.publicMetadataText);
     },
     sdlc: { config: () => lifecycleConfig, gh: (args, timeout, _cwd, bound) => sdlcGh(args, timeout, opts.cwd, bound) },
     board,
@@ -1657,6 +1733,10 @@ export async function startDaemon(opts: DaemonOptions) {
   /** What quiescence was judged on, for the log when an integration waits on it. */
   const stopEvidence = (peer: PeerId) => `${peer}: turn end ${turnEnded.has(peer) ? new Date(turnEnded.get(peer)!).toISOString() : "none"}, last tool call ${activeAt.has(peer) ? new Date(activeAt.get(peer)!).toISOString() : "none"}, ${bus.peers.get(peer)?.state ?? "offline"}`;
   board.onChange = (t, h) => {
+    if (!isClosedTaskState(t.state) && t.state !== "backlog") {
+      if (t.owner) inboxPolling.reset(t.owner);
+      if (t.reviewer) inboxPolling.reset(t.reviewer);
+    }
     turnFreeNow = undefined;
     scopes = new Map();
     progress.prune();
@@ -1757,6 +1837,8 @@ export async function startDaemon(opts: DaemonOptions) {
     // Somebody other than the paused peer has to be there, or the handoff would only leave its tasks without an owner.
     canHandOff: (peer) => [...bus.peers.keys()].some((id) => accountOf(id) !== accountOf(peer) && ["idle", "busy"].includes(bus.stateOf(id))),
     // A reading that arrived through a file carries the file's time; a stale one must not look fresh in the export.
+    // #683 U1: pauses, resumes and derived resets go to the event log, ids and numbers only.
+    ledger: entry => event(entry),
     reading: (peer, windows, hard, at) => event({ type: "quota", peer, windows: windows.map((w) => ({ id: w.id, used: w.used, ...(w.resetsAt ? { resetsAt: w.resetsAt } : {}) })), hard, ...(Math.abs(Date.now() - at) > 1000 ? { measuredAt: new Date(at).toISOString() } : {}) }),
     handoff: (peer, context, urgentOnly) => tasks.reassignForPause(peer, context, urgentOnly),
     resumed: (record) => {
@@ -1783,8 +1865,17 @@ export async function startDaemon(opts: DaemonOptions) {
     notify: (line) => { notify(line); feedBudgetPauses(); },
   }, accountMembers, accountOf));
   budget.setRecoveryHold(recoveryActive());
+  // ponytail: a third full read of events.jsonl at startup (after nativeStopsSeen and claudeNativeUsageSeen). Measured at about 70 ms on the real
+  // 46 MB, 238k-line log, so it is not folded into one pass across startup. Ceiling: the log is never rotated, so the cost grows with it; when a
+  // read passes a few hundred ms, make one `readEvents` pass feed all three sets (or keep the resets in hub.db, the #683 U2 roll-up).
+  budget.seedResets(readEvents(join(opts.stateDir, "events.jsonl")).flatMap(e => e.type === "quota_reset" ? [{ peer: e.peer, window: e.window, ...(e.resetsAt !== undefined ? { resetsAt: e.resetsAt } : {}) }] : []));
   const kimiTokens: { at: number; n: number }[] = [];
   startupCleanup.push(() => budget.close());
+  // #683 U2: events.jsonl folded into hub.db, a bounded pass at a time, so `usage` never rescans the log.
+  const usageRollup = new UsageRollup(join(opts.stateDir, "hub.db"), join(opts.stateDir, "events.jsonl"));
+  startupCleanup.push(() => usageRollup.close());
+  const pollUsageRollup = () => { try { usageRollup.poll(); } catch (error) { log(`usage roll-up pass failed: ${(error as Error).message.slice(0, 120)}`); } };
+  pollUsageRollup();
   // Turns and their tokens for telemetry (issue #40). Turn ids carry the hub run, so they stay unique across restarts.
   const runId = Date.now().toString(36);
   let turnSeq = 0;
@@ -1944,6 +2035,7 @@ export async function startDaemon(opts: DaemonOptions) {
   }
   const delta = tokenDeltas();
   /** Tokens a peer used, as increments: Kimi reports a session total (turned into increments below), Codex increments. */
+  let codexUsageSeq = 0; // per hub run: with the run id and peer it names one usage record
   const addTokens = (peer: PeerId, n: number): number => {
     const supervisionTurn = supervisionTurns.get(peer);
     if (supervisionTurn && Number.isFinite(n) && n >= 0) supervisionTurn.tokens = (supervisionTurn.tokens ?? 0) + n;
@@ -1965,6 +2057,8 @@ export async function startDaemon(opts: DaemonOptions) {
   };
   // Claude's numbers arrive through the status line tee `ahub claude` installs (src/cli/statusline-tee.ts).
   let claudeUsageSeen = 0;
+  let bandsRevision = ""; // #481 S7: the board revision and band configuration the last band evaluation that ran saw
+  let bandEvaluations = 0; // evaluations that ran (not skipped for an unchanged board); read by tests through the daemon
   const claudeContextSeen = new Map<string, string>();
   const contextTailSeen = new Map<PeerId, string>();
   const retainedCliAudits = new Set<string>();
@@ -2022,6 +2116,22 @@ export async function startDaemon(opts: DaemonOptions) {
       } catch { /* absent or unreadable native telemetry is unknown */ }
     }, 1000),
     setInterval(() => budget.tick(), 30_000),
+    setInterval(pollUsageRollup, 10_000),
+    // #481 S7: band tiers are evaluated every five minutes, and only when the board changed since the last evaluation (the status
+    // revision moves on every task write), so an idle board costs one integer read. Held while stopping or recovering, like the task sweep.
+    // ponytail: one evaluation reads every task with its history (a few ms per hundred tasks); bound it by a history window if a board passes several thousand tasks.
+    setInterval(() => {
+      if (stopping || recoveryActive()) return;
+      try {
+        const state = tasks.bandsState();
+        if (!state.ready || opts.bandsHeld?.()) return; // held, mode off or no bands: nothing is consumed, so the breach is still there when it clears
+        const revision = `${board.statusRevision()}:${state.signature}`;
+        if (revision === bandsRevision) return;
+        bandEvaluations++;
+        tasks.proposeFromBands();
+        bandsRevision = `${board.statusRevision()}:${state.signature}`; // after the write: the cards this pass made are not a reason to run again
+      } catch (error) { log(`sdlc band evaluation failed: ${sanitize((error as Error).message).slice(0, 160)}`); }
+    }, opts.bandsEveryMs ?? 300_000),
     setInterval(() => {
       if (!ready || !memoryBinding) return;
       const before = memoryProblem;
@@ -2147,7 +2257,7 @@ export async function startDaemon(opts: DaemonOptions) {
     }
     // Inside a PII turn the worker's words may carry the PII whatever they are attached to: a note would go to
     // claude-mem (a cloud observer) and a new task could be routed to a cloud peer without matching any pattern.
-    if (piiTurn && (MEMORY_READ_TOOLS.has(op) || op === "hub_memory_correct" || op === "hub_remember" || op === "hub_task_propose" || op === "hub_sdlc_record" || op === "hub_plan_review" || op === "hub_sdlc_costs" || op.startsWith("hub_release_") || op === "hub_backlog_return_untouched" || op === "hub_backlog_plan" || op === "hub_backlog_undo" || op === "hub_backlog_pull" || op === "hub_backlog_split" || op === "release_new")) throw new PreEffectToolRefusal(`${op} is not available while working on a PII task: its text must not leave this machine`);
+    if (piiTurn && (MEMORY_READ_TOOLS.has(op) || op === "hub_memory_correct" || op === "hub_remember" || op === "hub_task_propose" || op === "hub_sdlc_record" || op === "hub_plan_review" || op === "hub_sdlc_costs" || op === "hub_sdlc_metrics" || op.startsWith("hub_release_") || op === "hub_backlog_return_untouched" || op === "hub_backlog_plan" || op === "hub_backlog_undo" || op === "hub_backlog_pull" || op === "hub_backlog_split" || op === "release_new")) throw new PreEffectToolRefusal(`${op} is not available while working on a PII task: its text must not leave this machine`);
     // The same words attached to an ordinary task would reach its reviewer, its owner, overlapping owners (a plan, the
     // completed-change notice) and claude-mem. A turn that holds a PII task acts on ordinary tasks in a turn of its own.
     if (piiTurn && (op === "hub_task_done" || op === "hub_review" || (op === "hub_task_accept" && (a.plan != null || a.refs != null)))) {
@@ -2277,6 +2387,8 @@ export async function startDaemon(opts: DaemonOptions) {
         return JSON.stringify(await tasks.groomingDigest(by));
       case "hub_sdlc_costs":
         return JSON.stringify(await tasks.costReport(by, a.repo));
+      case "hub_sdlc_metrics":
+        return JSON.stringify(tasks.sdlcMetrics(by, a.since));
       case "hub_plan_review": {
         const { id, ...review } = a;
         return JSON.stringify(tasks.publicView(await tasks.recordPlanReview(by, id, review)));
@@ -2297,10 +2409,11 @@ export async function startDaemon(opts: DaemonOptions) {
         return JSON.stringify(tasks.publicView(await tasks.undoPlanning(by, a.id, a.revision)));
       case "hub_task_propose": {
         const t = await tasks.propose(by, a);
-        if (t.state === "backlog") return line(t);
+        const repoHint = tasks.refsRepoHint(t); // #723: advice only; never part of the write
+        if (t.state === "backlog") return [line(t), repoHint].filter(Boolean).join("\n");
         const overlap = tasks.overlaps(t, t.owner === by);
         if (t.owner === by && tasks.silentFor(t.id) && factsOn()) factsFor(by).sawPlans(by, tasks.overlapTasks(t)); // as for an accept
-        return [line(t), tasks.namedOwnerNote(t, a.owner as PeerId | undefined, by), overlap, tasks.claimRoleGuidance(t, by), t.owner === by ? tasks.planGuardText(t) : ""].filter(Boolean).join("\n");
+        return [line(t), tasks.namedOwnerNote(t, a.owner as PeerId | undefined, by), overlap, tasks.claimRoleGuidance(t, by), t.owner === by ? tasks.planGuardText(t) : "", repoHint].filter(Boolean).join("\n");
       }
       case "hub_task_accept": {
         // S1 spec acceptance and S9 plan review are checked against one task snapshot before acceptance.
@@ -2412,7 +2525,10 @@ export async function startDaemon(opts: DaemonOptions) {
       }
       case "task_show": {
         const task = board.get(Number(a.id));
-        return JSON.stringify(task ? { ...task, flowRevision: task.history.length, reviews: board.reviews({ task: task.id }) } : `no task #${a.id}`, null, 2);
+        if (!task) return JSON.stringify(`no task #${a.id}`);
+        const { codeSymbols: _storedCodeSymbols, ...detail } = task;
+        const codeSymbols = tasks.publicView(task).codeSymbols;
+        return JSON.stringify({ ...detail, ...(codeSymbols ? { codeSymbols } : {}), symbolOverlaps: tasks.symbolOverlaps(task), flowRevision: task.history.length, reviews: board.reviews({ task: task.id }) }, null, 2);
       }
       case "task_assign":
       case "task_assign_checked": {
@@ -2496,6 +2612,7 @@ export async function startDaemon(opts: DaemonOptions) {
       else delete defaultSources[peer];
     }
   };
+  const actionBudgets = new ActionBudgets(() => config.action_policy, contextSession);
   const permissionMode = (peer: string): PermissionMode => permissionModes.get(peer) ?? "ask";
   const permissionModeSources = new Map(Object.entries(defaultSources).map(([peer, value]) => [peer, value.source]));
   const unattendedPeers = new Set<string>();
@@ -2504,6 +2621,12 @@ export async function startDaemon(opts: DaemonOptions) {
   const claudePermissionGenerations = new Map<string, string>();
   const permissions = new Map<string, { push: string; peer: string; tool?: string; createdAt: number; expiresAt: number; done: (optionId: string | undefined, surface?: "console" | "dashboard" | "terminal", reason?: "expired" | "cancelled") => boolean }>();
   let stopping = false;
+  const releaseAuthorizations = new ReleaseAuthorizations(opts.cwd, {
+    docs: opts.releaseDocEvidence,
+    gh: (args, timeout) => sdlcGh(args, timeout, opts.cwd),
+    current: () => !stopping && !recoveryActive() && !bus.isRecoveryHeld,
+    record: receipt => event({ type: "release_authorization", by: "user", authorization: receipt.id, commit: receipt.commit, version: receipt.version, docsDigest: receipt.docs.digest, documents: receipt.docs.documents }),
+  });
   const terminalReads = terminalOwnerReads();
   const terminalLaunches = new TerminalLaunches({
     owner: row => {
@@ -2788,10 +2911,11 @@ export async function startDaemon(opts: DaemonOptions) {
     ...(dashboard ? { uiOrigin: dashboard.origin } : {}),
     codexProxyPort: opts.codexProxyPort,
     peers: Object.fromEntries(
-      peerIds.map((id) => { const p = bus.peers.get(id); const summary = bus.queueSummary(id); const context = contexts.view(id, contextSession(id), !!p && ["idle", "busy", "paused"].includes(bus.stateOf(id))); return [id, { state: bus.stateOf(id), ...(!membershipAllowed(id) ? { rostered: false, rosterNote: "off roster" } : {}), ...permissionStatus(id, p), ...(isCodexPeer(p) && p.statusNotice ? { statusNotice: p.statusNotice } : {}), ...(context.source !== null || context.measuredAt !== null ? { context } : {}), queued: bus.queued(id), ...(p ? {} : { attached: false }), ...(summary.needsReview ? { needsReview: summary.needsReview } : {}), ...(summary.liveAccepted ? { liveAccepted: summary.liveAccepted, settlementNote: "awaiting adapter completion (Claude: correlated reply or hub_delivery_done); task state is independent" } : {}), ...queueHoldStatus(id, summary.heldBy), ...(summary.oldestQueuedAt !== undefined ? { oldestQueuedAt: summary.oldestQueuedAt } : {}), ...(bus.queuedImportant(id) ? { queuedImportant: bus.queuedImportant(id) } : {}), ...importantWaitingStatus(id, p), ...pausedNote(id), ...(isLocalPeer(p) && p.lastServedBy ? { servedBy: p.lastServedBy } : {}), ...(isWsPeer(p) && p.claiming ? { claiming: true } : {}), ...(isWsPeer(p) && p.pullOnly ? { pullOnly: true, toolsOnly: definitionOf(id)?.attach?.pullOnlyNotice ?? "tools-only: messages wait for hub_inbox; for pushes restart Claude with ahub claude", lastInboxAt: p.lastInboxAt ?? null } : {}), ...(isPiPeer(p) ? { requestedModel: p.getRequestedModel(), backends: modelRelays.get(id)?.status().backends ?? [] } : {}) }]; }),
+      peerIds.map((id) => { const p = bus.peers.get(id); const summary = bus.queueSummary(id); const context = contexts.view(id, contextSession(id), !!p && ["idle", "busy", "paused"].includes(bus.stateOf(id))); return [id, { state: bus.stateOf(id), ...(!membershipAllowed(id) ? { rostered: false, rosterNote: "off roster" } : {}), ...permissionStatus(id, p), ...(isCodexPeer(p) && p.statusNotice ? { statusNotice: p.statusNotice } : {}), ...(context.source !== null || context.measuredAt !== null ? { context } : {}), queued: bus.queued(id), ...(p ? {} : { attached: false }), ...(summary.needsReview ? { needsReview: summary.needsReview } : {}), ...(summary.liveAccepted ? { liveAccepted: summary.liveAccepted, settlementNote: "awaiting adapter completion (Claude: correlated reply or hub_delivery_done); task state is independent" } : {}), ...queueHoldStatus(id, summary.heldBy), ...(summary.oldestQueuedAt !== undefined ? { oldestQueuedAt: summary.oldestQueuedAt } : {}), ...(bus.queuedImportant(id) ? { queuedImportant: bus.queuedImportant(id) } : {}), ...importantWaitingStatus(id, p), ...pausedNote(id), ...(reviewerUnavailable.has(id) ? { reviewerUnavailable: reviewerUnavailable.get(id) } : {}), ...jcodeModelSource(id), ...(isLocalPeer(p) && p.lastServedBy ? { servedBy: p.lastServedBy } : {}), ...(isWsPeer(p) && p.claiming ? { claiming: true } : {}), ...(isWsPeer(p) && p.pullOnly ? { pullOnly: true, toolsOnly: definitionOf(id)?.attach?.pullOnlyNotice ?? "tools-only: messages wait for hub_inbox; for pushes restart Claude with ahub claude", lastInboxAt: p.lastInboxAt ?? null } : {}), ...(isPiPeer(p) ? { requestedModel: p.getRequestedModel(), backends: modelRelays.get(id)?.status().backends ?? [] } : {}) }]; }),
     ),
     taskWip: Object.fromEntries(peerIds.map(id => [id, { wip: tasks.wip(id), wipLimit: tasks.wipLimit(id) }])),
     boardReadCapabilities: { releaseFilter: true, columnMetadata: true },
+    actionPolicyInfo: Object.fromEntries(peerIds.map(id => [id, actionBudgets.status(id, false)])),
     roleInfo: Object.fromEntries(peerIds.map(id => [id, { flowRoles: config.roles[id] ?? [], catalogRoles: roleState(id), ...(config.roles[id]?.includes("planner") ? { planner: plannerSource } : {}) }])),
     planner: { peers: plannerPeers(), source: plannerSource },
     ...(pendingPermissionDefaults.size ? { permissionDefaults: [...pendingPermissionDefaults].map(([peer, source]) => ({ peer, mode: "never-ask", source })) } : {}),
@@ -3706,12 +3830,24 @@ export async function startDaemon(opts: DaemonOptions) {
     }
     if (adapter?.start.daemonPort === "owned-acp") {
       if (!jcodeMcpReady(opts.cwd, opts.stateDir, SERVER_JS)) return { ok: false, error: "Jcode project MCP entry missing or stale; the person runs ahub jcode to configure it" };
-      const jcode: JcodePeer = adapter!.start.create!({ instance: peer, projectRoot: opts.cwd, stateDir: opts.stateDir, kindConfig: config, permission: permissionMode(peer), mcpServers: [], daemon: DAEMON_PORTS["owned-acp"]({ command: config.jcode_cmd, home: config.jcode_home, providerProfile: (args.providerProfile ?? config.jcode_provider_profile) || undefined,
-        ...(args.model ? { launchModel: args.model } : {}), ...(args.sessionId ? { resumeSessionId: args.sessionId } : {}), cwd: executionCwd, watchdogMs: config.watchdog_ms,
+      // #691: name a version refusal before the owned daemon starts; the ACP identity check stays the binding one.
+      const jcodeVerdict = await jcodeVersionAsync(config.jcode_cmd, executionCwd);
+      if (!jcodeVerdict.ok) return { ok: false, error: jcodeVerdict.reason };
+      if (jcodeVerdict.note) log(jcodeVerdict.note);
+      // #685: an extra instance runs its own native home and model fields; the base peer keeps jcode_home and the global provider profile.
+      const instance = declarations[peer];
+      // #685 scope update 2: the person authenticates inside Jcode against that home. The hub passes -p, -m and --provider-profile as
+      // written and reads or writes no credential; the only preflight is that the declared home is a directory the person owns.
+      if (instance?.jcode_home) { const refusal = jcodeHomeRefusal(peer, instance.jcode_home); if (refusal) return { ok: false, error: refusal }; }
+      const jcode: JcodePeer = adapter!.start.create!({ instance: peer, projectRoot: opts.cwd, stateDir: opts.stateDir, kindConfig: config, permission: permissionMode(peer), mcpServers: [], daemon: DAEMON_PORTS["owned-acp"]({ peer, command: config.jcode_cmd, home: instance?.jcode_home ?? config.jcode_home,
+        providerProfile: (args.providerProfile ?? instance?.provider_profile ?? config.jcode_provider_profile) || undefined,
+        ...(instance?.provider ? { provider: instance.provider } : {}),
+        ...(args.model ?? instance?.model ? { launchModel: (args.model ?? instance?.model)! } : {}), ...(args.sessionId ? { resumeSessionId: args.sessionId } : {}), cwd: executionCwd, watchdogMs: config.watchdog_ms,
         preamble: sessionRoleContract(peer), log: () => log("Jcode native diagnostic: details withheld") }) }) as JcodePeer;
+      jcodeLaunches.set(peer, jcode);
       recoveryTaskPreface(peer); await ensurePreface(peer);
       try { await jcode.start(); await reconcileNativeStart(peer, jcode); }
-      catch { await jcode.stop().catch(() => {}); throw new Error("Jcode startup not verified; check native version, provider profile, MCP store and owned daemon (details withheld)"); }
+      catch { await jcode.stop().catch(() => {}); if (jcodeLaunches.get(peer) === jcode) jcodeLaunches.delete(peer); throw new Error("Jcode startup not verified; check native version, provider profile, MCP store and owned daemon (details withheld)"); }
       return { ok: true, policy: "unmanaged" };
     }
     if (adapter?.start.acpCommand) {
@@ -3796,7 +3932,7 @@ export async function startDaemon(opts: DaemonOptions) {
         if (configuredIds.includes(adapter.kind) && owner.pendingOwnedProcess) bus.add(owner); // Retain the failed owner for explicit stop retry; never replace its live child.
         if (configuredIds.includes(adapter.kind)) throw new Error(`${peer}: ACP startup identity, session, permission or owned-group verification failed (details withheld)`);
         if (error instanceof QwenIdentityError) throw error;
-        throw new Error("Qwen could not reach its provider or complete its startup handshake; verify the provider connection and Qwen Code 0.25.0 (details withheld)");
+        throw new Error(`${adapter.displayName} could not reach its provider or complete its startup handshake; verify the provider connection and native CLI${isCompatId(adapter.kind) ? ` (${describe(adapter.kind)})` : ""}; see ahub agents (details withheld)`);
       }
       return { ok: true };
     }
@@ -3807,6 +3943,12 @@ export async function startDaemon(opts: DaemonOptions) {
         admitAttach: () => membershipAllowed(peer),
         permissionMode: permissionMode(peer),
         onTokens: (added) => void addTokens(peer, added),
+        // #683 U1: the same update split into Codex's own kinds, next to the unchanged `tokens` event. One record per update:
+        // the id names the hub run, peer and a per-run sequence, so it is unique across restarts. It never carries the native thread: usage telemetry has no session id (docs/events.md).
+        onTokenBreakdown: delta => {
+          event({ type: "usage", peer, source: "codex_appserver", id: `codex:${runId}:${peer}:${++codexUsageSeq}`, inputTokens: delta.input, cacheReadTokens: delta.cachedInput,
+            outputTokens: delta.output, reasoningTokens: delta.reasoning, totalTokens: delta.total, ...taskAttribution(peer) });
+        },
         contextReader: adapter.budget?.context,
         onContext: adapter.budget?.context ? (reading) => contexts.report(peer, reading, contextSession(peer)) : undefined,
         // #215: before the thread's first turn_start, so the planner can tell which turns belong to which thread.
@@ -4146,7 +4288,12 @@ export async function startDaemon(opts: DaemonOptions) {
         onUnavailable: (failure, current) => {
           const attached = () => current() && bus.peers.get(peer) === reviewer;
           if (!attached()) return;
-          if (failure.cause === "start_failed") reviewerUnavailable.set(peer, "reviewer isolation unavailable; restart after checking the verified CLI and isolation requirements");
+          if (failure.cause === "start_failed") {
+            // #722: the class (a closed list) is the only detail; never a path, native text or token.
+            const reason = reviewerUnavailableReason(failure.causeClass ?? "unknown", failure.causeDetail);
+            log(`reviewer ${peer} unavailable for task #${failure.task}: ${sanitize(reason).slice(0, 300)}`);
+            reviewerUnavailable.set(peer, sanitize(reason).slice(0, 1000));
+          }
           return tasks.retryReviewer(failure.task, peer, failure, attached).then(() => undefined);
         },
         log,
@@ -4154,8 +4301,10 @@ export async function startDaemon(opts: DaemonOptions) {
       try { await reviewer.start(); }
       catch (error) {
         await reviewer.stop().catch(() => {});
-        const reason = backend.nativePolicy && error instanceof Error ? sanitize(error.message).slice(0, 1000)
-          : "reviewer isolation unavailable; inspect the verified CLI version and isolation requirements";
+        // #691: a version refusal names only versions and the trust command, so it is shown for every backend.
+        const reason = error instanceof Error && (backend.nativePolicy || error.message.startsWith(VERSION_REFUSAL)) ? sanitize(error.message).slice(0, 1000)
+          : reviewerUnavailableReason(error instanceof ReviewerUnavailableError ? error.causeClass : "unknown", error instanceof ReviewerUnavailableError ? error.detail : undefined);
+        log(`start ${peer} failed [cause: ${error instanceof ReviewerUnavailableError ? error.causeClass : "unknown"}]`);
         reviewerUnavailable.set(peer, reason);
         return { ok: false, error: reason };
       }
@@ -4315,7 +4464,7 @@ export async function startDaemon(opts: DaemonOptions) {
       const text = (v: unknown, max = 200) => typeof v === "string" && v.trim() && v.length <= max ? v.trim() : undefined;
       const tier = q.tier === "short" || q.tier === "long" || q.tier === "goals" ? q.tier : "long";
       const kind = typeof q.kind === "string" && (["decision", "finding", "contract", "fail"] as string[]).includes(q.kind) ? q.kind as MemoryView["kind"] : undefined;
-      const peer = text(q.peer, 32), machine = text(q.machine, 32), search = text(q.q), node = text(q.node), since = [text(q.since, 40)].find((v) => v !== undefined && !Number.isNaN(Date.parse(v))); // an unreadable since filters nothing
+      const peer = text(q.peer, 32), machine = text(q.machine, 32), search = text(q.q), node = text(q.node, typeof q.node === "string" && q.node.startsWith("symbol:") ? 512 : 200), since = [text(q.since, 40)].find((v) => v !== undefined && !Number.isNaN(Date.parse(v))); // an unreadable since filters nothing
       const hops = q.hops === 2 ? 2 : 1;
       const all = memoryStore.list({ project: memoryProject, limit: Number.MAX_SAFE_INTEGER });
       const goals = memoryStore.goals(memoryProject);
@@ -4353,6 +4502,43 @@ export async function startDaemon(opts: DaemonOptions) {
     const attentionStatus = status(false, true);
     let pet; try { const config = loadPetConfig(opts.cwd); pet = { enabled: config.enabled, character: config.character ?? "stai", blink: config.blink }; } catch { pet = { enabled: false }; }
     const peerView = Object.fromEntries(Object.entries(attentionStatus.peers).map(([id, peer]) => [id, { ...peer, ...turnView(id as PeerId) }])), boardTasks = board.list();
+    const usageView = (open: boolean) => {
+      // #683 U4: the roll-up runs only while the Agents view that shows it is open, never on a hidden view's 1 s poll.
+      if (!open) return undefined;
+      try {
+        const caught = usageRollup.catchUp(100);
+        const status = budget.status();
+        const live = new Set(Object.entries(status).filter(([, v]) => v.paused).map(([peer]) => peer));
+        const limits = usageRollup.limits(undefined, { limit: 100, live });
+        const total = usageRollup.total();
+        const daily = usageRollup.daily(14);
+        const taskUsage = usageRollup.query({ by: "task" });
+        return {
+          // `behind`: the roll-up has not folded the whole log, so every figure below is a lower bound, never the whole (unknown is not 0).
+          behind: !caught,
+          daily,
+          limits,
+          total,
+          tasks: taskUsage.rows.map(r => ({
+            id: r.key === "unattributed" ? 0 : Number(r.key.replace(/^#/, "")),
+            pii: r.pii === true,
+            records: r.records,
+            input: r.input,
+            output: r.output,
+            cacheRead: r.cacheRead,
+            cacheWrite: r.cacheWrite,
+            reasoning: r.reasoning,
+            total: r.total,
+            counted: r.counted,
+            totalWithoutCache: r.totalWithoutCache,
+          })),
+        };
+      } catch (e) {
+        log(`dashboard usage view failed: ${(e as Error).message}`);
+        // The page keeps the last figures for `undefined` (a hidden view), so a failed read says so explicitly instead.
+        return { unavailable: true };
+      }
+    };
     return {
       ok: true,
       projectId,
@@ -4372,7 +4558,7 @@ export async function startDaemon(opts: DaemonOptions) {
       tasks: boardTasks.map((task) => {
         const view = tasks.publicView(task);
         // Refs and history can themselves quote private text. The dashboard needs neither.
-        return { id: task.id, title: view.title, detail: view.detail, class: task.class, ...(task.profile ? { profile: task.profile, profileClass: task.profileClass } : {}), ...(task.role ? { role: task.role } : {}), state: task.state, owner: task.owner, reviewer: task.reviewer, deps: view.deps ?? [], ...(task.reserved ? { reserved: task.reserved } : {}), planningRevision: task.planningRevision ?? 0, rank: task.rank ?? null, priority: task.priority ?? null, release: task.release ?? null, plannedStart: task.plannedStart ?? null, due: task.due ?? null, pinned: task.pinned === true, actualDates: view.actualDates, ...(view.cancelled ? { cancelled: view.cancelled } : {}), ...(view.external ? { external: view.external } : {}), started: taskHasStarted(task), urgent: task.signals.includes("urgent"), updated: task.updated, reworkRound: task.history.filter(entry => entry.event === "changes_requested").length, checking: tasks.isChecking(task.id), ...(view.lifecycle ? { lifecycle: view.lifecycle } : {}) };
+        return { id: task.id, title: view.title, detail: view.detail, class: task.class, ...(task.profile ? { profile: task.profile, profileClass: task.profileClass } : {}), ...(task.role ? { role: task.role } : {}), state: task.state, owner: task.owner, reviewer: task.reviewer, deps: view.deps ?? [], ...(task.reserved ? { reserved: task.reserved } : {}), planningRevision: task.planningRevision ?? 0, rank: task.rank ?? null, priority: task.priority ?? null, release: task.release ?? null, plannedStart: task.plannedStart ?? null, due: task.due ?? null, pinned: task.pinned === true, actualDates: view.actualDates, ...(view.codeSymbols ? { codeSymbols: view.codeSymbols } : {}), ...(() => { const group = codeGroup(task, view.codeSymbols, task.plan?.symbols, tasks.publicMetadataText, tasks.isPii(task)); return group ? { codeGroup: group } : {}; })(), ...(view.cancelled ? { cancelled: view.cancelled } : {}), ...(view.external ? { external: view.external } : {}), started: taskHasStarted(task), urgent: task.signals.includes("urgent"), updated: task.updated, reworkRound: task.history.filter(entry => entry.event === "changes_requested").length, checking: tasks.isChecking(task.id), ...(view.lifecycle ? { lifecycle: view.lifecycle } : {}) };
       }),
       links: links.filter(link => link.tasks.every(id => { const task = board.get(id); return task && !tasks.isPii(task); })),
       budget: Object.fromEntries(peers.map((id) => [id, { ...(quota[accountOf(id)] ?? { windows: [] }), context: contexts.view(id, contextSession(id), bus.peers.has(id) && ["idle", "busy", "paused"].includes(bus.stateOf(id))) }])),
@@ -4391,6 +4577,7 @@ export async function startDaemon(opts: DaemonOptions) {
       roster: rosterView(),
       ...benchView(),
       ...memoryView(_input?.memory),
+      usage: usageView(_input?.view === "agents"),
     };
   }
 
@@ -4487,7 +4674,7 @@ export async function startDaemon(opts: DaemonOptions) {
         settledHolderChange = JSON.stringify(oldHolders) !== JSON.stringify(newHolders);
         if (settledHolderChange) effect = `planner ${JSON.stringify(oldHolders.planners)} -> ${JSON.stringify(newHolders.planners)}; conductor ${JSON.stringify(oldHolders.conductors)} -> ${JSON.stringify(newHolders.conductors)}`;
       }
-      const input = { key, before, acceptedFallback, settledHolderChange, after: machine && rawChanged ? rawAfter : after, source: route ? "routing" as const : "config" as const, tracked, authority, guard, confirmed: !!scope || confirmed.includes(key) };
+      const input = { key, before, acceptedFallback, settledHolderChange, after: machine && rawChanged ? rawAfter : after, source: route ? "routing" as const : "config" as const, sourceFile: origin?.name, tracked, authority, guard, confirmed: !!scope || confirmed.includes(key) };
       const decision = authorizeConfigLeaf(input);
       if (!decision.allowed) {
         const next = `${decision.reason}; review and run ahub settings reload, or revert this key${machine && tracked !== false ? "; move machine-local declarations to an untracked local file first" : ""}`;
@@ -4603,6 +4790,7 @@ export async function startDaemon(opts: DaemonOptions) {
         if (change.applies === "restart" || change.key === "roles" || change.key.startsWith("roles.")) continue;
         putConfig(config, change.key, change.after);
       }
+      if (changes.some(change => change.key === "action_policy" || change.key.startsWith("action_policy."))) actionBudgets.policyChanged();
       if (rolesChanged) { policyRoles = structuredClone(prepared.running.roles); settlePlanner(); }
       for (const change of changes.filter(change => change.key === "permission_modes" || change.key.startsWith("permission_modes."))) {
         for (const peer of change.key === "permission_modes" ? SUPPORTED_PEERS : [change.key.split(".")[1]!]) changedPermissionDefaults.add(peer);
@@ -4936,7 +5124,7 @@ export async function startDaemon(opts: DaemonOptions) {
     if (a.action === "sdlc_queue" || a.action === "sdlc_release") {
       const liveIssues = a.liveIssues ?? [];
       if (typeof a.repo !== "string" || !Array.isArray(liveIssues) || liveIssues.length > 32) return bad;
-      const report = a.action === "sdlc_queue" ? await tasks.deliveryQueue(a.repo) : await tasks.releaseReadiness(a.repo, liveIssues);
+      const report = a.action === "sdlc_queue" ? await tasks.deliveryQueue(a.repo) : releaseAuthorizations.report(await tasks.releaseReadiness(a.repo, liveIssues));
       return { ok: true, report };
     }
     switch (a.action) {
@@ -5313,6 +5501,12 @@ export async function startDaemon(opts: DaemonOptions) {
         c.peer = String(msg.peer ?? "");
         if (!PEER_ID.test(c.peer) || c.peer === USER || c.peer === "hub") return sock.close(4403, "peer id is reserved or malformed");
         if (!membershipAllowed(c.peer)) return sock.close(4000, "peer is off roster; retry when a person adds it");
+        // #368: a hub-tools socket for an owned Jcode (a project-file MCP entry, which names no peer) is admitted only with the launch id of that
+        // peer's current owned launch. A forged AGENTHUB_PEER_ID in some other process has no such id, so it never acts as that peer.
+        if (definitionOf(c.peer)?.start.daemonPort === "owned-acp") {
+          const owner = jcodeLaunches.get(c.peer);
+          if (!owner || !owner.ownsLaunch(msg.launchId)) return sock.close(4403, "this process is not an owned launch of that peer; start it with ahub jcode");
+        }
       } else {
         c.peer = String(msg.peer ?? defaultChannelPeer(undefined));
         if (definitionOf(c.peer)?.transport === "ws-pull" && msg.channel !== false) return sock.close(4403, "this native peer supports pull-only attachment; use hub_inbox");
@@ -5376,6 +5570,31 @@ export async function startDaemon(opts: DaemonOptions) {
           if (msg.peer !== undefined && (typeof msg.peer !== "string" || !PEER_ID.test(msg.peer))) return void reply({ ok: false, error: "invalid peer" });
           return void reply({ ok: true, deliveries: bus.queueList(msg.peer).map((row) => queueView(row)) });
         }
+        if (msg.op === "discard") {
+          // #713: the person's bulk clear of one peer's backlog. Without `confirmed` it only counts; with it, every queued (or needs_review) delivery of that peer is discarded
+          // through the same `resolveDelivery` as one by one, each with the reason, so the journal records each as a `resolve ... discard`. Push peers' queues are never touched
+          // because only the named peer is read. Refused while recovery or shutdown holds queue mutations, like every queue resolution.
+          if (typeof msg.peer !== "string" || !PEER_ID.test(msg.peer)) return void reply({ ok: false, error: "peer must be a peer id" });
+          const state = msg.state === undefined ? "queued" : msg.state;
+          if (state !== "queued" && state !== "needs_review") return void reply({ ok: false, error: "state is queued or needs_review" });
+          const rows = bus.queueList(msg.peer).filter((row) => row.state === state);
+          if (msg.confirmed !== true) return void reply({ ok: true, op: "discard", peer: msg.peer, state, count: rows.length, discarded: 0, refused: 0 });
+          if (typeof msg.reason !== "string" || !msg.reason.trim() || msg.reason.length > 2000) return void reply({ ok: false, error: "discard needs a reason" });
+          if (recoveryActive() || stopping) return void reply({ ok: false, error: "recovery or shutdown is holding queue mutations" });
+          let discarded = 0; const refused: Record<string, number> = {};
+          for (const row of rows) {
+            // A queued row with no journal record of its own carries the journal's global revision, which every discard moves: read the row's current revision just before
+            // discarding it, so the 12th discard is not refused as stale because of the 11 before it. A row that is gone or changed state meanwhile is counted as refused.
+            const current = bus.queueShow(row.id) ?? bus.queueList(msg.peer).find((r) => r.id === row.id);
+            try {
+              if (!current || current.state !== state) throw new Error("unknown delivery");
+              bus.resolveDelivery(row.id, current.revision, "discard", msg.reason.trim()); discarded++;
+            }
+            catch (error) { const why = resolutionRefusal(error).split(":")[0]!; refused[why] = (refused[why] ?? 0) + 1; }
+          }
+          writeStatus();
+          return void reply({ ok: true, op: "discard", peer: msg.peer, state, count: rows.length, discarded, refused: rows.length - discarded, ...(rows.length - discarded ? { refusedBy: refused } : {}) });
+        }
         if (typeof msg.id !== "string" || !msg.id || msg.id.length > 256) return void reply({ ok: false, error: "invalid delivery ID" });
         if (msg.op === "show") {
           const row = bus.queueShow(msg.id);
@@ -5387,7 +5606,7 @@ export async function startDaemon(opts: DaemonOptions) {
           bus.resolveDelivery(msg.id, msg.revision, msg.action, msg.reason.trim());
           writeStatus();
           return void reply({ ok: true, delivery: queueView(bus.queueShow(msg.id)) });
-        } catch { return void reply({ ok: false, error: "resolution refused: refresh the delivery revision and inspect active or already resolved work" }); }
+        } catch (error) { return void reply({ ok: false, error: resolutionRefusal(error) }); }
       }
       case "delivery_holds": {
         if (!c.peer || (c.role !== "peer" && c.role !== "tools")) return void reply({ ok: false, error: "held metadata requires a peer identity" });
@@ -5413,9 +5632,15 @@ export async function startDaemon(opts: DaemonOptions) {
           const envs = bus.pull(peer.id);
           if (!envs) return void reply({ ok: false, error: queueHold(peer.id) ?? (bus.isRecoveryHeld ? "recovery is holding deliveries" : pauseReason(peer.id)) });
           peer.lastInboxAt = Date.now();
+          let polling: ReturnType<InboxPolling["read"]>;
+          try {
+            const assigned = peer.pullOnly && board.statusTasks().some(task => !isClosedTaskState(task.state) && task.state !== "backlog" && (task.owner === peer.id || task.reviewer === peer.id));
+            polling = peer.pullOnly ? inboxPolling.read(peer.id, envs.length === 0, assigned, peer.lastInboxAt) : undefined;
+            if (polling?.notice) notify(`${peer.id} is polling an empty inbox with no task (${polling.count} empty reads in ${polling.minutes} min)`);
+          } catch { polling = undefined; } // The pull already completed: advice must never discard its envelopes.
           writeStatus();
           if (envs.length) log(`${peer.id} read ${envs.length} queued message(s) through hub_inbox`);
-          return void reply({ ok: true, envs, waiting: bus.queued(peer.id), waitingImportant: bus.queuedImportant(peer.id) });
+          return void reply({ ok: true, envs, waiting: bus.queued(peer.id), waitingImportant: bus.queuedImportant(peer.id), ...(polling ? { pollingAdvice: { count: polling.count, minutes: polling.minutes } } : {}) });
         } catch { return void reply({ ok: false, error: "delivery journal unavailable" }); }
       }
       case "delivery_complete": {
@@ -5749,11 +5974,31 @@ export async function startDaemon(opts: DaemonOptions) {
           return void reply({ t: "ui", ok: false, error: "could not start the dashboard" });
         }
       case "sdlc": {
+        if (msg.op === "release-guard" || msg.op === "release-guard-hook") {
+          if (c.role !== "console" && c.role !== "tools" && c.role !== "peer" || c.peer && (!!turns.get(c.peer)?.private || contextPii(c.peer))) return void reply({ ok: false, error: "release guard unavailable for this caller" });
+          if (msg.op === "release-guard") {
+            const parsed = parseReleaseGuardArgv(msg.argv);
+            if (!parsed.ok) return void reply({ ok: false, error: parsed.reason });
+            void releaseAuthorizations.guardRequest(parsed.request).then(reply, () => reply({ ok: false, error: "release guard evidence unavailable" }));
+          } else {
+            const parsed = parseReleasePushUpdates(msg.remoteName, msg.remoteUrl, msg.stdin);
+            if (!parsed.ok) return void reply({ ok: false, error: parsed.reason });
+            reply(releaseAuthorizations.guardPush(parsed.remoteName, parsed.remoteUrl, parsed.updates));
+          }
+          return;
+        }
         if (c.role !== "console") return void reply({ ok: false, error: "SDLC readback is console only; task owners record ids through hub_sdlc_record" });
+        if (msg.op === "authorize-release") {
+          void releaseAuthorizations.authorize(USER, msg.version, msg.commit).then(
+            authorization => reply({ ok: true, authorization }),
+            error => reply({ ok: false, error: releaseAuthorizationError(error) }),
+          );
+          return;
+        }
         if (msg.op === "queue" || msg.op === "release") {
           if (typeof msg.repo !== "string" || !Array.isArray(msg.liveIssues ?? []) || (msg.liveIssues ?? []).length > 32) return void reply({ ok: false, error: "invalid delivery readback arguments" });
           const read = msg.op === "queue" ? tasks.deliveryQueue(msg.repo) : tasks.releaseReadiness(msg.repo, msg.liveIssues ?? []);
-          void read.then(report => reply({ ok: true, report }), () => reply({ ok: false, error: "delivery readback unavailable" }));
+          void read.then(report => reply({ ok: true, report: msg.op === "release" ? releaseAuthorizations.report(report as Awaited<ReturnType<typeof tasks.releaseReadiness>>) : report }), () => reply({ ok: false, error: "delivery readback unavailable" }));
           return;
         }
         if (msg.op === "export") {
@@ -5788,7 +6033,11 @@ export async function startDaemon(opts: DaemonOptions) {
         if (msg.id !== undefined && (!Number.isSafeInteger(msg.id) || msg.id <= 0 || !selected.length)) return void reply({ ok: false, error: "invalid lifecycle task id" });
         void (async () => {
           const rows = [];
-          for (const task of selected.slice(0, 100)) rows.push({ id: task.id, title: tasks.publicTitle(task), ...(tasks.isPii(task) ? {} : { receipt: task.sdlc }), ...await tasks.lifecycleStatus(task.id, msg.id !== undefined) });
+          for (const task of selected.slice(0, 100)) {
+            const status = await tasks.lifecycleStatus(task.id, msg.id !== undefined);
+            const current = board.get(task.id) ?? task;
+            rows.push({ id: task.id, title: tasks.publicTitle(current), ...(tasks.isPii(current) ? {} : { receipt: tasks.publicView(current).sdlc }), ...status });
+          }
           reply({ ok: true, mode: lifecycleConfig.mode, rows, truncated: selected.length > 100 });
         })().catch(() => reply({ ok: false, error: "lifecycle readback unavailable" }));
         return;
@@ -5805,7 +6054,7 @@ export async function startDaemon(opts: DaemonOptions) {
       case "ui_snapshot":
         if (c.role !== "console") return void reply({ ok: false, error: "ui_snapshot is a console command" });
         if (!Number.isSafeInteger(msg.after ?? 0) || (msg.after ?? 0) < 0) return void reply({ ok: false, error: "invalid cursor" });
-        return void reply(uiSnapshot(msg.after ?? 0, msg.memory !== undefined ? { memory: msg.memory } : undefined));
+        return void reply(uiSnapshot(msg.after ?? 0, msg.memory !== undefined || dashboardView(msg.view) ? { ...(msg.memory !== undefined ? { memory: msg.memory } : {}), ...(dashboardView(msg.view) ? { view: msg.view } : {}) } : undefined));
       case "ui_action":
         if (c.role !== "console") return void reply({ ok: false, error: "ui_action is a console command" });
         if (recoveryActive()) return void reply({ ok: false, error: "recovery is holding mutations" });
@@ -5964,6 +6213,41 @@ export async function startDaemon(opts: DaemonOptions) {
           budget.report(String(msg.set.peer), [{ id: msg.set.window === "week" ? "week" : "5h", used, ...(msg.set.resetsInMs ? { resetsAt: Date.now() + Number(msg.set.resetsInMs) } : {}), source: "ahub budget set" }]);
         }
         return void reply({ t: "budget", ok: true, budget: budget.status(), gate: config.budget.gate });
+      case "usage": {
+        // #683 U2: the console, the person and a configured planner read usage; every other agent is refused. Always answered (rid).
+        const planner = c.role === "tools" && !!c.peer && !!config.roles[c.peer]?.includes("planner");
+        if (c.role !== "console" && !planner) return void reply({ t: "usage", ok: false, error: "usage is read by the person and a configured planner" });
+        if (planner && c.peer && turns.get(c.peer)?.private) return void reply({ t: "usage", ok: false, error: "usage is unavailable during a private turn" });
+        const op = msg.op === undefined ? "query" : msg.op;
+        const num = (v: unknown): number | undefined | null => v === undefined ? undefined : typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : null;
+        const since = num(msg.since), until = num(msg.until);
+        if (since === null || until === null) return void reply({ t: "usage", ok: false, error: "since and until are epoch milliseconds" });
+        if (msg.task !== undefined && !(Number.isSafeInteger(msg.task) && (msg.task as number) > 0)) return void reply({ t: "usage", ok: false, error: "task is a positive task id" });
+        try {
+          // Fold what the log has now, within a time budget: a hub that has just started is still behind a large log, and an answer built from the
+          // part folded so far would read as "no records" for a peer that did use tokens. `behind` says so when the budget ran out (#683 U3).
+          // ponytail: catchUp runs synchronously on the daemon loop, so a request on a log far behind stalls it for up to this budget (about 250 ms
+          // folds the real 47 MB log). Ceiling: a log several times larger answers `behind` and finishes over the 10 s polls; move the fold to a worker if a stall is felt.
+          const behind = !usageRollup.catchUp(250);
+          const reply_ = (body: Record<string, unknown>) => reply({ ...body, ...(behind ? { behind: true } : {}) });
+          if (op === "limits") {
+            if (msg.peer !== undefined && (typeof msg.peer !== "string" || !PEER_ID.test(msg.peer))) return void reply({ t: "usage", ok: false, error: "peer must be a peer id" });
+            if (msg.limit !== undefined && !(Number.isInteger(msg.limit) && (msg.limit as number) >= 1 && (msg.limit as number) <= LIMITS_MAX)) return void reply({ t: "usage", ok: false, error: `limit is an integer from 1 to ${LIMITS_MAX}` });
+            const status = budget.status();
+            // The pauses the hub holds now: an event-open pause it no longer holds (an `ahub reset` cleared it) is reported as ended, not open.
+            const live = new Set(Object.entries(status).filter(([, v]) => v.paused).map(([peer]) => peer));
+            return void reply_({ t: "usage", ok: true, op, limits: usageRollup.limits(msg.peer, { ...(msg.limit !== undefined ? { limit: msg.limit as number } : {}), live }), current: publicPeerBudget(status, text => tasks.nameable(text)) });
+          }
+          if (op === "total") return void reply_({ t: "usage", ok: true, op, total: usageRollup.total() });
+          if (op !== "query") return void reply({ t: "usage", ok: false, error: "op is query, limits or total" });
+          const by = (msg.by ?? "peer") as UsageGroup;
+          if (!USAGE_GROUPS.includes(by)) return void reply({ t: "usage", ok: false, error: `by is one of ${USAGE_GROUPS.join(", ")}` });
+          // issue, pr and release are the board's current links of each task (ids only, never a title).
+          const board_ = new Map(board.list().map(t => [t.id, t]));
+          const links = (id: number) => { const t = board_.get(id); return t ? { ...(t.sdlc?.issue ? { issue: t.sdlc.issue } : {}), ...(t.sdlc?.pr ? { pr: t.sdlc.pr } : {}), ...(t.release ? { release: t.release } : {}) } : undefined; };
+          return void reply_({ t: "usage", ok: true, op, usage: usageRollup.query({ by, ...(since !== undefined ? { since } : {}), ...(until !== undefined ? { until } : {}), ...(msg.task !== undefined ? { task: msg.task as number } : {}) }, links) });
+        } catch (error) { return void reply({ t: "usage", ok: false, error: `usage unavailable: ${(error as Error).message.slice(0, 120)}` }); }
+      }
       case "permit":
         if (c.role !== "console") return void reply({ t: "permit", ok: false, error: "permit is a console command" });
         return void reply({ t: "permit", ok: permissions.get(String(msg.id))?.done(msg.option ? String(msg.option) : undefined, msg.surface === "console" ? "console" : "terminal") === true });
@@ -5992,6 +6276,7 @@ export async function startDaemon(opts: DaemonOptions) {
     stopping = true;
     terminalLaunches.clear();
     // Start cancellation immediately; a failed read cleanup must not strand the other owned peers or finalization.
+    const codeFactsStopped = codeFacts.close().catch(() => { log("code facts cleanup failed during shutdown"); });
     const terminalReadsStopped = terminalReads.stop().catch(() => { log("terminal owner query cleanup failed during shutdown"); });
     runnerRefreshAbort.abort();
     // A stop someone asked for is not a crash, even if it then runs past the shutdown deadline: forget the sessions now.
@@ -6007,7 +6292,7 @@ export async function startDaemon(opts: DaemonOptions) {
     for (const pending of checkpointWaits.values()) pending.done(undefined);
     for (const p of permissions.values()) p.done(undefined);
     try {
-      await terminalReadsStopped;
+      await Promise.all([terminalReadsStopped, codeFactsStopped]);
       await terminalLaunches.settled();
       // A peer can still be inside memory recall or its native handshake when kill arrives.
       // Drain those starts before taking the final owned-process snapshot.
@@ -6108,8 +6393,8 @@ export async function startDaemon(opts: DaemonOptions) {
   // After a crash that recorded Pi, crash recovery starts it (#66): its recorded session first, a fresh one if that fails.
   const piRecovered = !archivedPiContinuity && !!crashed?.peers.some((p) => definitionOf(p.peer)?.session.restoreOnStart);
   if (piAutoStart() && !recoveryActive() && !piRecovered) autoStartPi();
-  return { bus, token, port: server.port as number, stop, stopped: new Promise<void>((r) => (onStop = r)) };
+  return { bus, token, port: server.port as number, bandEvaluations: () => bandEvaluations, stop, stopped: new Promise<void>((r) => (onStop = r)) };
   } finally {
-    if (!ready) for (const cleanup of startupCleanup.reverse()) { try { cleanup(); } catch { /* preserve startup error */ } }
+    if (!ready) for (const cleanup of startupCleanup.reverse()) { try { await cleanup(); } catch { /* preserve startup error */ } }
   }
 }