@staix/agent-hub 0.12.23 → 0.12.25

package/src/cli/bench.ts

@@ -7,9 +7,11 @@ import { ControlClient } from "../hub/control-client.ts";
 import { readEvents } from "../hub/events.ts";
 import { hubGitArgv, hubGitEnv } from "../hub/git.ts";
 import { taskRecords } from "../hub/research.ts";
-import { appendBench, BENCH_SCHEMA, parseSuite, suiteHash, type Attempt, type AttemptError, type AttemptMetrics, type Fingerprint, type Outcome, type SuiteTask } from "../hub/bench.ts";
+import { appendBench, BENCH_SCHEMA, memoryMode, type MemoryMode, parseSuite, suiteHash, type Attempt, type AttemptError, type AttemptMetrics, type Fingerprint, type Outcome, type SuiteTask } from "../hub/bench.ts";
 import { hubHome, realPath } from "../hub/project.ts";
 import { processSignature } from "../pi/process-signature.ts";
+import { loadConfig } from "../hub/daemon.ts";
+import { addonState, detectTooling, type Addon, type AddonName } from "../hub/tooling.ts";
 import { VERSION } from "../version.ts";
 
 /** What the runner needs from the world, so tests can drive it without a terminal. */
@@ -24,8 +26,12 @@ export interface BenchIo {
   now(): number;
   sleep(ms: number): Promise<void>;
   log(line: string): void;
+  /** #248: the add-ons a peer works with; `detectTooling` on this machine unless a test supplies its own. */
+  tooling?(peer: string): Addon[] | Promise<Addon[]>;
+  /** #258: the memory settings the project's hub runs with; the project config unless a test supplies them. */
+  memoryConfig?(): { enabled: boolean; native?: boolean };
 }
-export interface BenchOptions { cwd: string; stateDir: string; suitePath: string; arm: string; repeat: number; only?: string[]; home?: string; pollMs?: number; verifyTimeoutMs?: number; setupTimeoutMs?: number; settleMs?: number; stopped?: () => boolean }
+export interface BenchOptions { cwd: string; stateDir: string; suitePath: string; arm: string; repeat: number; addons?: Partial<Record<AddonName, "on" | "off">>; memory?: MemoryMode; only?: string[]; home?: string; pollMs?: number; verifyTimeoutMs?: number; setupTimeoutMs?: number; settleMs?: number; stopped?: () => boolean }
 
 const fail = (message: string): never => { throw new Error(message); };
 
@@ -192,12 +198,25 @@ export async function runBench(opts: BenchOptions, io: BenchIo): Promise<string>
       // ponytail: the hub's status reports a requested model for Pi only and permission modes once #242 lands; the rest
       // are recorded as absent. Reading each peer's launch settings would fill them in.
       // The status lists every peer the hub has known; an arm is the ones attached now.
-      peers: Object.entries(status.peers ?? {}).filter(([, p]) => p.state !== "offline")
-        .map(([id, p]) => ({ id, ...(p.requestedModel ? { model: p.requestedModel } : {}), ...(p.permissionMode ? { permissionMode: p.permissionMode } : {}) })).sort((a, b) => a.id.localeCompare(b.id)),
+      peers: (await Promise.all(Object.entries(status.peers ?? {}).filter(([, p]) => p.state !== "offline")
+        .map(async ([id, p]) => ({ id, ...(p.requestedModel ? { model: p.requestedModel } : {}), ...(p.permissionMode ? { permissionMode: p.permissionMode } : {}),
+          addons: await (io.tooling ?? ((peer: string) => detectTooling(peer, { cwd: opts.cwd })))(id) })))).sort((a, b) => a.id.localeCompare(b.id)),
       routingHash: existsSync(routing) ? createHash("sha256").update(readFileSync(routing)).digest("hex") : null,
       hubVersion: status.version,
     };
+    // #248: a declared add-on condition must hold for the attached peers before anything is recorded or reset.
+    const addons = Object.entries(opts.addons ?? {}) as [AddonName, "on" | "off"][];
+    for (const [name, want] of addons) {
+      const found = addonState(name, fingerprint.peers.map((p) => p.addons));
+      if (found !== want) throw new Error(`the arm declares ${name} ${want}, but the attached peers have it ${found}; change their setup or the declaration (nothing was run)`);
+    }
+    // #258 AC11: the memory the project's hub runs with (its config, read at hub start) must be the arm's.
+    // ponytail: read from the project config, not the running hub; a config edited since the hub started reads wrong.
+    const runsWith = opts.memory ? memoryMode((io.memoryConfig ?? (() => loadConfig(opts.cwd).memory))()) : undefined;
+    if (opts.memory && runsWith !== opts.memory) throw new Error(`the arm declares memory ${opts.memory}, but this project's hub runs with ${runsWith}; change memory.enabled / memory.native and restart the hub, or the declaration (nothing was run)`);
+    const condition = { ...(addons.length ? { addons: Object.fromEntries(addons.sort(([a], [b]) => a.localeCompare(b))) } : {}), ...(opts.memory ? { memory: opts.memory } : {}) };
     appendBench({ schema: BENCH_SCHEMA, kind: "run", run, suite: suite.name, suiteHash: suiteHash(suiteText), arm: opts.arm, fingerprint, version: VERSION,
+      ...(Object.keys(condition).length ? { condition } : {}),
       startedAt: new Date(io.now()).toISOString(), tasks: tasks.length, repeats: opts.repeat, order: tasks.map((t) => t.id), runner: { pid: process.pid, signature: processSignature(process.pid) ?? null } }, home);
     io.log(`bench run ${run}: ${suite.name} [${opts.arm}], ${tasks.length} task${tasks.length === 1 ? "" : "s"} x ${opts.repeat}`);
     let stopped: "timeout" | "interrupted" | "error" | undefined;
@@ -237,7 +256,7 @@ async function runAttempt(task: SuiteTask, commit: string, repeat: number, run:
   // The attempt ends when its outcome is known: the wait for its measures is not part of its time.
   const done = (outcome: Outcome, extra: { error?: AttemptError; verifyExit?: number | null; hubTask?: number | null; metrics?: AttemptMetrics | null; ended?: number; open?: boolean } = {}) => {
     const ended = extra.ended ?? io.now();
-    const attempt: Attempt = { schema: BENCH_SCHEMA, kind: "attempt", run, task: task.id, repeat, outcome, ...(extra.error ? { error: extra.error } : {}), verifyExit: extra.verifyExit ?? null,
+    const attempt: Attempt = { schema: BENCH_SCHEMA, kind: "attempt", run, arm: opts.arm, task: task.id, repeat, outcome, ...(extra.error ? { error: extra.error } : {}), verifyExit: extra.verifyExit ?? null,
       hubTask: extra.hubTask ?? null, startedAt: new Date(started).toISOString(), endedAt: new Date(ended).toISOString(), ms: ended - started, metrics: extra.metrics ?? null };
     return { attempt, open: extra.open ?? false };
   };

package/src/cli/board-read.ts

@@ -0,0 +1,12 @@
+/** Older same-protocol daemons may ignore newly added filter arguments. */
+export function supportsBoardReleaseFilter(status: unknown): boolean {
+  if (!status || typeof status !== "object") return false;
+  const capability = (status as Record<string,unknown>).boardReadCapabilities;
+  return !!capability && typeof capability === "object" && (capability as Record<string,unknown>).releaseFilter === true;
+}
+
+export function supportsBoardColumnMetadata(status: unknown): boolean {
+  if (!status || typeof status !== "object") return false;
+  const capability = (status as Record<string,unknown>).boardReadCapabilities;
+  return !!capability && typeof capability === "object" && (capability as Record<string,unknown>).columnMetadata === true;
+}

package/src/cli/console-state.ts

@@ -1,3 +1,6 @@
+import { consoleNeeds, characterAttentionLine, attentionCommand } from "./attention.ts";
+import { CHARACTERS, petFrame, petSize, petFooterRows, type CharacterId, type PetSize, type PetPose } from "../pet/frame.ts";
+import { PEER_PALETTE } from "../ui/peer-palette.ts";
 import { PERMISSION_MODES, permissionBoundary } from "../hub/permission-mode.ts";
 import { taskProgress } from "../ui/task-progress.ts";
 import type { ProgressStage } from "../ui/task-progress.ts";
@@ -10,6 +13,11 @@ export interface Approval {
 export interface PermissionDefault { peer: string; mode: "never-ask"; source: string }
 export interface ConsoleEvent { text: string; peer?: string; kind?: string; tone?: Tone }
 export interface ConsoleState {
+  /** Older embedding callers omit choices and retain the original STAI/off toggle. */
+  petChoices?: readonly CharacterId[]; petCharacter?: CharacterId; petSize?: PetSize; petGlyphs?: "ascii" | "blocks";
+  attentionFacts?: { kind: "review" | "offline"; id: number; peer?: string }[];
+  attentionFingerprint?: string;
+  petEnabled?: boolean; petBlink?: boolean; attentionMessages?: { id?: string; peer?: string; important: boolean; since?: number }[]; storageBlocked?: boolean; recoveryNeed?: { id?: string; running: boolean; since?: number }; attentionSelection?: number;
   mode: "stream" | "panels"; panel: number; selection: number;
   /** The selected request, by id: a, d and v act on it alone, and it is cleared, never moved, when the request closes. */
   approvalId?: string;
@@ -77,9 +85,9 @@ export function terminalText(value: unknown): string {
 export type Tone = "info" | "strong" | "success" | "attention" | "failure" | "muted" | "peerClaude" | "peerCodex" | "taskKeyword" | "number" | "issueRef" | "taskRef";
 export interface Span { text: string; tone?: Tone }
 export const PALETTE: Readonly<Record<Tone, string>> = Object.freeze({
-  info: "\x1b[36m", strong: "\x1b[1;36m", success: "\x1b[32m", attention: "\x1b[33m", failure: "\x1b[31m", muted: "\x1b[90m",
-  peerClaude: "\x1b[94m", peerCodex: "\x1b[96m",
-  taskKeyword: "\x1b[35m", number: "\x1b[1m", issueRef: "\x1b[4m", taskRef: "\x1b[4;35m",
+  info: PEER_PALETTE.hub.ansi, strong: "\x1b[1;36m", success: PEER_PALETTE.local.ansi, attention: PEER_PALETTE.pi.ansi, failure: "\x1b[31m", muted: PEER_PALETTE.other.ansi,
+  peerClaude: PEER_PALETTE.claude.ansi, peerCodex: PEER_PALETTE.codex.ansi,
+  taskKeyword: PEER_PALETTE.kimi.ansi, number: "\x1b[1m", issueRef: "\x1b[4m", taskRef: "\x1b[4;35m",
 });
 export function paint(line: Span[], color: boolean): string {
   return line.map(span => {
@@ -179,7 +187,10 @@ export function stateTone(state: string): Tone | undefined {
 }
 const span = (text: unknown, tone?: Tone): Span => ({ text: String(text ?? ""), ...(tone ? { tone } : {}) });
 /** One line of sanitized text: a newline or a tab becomes a space, as wrap() counts a tab (stringWidth("\t") is 0). */
-const flat = (value: unknown) => terminalText(value).replace(/[\n\t]/g, " ");
+const flat = (value: unknown) => {
+  const text = terminalText(value), line = text.replace(/[\n\t]/g, " ");
+  return text.includes("\t") ? terminalText(line) : line;
+};
 /**
  * Clip sanitized plain text to the width and keep the tones of the surviving prefix. Widths are measured as paint()
  * prints them: paint() sanitizes each span again, and a cut that ends a span in `[agent-hub` earns it a `> `.
@@ -313,9 +324,9 @@ const KEYS: [string, string[]][] = [
   ["Events", ["f peer filter", "g kind filter"]],
 ];
 /** The `?` key table: one group per panel, its keys kept whole and packed into the width after the group column. */
-export function keyTable(columns: number): Span[][] {
+export function keyTable(columns: number, attention = false, characters = false): Span[][] {
   const lines: Span[][] = []; const pad = 12;
-  for (const [group, items] of KEYS) {
+  for (const [group, items] of [...KEYS, ...(attention ? [[characters ? "Pet" : "Attention", ["n next need", characters ? "P next character/off" : "P STAI/off"]] as [string, string[]]] : [])]) {
     let text = ""; let head = group;
     const flush = () => { lines.push([span(head.padEnd(pad), head ? "info" : undefined), span(text)]); head = ""; text = ""; };
     for (const item of items) { if (text && pad + Bun.stringWidth(`${text}   ${item}`) > columns) flush(); text = text ? `${text}   ${item}` : item; }
@@ -341,7 +352,7 @@ function bound(s: ConsoleState): ConsoleState {
   if (s.requestDetail && s.requestDetail !== s.approvalId) { s.requestDetail = s.approvalId; s.detailOffset = 0; }
   return s;
 }
-const COMMANDS = new Set(["status", "board", "task", "review", "say", "pause", "resume", "budget", "queue", "permit", "permission", "ask", "remember", "route", "turns", "undo", "check-path", "report"]);
+const COMMANDS = new Set(["status", "board", "task", "review", "say", "pause", "resume", "budget", "queue", "permit", "permission", "ask", "remember", "route", "sdlc", "turns", "undo", "check-path", "report"]);
 /** A tiny argv parser, never a shell. Quotes group arguments; backslash escapes one character. */
 export function parseConsoleCommand(input: string): string[] {
   const words: string[] = []; let word = ""; let quote = ""; let escaped = false; let started = false;
@@ -377,6 +388,7 @@ export const selectedApproval = (s: ConsoleState) => s.approvals.find(a => a.id
 /** The selected row: the Approvals panel's is the selected request (-1 when none is). */
 const selection = (s: ConsoleState) => s.panel === 2 ? s.approvals.findIndex(a => a.id === s.approvalId) : s.selection;
 export function reduceConsole(state: ConsoleState, key: string, now = Date.now()): { state: ConsoleState; effects: ConsoleEffect[] } {
+  const attentionKeyBlocked = !!(state.confirm || state.optionChoice || state.modeChoice || state.help || state.editing || state.input);
   // A notice answers the key before this one; one that pruning raises now stays.
   let s = pruneApprovals({ ...state, notice: "" }, now); const effects: ConsoleEffect[] = [];
   const done = () => ({ state: bound(s), effects });
@@ -438,7 +450,47 @@ export function reduceConsole(state: ConsoleState, key: string, now = Date.now()
     } else if (!key.startsWith("\x1b")) s.input += terminalText(key).replace(/\n/g, "");
     return done();
   }
+  if ((key === "n" || key === "P") && attentionKeyBlocked) return done();
   if (key === "q") { effects.push({ type: "exit" }); return done(); }
+  if (key === "P" && !s.optionChoice && !s.help) {
+    const choices = s.petChoices;
+    if (!choices?.length) s.petEnabled = !s.petEnabled;
+    else if (!s.petEnabled) { s.petEnabled = true; s.petCharacter = choices[0]; }
+    else { const next = choices.indexOf(s.petCharacter ?? "stai") + 1; s.petEnabled = next < choices.length; if (s.petEnabled) s.petCharacter = choices[next]; }
+    return done();
+  }
+  if (key === "n" && s.petEnabled && !s.optionChoice && !s.help) {
+    const items = consoleNeeds(s, now).items;
+    if (!items.length) return done();
+    const fingerprint = JSON.stringify(items);
+    const prior = s.attentionFingerprint === fingerprint ? s.attentionSelection ?? -1 : -1;
+    const index = (prior + 1) % items.length;
+    s.attentionFingerprint = fingerprint;
+    s.attentionSelection = index;
+    const item = items[index]!;
+    let navigated = false;
+    if (item.kind === "approval") {
+      s.approvalId = String(item.id);
+      if (s.mode === "panels") { s.panel = 2; s.selection = s.approvals.findIndex(row => row.id === item.id); }
+      navigated = true;
+    } else if (item.kind === "delivery" && s.mode === "panels") {
+      const rows = s.queue.filter(row => row.state === "needs_review" || row.state === "queued");
+      const selected = item.id === undefined ? -1 : rows.findIndex(row => row.id === item.id);
+      if (selected >= 0) { s.panel = 4; s.selection = selected; navigated = true; }
+    } else if (item.kind === "review" && s.mode === "panels") {
+      const rows = panelRows({ ...s, panel: 3 });
+      const selected = rows.findIndex(row => row.id === item.id);
+      if (selected >= 0) { s.panel = 3; s.selection = selected; navigated = true; }
+    }
+    if (navigated) { s.detail = undefined; s.requestDetail = undefined; }
+    else {
+      const command = attentionCommand(item);
+      const text = `${item.kind}${item.peer ? ` ${item.peer}` : ""}${item.id ? ` ${item.id}` : ""}: ${command}`;
+      if (s.mode === "panels") notify(s, text, now, "attention");
+      effects.push({ type: "print", text, kind: "attention", tone: "attention" });
+    }
+    return done();
+  }
   if (key === "\t") { s.mode = s.mode === "panels" ? "stream" : "panels"; s.detail = undefined; s.requestDetail = undefined; return done(); }
   if (key === ":") { s.editing = true; return done(); }
   const switchPanel = (panel: number) => { s.panel = panel; s.selection = 0; s.detail = undefined; s.requestDetail = undefined; return done(); };
@@ -523,6 +575,9 @@ export function renderConsole(s: ConsoleState, columns: number, rows = 24, now =
   return renderConsoleLines(s, columns, rows, now).map(line => paint(line, false));
 }
 const NOTICE_MS = 10_000;
+export function activeNotice(s: Pick<ConsoleState, "notice" | "noticeAt">, now = Date.now()): boolean {
+  return !!s.notice && now - (s.noticeAt ?? now) < NOTICE_MS;
+}
 export const TABLES: Record<number, string[]> = {
   1: ["PEER", "STATE", "LINK", "Q", "!", "REVIEW", "PAUSE", "QUOTA", "MODEL"],
   2: ["ID", "PEER", "LEFT", "TITLE"],
@@ -539,9 +594,9 @@ export function cells(s: ConsoleState, row: any, selected: boolean, now: number,
     const paused = b?.paused ? `budget ${relative(b.paused.resetsAt, now)}` : row.paused && typeof row.paused === "object"
       ? `${row.paused.by ?? "paused"}${typeof row.paused.at === "number" ? ` ${duration(now - row.paused.at)}` : ""}`
       : row.paused === "manual" ? "user" : row.paused ? String(row.paused).split(":")[0] : "-";
-    return [id(row.id, row.state === "offline" ? undefined : "info"), span(row.state, stateTone(row.state)),
+    return [id(row.id, row.state === "offline" ? undefined : "info"), span(row.rostered === false ? `${row.state} off roster` : row.state, stateTone(row.state)),
       ...(showPermissionModes(s) ? [span(row.permissionMode && row.permissionMode !== "ask" ? row.permissionMode : "-", row.permissionMode === "never-ask" ? "attention" : undefined)] : []),
-      span(row.toolsOnly ? "tools-only" : row.attached === false ? "detached" : "attached", row.toolsOnly ? "attention" : undefined),
+      span(row.pullOnly && row.id === "kimi" ? "pull-only" : row.toolsOnly ? "tools-only" : row.attached === false ? "detached" : "attached", row.toolsOnly ? "attention" : undefined),
       span(count(row.queued)), span(count(row.queuedImportant), row.queuedImportant ? "attention" : undefined),
       span(count(row.needsReview), row.needsReview ? "failure" : undefined), span(paused, paused === "-" ? undefined : "attention"),
       span(b?.windows?.length ? b.windows.map((w: any) => `${w.id} ${Math.round(w.used * 100)}%${typeof w.resetsAt === "number" ? ` ${relative(w.resetsAt, now)}` : ""}`).join(", ") : "-"),
@@ -555,9 +610,9 @@ export function cells(s: ConsoleState, row: any, selected: boolean, now: number,
     const stage = stages?.get(row.id);
     const meter = stage ? "[" + "#".repeat(stage.stage - (stage.changes ? 1 : 0)) + (stage.changes ? "!" : "") + "-".repeat(4 - stage.stage) + "]" : "[----]";
     return [id(`#${row.id}`, "info"), span(`${row.state}${failed && row.state !== last.event ? ` ${last.event}` : ""}${row.ready ? " ready" : ""}${stage?.waiting ? " waiting" : ""}`, failed ? "failure" : row.ready || stage?.waiting ? "attention" : stateTone(row.state)),
-      span(row.owner ?? "-"), span(row.reviewer ?? "-"), span(row.class ?? "-"), span(typeof at === "number" ? duration(now - at) : "-", "muted"), span(row.title), span(meter, stage?.changes ? "failure" : stateTone(row.state))];
+      span(row.owner ?? "-"), span(row.reviewer ?? "-"), span(row.profileClass ? `${row.profileClass} (base ${row.class})` : row.class ?? "-"), span(typeof at === "number" ? duration(now - at) : "-", "muted"), span(row.title), span(row.lifecycle ? `${meter} ${row.lifecycle.workflow ? row.lifecycle.workflow + " " : ""}SDLC ${row.lifecycle.stage}${row.lifecycle.definition ? ` (base ${row.lifecycle.definition.base}) / next: ${row.lifecycle.actor} / entry: ${row.lifecycle.entry?.length ? "blocked" : "ready"} / exit: ${row.lifecycle.exit?.length ? "blocked" : "ready"}` : ""}: ${row.lifecycle.next}` : meter, stage?.changes ? "failure" : stateTone(row.state))];
   }
-  if (s.panel === 4) return [id(row.id, "info"), span(row.peer), span(row.state, stateTone(row.state)), span(row.revision ?? "-"), span(typeof row.createdAt === "number" ? duration(now - row.createdAt) : "-", "muted")];
+  if (s.panel === 4) return [id(row.id, "info"), span(row.peer), span(row.rostered === false ? `${row.state} off roster` : row.state, stateTone(row.state)), span(row.revision ?? "-"), span(typeof row.createdAt === "number" ? duration(now - row.createdAt) : "-", "muted")];
   const [header, ...body] = String(row.text).split("\n");
   // The header goes through the stream's own tokenizer with the event's tone and kind, on the same tab-flattened
   // text the stream tokenizes, so an event reads the same in both places (#309); body lines stay plain, as in the
@@ -617,6 +672,35 @@ function header(s: ConsoleState, columns: number): Span[] {
 }
 /** The label column is the hub's own: a cut title or option list is marked `(more)` there; Enter shows it whole. */
 const more = (line: Span[], text?: string): Span[] => [span("(more)".padEnd(Bun.stringWidth(line[0]!.text)), "attention"), ...(text === undefined ? line.slice(1) : [span(text)])];
+export function consoleFooterRows(s: ConsoleState, columns: number, rows: number): number {
+  return s.petEnabled ? petFooterRows(petSize(s.petSize, columns, rows)) : 4;
+}
+function decoratePetFooter(s: ConsoleState, columns: number, rows: number, now: number, rule: Span[], footer: Span[][], noticeShown: boolean): Span[][] {
+  if (!s.petEnabled) return [rule, ...footer];
+  const value = consoleNeeds(s, now), character = s.petCharacter ?? "stai", size = petSize(s.petSize, columns, rows);
+  const tone: Tone = value.state === "blocked" ? "failure" : value.act ? "attention" : "muted";
+  if (size === "line") {
+    const text = characterAttentionLine(value, character, now, s.petBlink, true, s.petGlyphs);
+    return [Bun.stringWidth(text) + 4 <= columns ? [span("-".repeat(columns - Bun.stringWidth(text) - 2) + " ", "muted"), span(text.slice(0, 5)), span(text.slice(5), tone), span("-", "muted")] : rule, ...footer];
+  }
+  const pose: PetPose = s.petBlink && value.items.some(item => item.kind === "approval") && Math.floor(now / 1000) % 2 ? "waitingBlink" : value.state;
+  const frame = petFrame(character, pose, size, s.petGlyphs), width = size === "mini" ? 9 : 12, height = size === "mini" ? 3 : 8;
+  const available = columns - width - 1, caption = characterAttentionLine(value, character, now, false).slice(6);
+  const left: Span[][] = [[span(caption, tone)], footer[0]!, footer[1]!];
+  // Notices and source paths stay in their existing views, never beside an expanded character.
+  if (noticeShown || s.confirm?.type === "permission_default") left[2] = [span(`${s.approvals.length} approvals / ${value.act} action / ${value.watch} watch`, tone)];
+  for (let index = 0; index < height - 3; index++) {
+    const item = value.items[index];
+    left.push(item ? [span([item.kind, item.peer, item.id].filter(part => part !== undefined).join(" "), item.level === "act" ? "attention" : "muted")] : []);
+  }
+  const result = left.map((line, index) => {
+    const fitted = fitLine(line, available), text = fitted.map(cell => cell.text).join("");
+    const body = frame[index] ?? " ".repeat(width), accent = CHARACTERS[character].accent?.[size];
+    const bodySpans = accent?.row === index ? [span(body.slice(0, accent.start)), span(body.slice(accent.start, accent.start + accent.length), "attention"), span(body.slice(accent.start + accent.length))] : [span(body)];
+    return [...fitted, span(" ".repeat(Math.max(0, available - Bun.stringWidth(text)) + 1)), ...bodySpans];
+  });
+  return [...result, footer[2]!]; // The prompt line remains full-width and in its original terminal row.
+}
 export function renderConsoleLines(s: ConsoleState, columns: number, rows = 24, now = Date.now()): Span[][] {
   const permission = selectedApproval(s);
   let prompt = s.editing ? `: ${s.input}` : hint(s, columns);
@@ -632,14 +716,14 @@ export function renderConsoleLines(s: ConsoleState, columns: number, rows = 24,
     if (p.permissionMode && p.permissionMode !== "ask") summary.push(span(` ${p.permissionMode}`, "attention"));
     if (p.needsReview) summary.push(span(` review${p.needsReview}`, "failure"));
     if (p.paused) summary.push(span(" paused", "attention"));
-    if (p.toolsOnly) summary.push(span(" tools-only: ahub claude", "attention"));
+    if (p.toolsOnly) summary.push(span(id === "kimi" ? ` pull-only, read ${typeof p.lastInboxAt === "number" ? relative(p.lastInboxAt, now) : "never"}` : " tools-only: ahub claude", "attention"));
   }
   const quotas = Object.entries(s.budget).map(([id, b]) => `${id}:${b.windows?.map((w: any) => `${w.id} ${Math.round(w.used * 100)}%`).join("/") ?? "?"}`).join(" ");
   if (quotas) summary.push(span(`${summary.length ? " | " : ""}${quotas}`));
   const approvals = [span(plural(s.approvals.length, "approval"), s.approvals.length ? "attention" : undefined)];
   if (permission) approvals.push(span(` | ${permission.peer} ${permission.id}`, "attention"), span(` ${duration(permission.expiresAt - now)} left`, "muted"));
   else if (s.approvals.length) approvals.push(span(" | none selected", "muted"));
-  const noticeShown = !!s.notice && now - (s.noticeAt ?? now) < NOTICE_MS;
+  const noticeShown = activeNotice(s, now);
   if (noticeShown) approvals.push(span(" | "), span(s.notice, s.noticeTone ?? "failure"));
   const neverPeer = s.confirm?.type === "permission_default" ? s.confirm.peer : s.confirm?.type === "command" && s.confirm.args[0] === "permission" && s.confirm.args[2] === "never-ask" ? s.confirm.args[1] : undefined;
   const defaultSource = s.confirm?.type === "permission_default" ? s.confirm.source : undefined;
@@ -655,13 +739,15 @@ export function renderConsoleLines(s: ConsoleState, columns: number, rows = 24,
     if (!noticeShown && defaultSource === undefined && (counts || !s.approvals.length) && Bun.stringWidth(taskCount.text + " | " + approvals.map(s => s.text).join("")) <= columns) {
       footer[1] = fitLine([taskCount, span(" | "), ...approvals], columns);
     }
-    return [rule, ...footer];
+    return decoratePetFooter(s, columns, rows, now, rule, footer, noticeShown);
   }
   const progress = taskProgress(s.tasks);
-  const height = rows - 6; // header, rule, body, rule, three footer lines
+  const bodyHeight = rows - 2 - consoleFooterRows(s, columns, rows);
+  const noticeLines = noticeShown && s.petEnabled && petSize(s.petSize, columns, rows) !== "line" ? wrap(`Notice: ${s.notice}`, columns).slice(0, Math.max(0, bodyHeight - 6)).map(text => [span(text, s.noticeTone ?? "failure")]) : [];
+  const height = bodyHeight - noticeLines.length;
   const lines: Span[][] = [];
   if (s.confirm?.type === "permission_default") lines.push(...fieldLines([["default", `${s.confirm.peer} never-ask`], ["source", s.confirm.source], ["bounds", permissionBoundary(s.confirm.peer)], ["decision", "y enables; n cancels for this hub; Esc defers; until then ask"]], columns, now).flat());
-  else if (s.help) lines.push(...keyTable(columns));
+  else if (s.help) lines.push(...keyTable(columns, !!s.petEnabled || !!s.petChoices?.length, !!s.petChoices?.length));
   else if (s.detail !== undefined || (s.requestDetail && permission)) {
     const detail = s.detail !== undefined ? detailLines(s.detail, columns, now) : fieldLines(approvalFields(permission!), columns, now).flat();
     lines.push(...detail.slice(Math.min(s.detailOffset, Math.max(0, detail.length - height))));
@@ -702,5 +788,5 @@ export function renderConsoleLines(s: ConsoleState, columns: number, rows = 24,
     }
   }
   const body = lines.slice(0, height); while (body.length < height) body.push([]);
-  return [header(s, columns), rule, ...body, rule, ...footer];
+  return [header(s, columns), rule, ...noticeLines, ...body, ...decoratePetFooter(s, columns, rows, now, rule, footer, noticeShown)];
 }

package/src/cli/console.ts

@@ -7,6 +7,11 @@ import { renderTailEvent } from "./tail-render.ts";
 import { syncPermissionDefaults, permissionDefaultText, approvalFrom, initialConsoleState, keyTable, notify, paint, panelRows, permissionText, plural, pruneApprovals, reduceConsole, renderConsoleLines, resolveColor, stateTone, streamTokens, wrapStreamTokens, terminalText, wrap } from "./console-state.ts";
 import type { ConsoleEffect, ConsoleEvent, Detail, Tone } from "./console-state.ts";
 import type { BusEvent } from "../hub/bus.ts";
+import { consoleNeeds, attentionFacts } from "./attention.ts";
+import { loadPetConfig } from "./pet-config.ts";
+import { CHARACTER_IDS, petGlyphs, petSize } from "../pet/frame.ts";
+import { activeNotice, consoleFooterRows } from "./console-state.ts";
+import { characterAttentionLine } from "./attention.ts";
 
 export interface ConsoleTerminal {
   columns: number; rows: number; isTTY: boolean; isRaw?: boolean;
@@ -22,6 +27,7 @@ export interface ConsoleOptions {
   cwd: string; stateDir: string; panels?: boolean; columns?: number; rows?: number;
   terminal?: ConsoleTerminal;
   color?: boolean;
+  noPet?: boolean;
   /** Injected command runner must use argv, closed stdin, and return a cancellation handle. */
   runCommand?: (args: string[], output: (text: string) => void, done: () => void, columns?: number) => (() => void);
   pollMs?: number;
@@ -67,6 +73,11 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
   const { client } = options; const terminal = options.terminal ?? nativeTerminal();
   const color = options.color ?? resolveColor(undefined, { isTTY: terminal.isTTY, TERM: process.env.TERM, NO_COLOR: process.env.NO_COLOR }) === true;
   let state = initialConsoleState(!!options.panels); state.project = basename(options.cwd);
+  const pet = loadPetConfig(options.cwd);
+  state.petEnabled = pet.enabled && !options.noPet; state.petBlink = pet.blink;
+  state.petChoices = CHARACTER_IDS; state.petCharacter = pet.character ?? "stai";
+  state.petSize = pet.size; state.petGlyphs = petGlyphs(pet.glyphs);
+  let lastAct = 0; let lastBell = -Infinity;
   let columns = options.columns ?? terminal.columns; let rows = options.rows ?? terminal.rows;
   let active = true; let inAlternate = false; let plain = !terminal.isTTY || columns < 80 || rows < 24;
   let polling = false; let childRunning = false; let cancelChild: (() => void) | undefined;
@@ -74,6 +85,8 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
   const removers: (() => void)[] = []; const timers: ReturnType<typeof setInterval>[] = [];
   let resolveDone: () => void = () => {}; const done = new Promise<void>(resolve => { resolveDone = resolve; });
   let pendingStream: ConsoleEvent[] = []; let droppedStream = 0;
+  let priorStreamFooterStart: number | undefined;
+  let lastExpandedNotice = "";
   const notice = (text: string) => notify(state, text, Date.now());
   const safeWrite = (text: string) => terminal.write(paint([{ text }], color));
   const streamLines = (event: ConsoleEvent) => terminalText(event.text).replace(/\t/g, " ").split("\n").flatMap((text, index) => {
@@ -82,7 +95,7 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
     return index === 0 ? wrapStreamTokens(text, columns, event.tone, event.kind) : wrap(text, columns).map(line => [{ text: line }]);
   });
   const writeStream = (event: ConsoleEvent) => {
-    terminal.write(`\x1b[${rows - 4};1H`); // the scroll region ends above the rule and the three footer lines
+    terminal.write(`\x1b[${rows - consoleFooterRows(state, columns, rows)};1H`); // the scroll region ends above the rule and the three footer lines
     for (const line of streamLines(event)) { terminal.write(paint(line, color)); terminal.write("\r\n"); }
   };
   /** `record: false` is for the console's own prints (the key table, a request viewed again): not events, so not in Events. */
@@ -97,15 +110,34 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
     else { pendingStream.push(event); if (pendingStream.length > 1000) { pendingStream.shift(); droppedStream++; } }
   };
   const draw = () => {
-    if (!active || plain) return;
+    if (!active) return;
+    if (state.petEnabled) {
+      const attention = consoleNeeds(state, Date.now());
+      if (plain && attention.act !== lastAct) safeWrite(characterAttentionLine(attention, state.petCharacter) + "\n");
+      if (pet.bell && !lastAct && attention.act && attention.items.some(item => item.level === "act" && item.kind !== "message") && Date.now() - lastBell >= 60000) { terminal.write("\x07"); lastBell = Date.now(); }
+      lastAct = attention.act;
+    }
+    if (plain) return;
+    const returningToStream = state.mode === "stream" && inAlternate;
     if (state.mode === "panels" && !inAlternate) { terminal.write("\x1b[r\x1b[?1049h\x1b[2J"); inAlternate = true; }
     else if (state.mode === "stream" && inAlternate) {
-      terminal.write(`\x1b[?1049l\x1b[1;${rows - 4}r`); inAlternate = false;
+      terminal.write(`\x1b[?1049l\x1b[1;${rows - consoleFooterRows(state, columns, rows)}r`); inAlternate = false;
+    }
+    const footerStart = rows - consoleFooterRows(state, columns, rows) + 1;
+    if (state.mode === "stream" && priorStreamFooterStart !== undefined && priorStreamFooterStart < footerStart) {
+      for (let row = priorStreamFooterStart; row < footerStart; row++) terminal.write(`\x1b[${row};1H\x1b[2K`);
+    }
+    if (state.mode === "stream") priorStreamFooterStart = footerStart;
+    terminal.write(state.mode === "stream" ? `\x1b[1;${rows - consoleFooterRows(state, columns, rows)}r` : "\x1b[r");
+    if (returningToStream) {
       if (droppedStream) writeStream({ text: `${plural(droppedStream, "older panel-mode event")} omitted from console memory; inspect hub.log for the full stream.` });
       for (const event of pendingStream) writeStream(event);
       pendingStream = []; droppedStream = 0;
     }
-    terminal.write(state.mode === "stream" ? `\x1b[1;${rows - 4}r` : "\x1b[r");
+    if (state.mode === "stream" && state.petEnabled && petSize(state.petSize, columns, rows) !== "line" && activeNotice(state)) {
+      const key = JSON.stringify([state.noticeAt, state.notice]);
+      if (key !== lastExpandedNotice) { lastExpandedNotice = key; stream({ text: `Notice: ${state.notice}`, kind: "notice", tone: state.noticeTone ?? "failure" }, false); }
+    }
     const lines = renderConsoleLines(state, columns, rows);
     const start = rows - lines.length + 1;
     for (const [index, line] of lines.entries()) { terminal.write(`\x1b[${start + index};1H\x1b[2K`); terminal.write(paint(line, color)); }
@@ -136,7 +168,12 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
       if (!active) return;
       const [status, budget, tasks, queue, ready] = replies;
       if (status.status?.tasks && status.ok !== false) state.taskCounts = status.status.tasks;
-      if (status.status?.peers) state.peers = status.status.peers;
+      if (status.status?.peers) state.peers = Object.fromEntries(Object.entries(status.status.peers).map(([peer, value]) => [peer, { ...(value as object), ...status.status.roleInfo?.[peer] }]));
+      if (status.status && status.ok !== false) {
+        state.attentionFacts = attentionFacts(status.status.attentionItems);
+        state.storageBlocked = !!status.status.deliveryError;
+        state.recoveryNeed = status.status.recovery ? { id: status.status.recovery.operationId, running: true } : undefined;
+      }
       if (syncPermissionDefaults(state, status.status?.permissionDefaults) && state.confirm?.type === "permission_default") stream({ text: permissionDefaultText(state.confirm), kind: "permission_default", peer: state.confirm.peer, tone: "attention" });
       if (budget.budget) state.budget = budget.budget;
       if (tasks?.ok) { const parsed = JSON.parse(tasks.text); if (Array.isArray(parsed)) {
@@ -178,7 +215,7 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
       if (!action.option) stream({ text: `  ! denial requested for permission ${action.id}`, kind: "permission", tone: "failure" });
       return;
     }
-    if (action.type === "keys") return stream({ text: keyTable(columns).map(line => paint(line, false)).join("\n"), kind: "console" }, false);
+    if (action.type === "keys") return stream({ text: keyTable(columns, !!state.petEnabled || !!state.petChoices?.length, !!state.petChoices?.length).map(line => paint(line, false)).join("\n"), kind: "console" }, false);
     if (action.type === "print") return stream({ text: action.text, kind: action.kind, ...(action.tone ? { tone: action.tone } : {}) }, false);
     if (action.type === "show") {
       const result = await client.request(action.panel === 3 ? { t: "task", op: "task_show", args: { id: action.id } } : { t: "queue", op: "show", id: action.id }, 3000);
@@ -201,6 +238,7 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
   const handle = (key: string) => {
     if (!active) return;
     const result = reduceConsole(state, key); state = result.state;
+    state.attentionMessages = []; state.attentionSelection = key === "n" ? state.attentionSelection : undefined;
     if (state.mode === "panels" && (plain || columns < 80 || rows < 24)) { state.mode = "stream"; notice("panels need at least 80x24"); }
     for (const action of result.effects) void effect(action).catch(error => stop(`Console error: ${String(error.message)}`));
     draw();
@@ -209,7 +247,10 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
   client.onPush = msg => {
     if (!active) return;
     try {
-      if (msg.t === "event") stream({ text: renderTailEvent(msg.e), peer: msg.e.peer ?? msg.e.env?.from, kind: msg.e.env?.kind ?? msg.e.t, tone: eventTone(msg.e) });
+      if (msg.t === "event") {
+        if (state.petEnabled && msg.e.t === "envelope" && !msg.e.dropped && msg.e.env.to?.includes("user")) state.attentionMessages = [...(state.attentionMessages ?? []), { id: msg.e.env.id, peer: msg.e.env.from, important: msg.e.env.priority === "important", since: msg.e.env.ts }].slice(-1000);
+        stream({ text: renderTailEvent(msg.e), peer: msg.e.peer ?? msg.e.env?.from, kind: msg.e.env?.kind ?? msg.e.t, tone: eventTone(msg.e) });
+      }
       else if (msg.t === "context") stream({ text: `  ${msg.peer}: ${contextLine(msg.reading, at => new Date(at).toLocaleTimeString())}`, peer: msg.peer, kind: "context" });
       else if (msg.t === "notice") stream({ text: `  * ${msg.line}`, kind: "notice" });
       else if (msg.t === "permission") {
@@ -230,6 +271,10 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
   };
   client.onClose = (_code, reason) => stop(`Hub connection closed${reason ? `: ${reason}` : ""}`);
   try {
+    if (state.petEnabled && pet.notice) {
+      if (state.mode === "panels" && !plain) notify(state, pet.notice, Date.now(), "attention");
+      else stream({ text: pet.notice, kind: "attention", tone: "attention" }, false);
+    }
     if (plain) { state.mode = "stream"; safeWrite("Console panels need a terminal of at least 80x24; showing the plain stream.\n"); }
     if (terminal.isTTY) {
       terminal.raw(true);
@@ -240,7 +285,8 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
         if (Array.from(text).length > 1 && !["\x1b[A", "\x1b[B", "\x1b[C", "\x1b[D"].includes(text)) {
           if (/^(?:\x1b\[[ABCD])+$/.test(text)) { for (const key of text.match(/\x1b\[[ABCD]/g)!) handle(key); }
           else {
-            if (state.help && state.mode === "panels") return;
+            state.attentionMessages = []; state.attentionSelection = undefined;
+            if (state.help && state.mode === "panels") { draw(); return; }
             if (state.confirm?.type === "permission_default") { draw(); return; }
             state.confirm = undefined; state.optionChoice = undefined; state.editing = true;
             state.input += terminalText(text.replace(/\x1b\[20[01]~/g, "")).replace(/\n/g, " "); draw();

package/src/cli/facts-hook.ts

@@ -3,8 +3,9 @@
 // PreToolUse preserves facts additionalContext and adds permission decisions; other phases observe only.
 // A failed or timed-out hub decides nothing, leaving Claude's native permission rules in effect.
 import { relative, resolve, isAbsolute } from "node:path";
+import { matchesPolicy } from "../hub/path-policy.ts";
 import { realPath } from "../hub/project.ts";
-import { isAgentConfigPath, isPermissionMode, hardLinked, isHubWritePath } from "../hub/permission-mode.ts";
+import { isAgentConfigPath, isInstructionPath, isPermissionMode, hardLinked, isHubWritePath } from "../hub/permission-mode.ts";
 import { ControlClient } from "../hub/control-client.ts";
 
 /** A library call may target another hub; only the managed command hook inherits that target's native identity. */
@@ -14,7 +15,7 @@ export function nativeHookIdentity(stateDir: string, peer: string, env: NodeJS.P
 }
 
 /** Only resolving project paths outside the hub/native configuration directories receive a file grant. */
-export function projectFileTool(tool: unknown, input: unknown, projectRoot: unknown): boolean {
+export function projectFileTool(tool: unknown, input: unknown, projectRoot: unknown, protectInstructions = false, readOnly: string[] = []): boolean {
   if (typeof projectRoot !== "string" || !isAbsolute(projectRoot) || !input || typeof input !== "object" || Array.isArray(input)) return false;
   const args = input as Record<string, unknown>;
   const key = ["Read", "Edit", "Write", "MultiEdit"].includes(String(tool)) ? "file_path" : tool === "NotebookEdit" ? "notebook_path" : ["LS", "Glob", "Grep"].includes(String(tool)) ? "path" : undefined;
@@ -24,7 +25,8 @@ export function projectFileTool(tool: unknown, input: unknown, projectRoot: unkn
   if (!optional && args[key] === undefined) return false;
   try {
     const root = realPath(projectRoot);
-    const protectedPath = (path: string) => isAgentConfigPath(path) || isHubWritePath(path);
+    const mutates = ["Edit", "Write", "MultiEdit", "NotebookEdit"].includes(String(tool));
+    const protectedPath = (path: string) => isAgentConfigPath(path) || isHubWritePath(path) || (protectInstructions && mutates && isInstructionPath(path));
     const safe = (path: string) => {
       const requested = resolve(root, path), lexical = relative(root, requested);
       if (protectedPath(lexical)) return false;
@@ -34,6 +36,7 @@ export function projectFileTool(tool: unknown, input: unknown, projectRoot: unkn
     };
     const target = typeof args[key] === "string" ? args[key] as string : root;
     if (target.split(/[\\/]/).includes("..") || !safe(target)) return false;
+    if (mutates && matchesPolicy(root, target, readOnly, true)) return false;
     if (tool === "Grep" && args.glob !== undefined) {
       if (typeof args.glob !== "string" || !args.glob || args.glob.split(/[\\/]/).includes("..") || protectedPath(args.glob)) return false;
       if (/[?*[{]/.test(args.glob) || !safe(resolve(root, target, args.glob))) return false;
@@ -48,6 +51,11 @@ export function projectFileTool(tool: unknown, input: unknown, projectRoot: unkn
   } catch { return false; }
 }
 
+/** Only a usable managed scoped-write grant may evaluate filesystem policy. */
+export function scopedWriteBlocked(phase: string, permission: unknown, tool: unknown, evaluate: () => boolean): boolean {
+  return phase === "pre" && permission === "ask-when-needed" && ["Edit", "Write", "MultiEdit", "NotebookEdit"].includes(String(tool)) && !evaluate();
+}
+
 /** The hook's stdout for one Claude Code hook input, or undefined for none. */
 export async function factsHook(stdin: string, stateDir: string, peer: string, timeoutMs = 2000): Promise<string | undefined> {
   const input = JSON.parse(stdin) as { hook_event_name?: unknown; tool_name?: unknown; tool_input?: unknown; tool_use_id?: unknown; session_id?: unknown; transcript_path?: unknown };
@@ -67,7 +75,7 @@ export async function factsHook(stdin: string, stateDir: string, peer: string, t
     }, timeoutMs);
     if (phase !== "pre" || !res?.ok) return undefined;
     const permission = isPermissionMode(res.permission) ? res.permission : "ask";
-    const fileTool = projectFileTool(input.tool_name, input.tool_input, res.projectRoot);
+    const fileTool = projectFileTool(input.tool_name, input.tool_input, res.projectRoot, res.protectInstructionFiles === true);
     const allow = input.hook_event_name === "PreToolUse" && (permission === "never-ask" || permission === "ask-when-needed" && fileTool);
     const text = typeof res.text === "string" && res.text ? res.text : undefined;
     if (!allow && !text) return undefined;