@staix/agent-hub 0.12.37 → 0.12.39

package/src/cli/agy-mcp.ts

@@ -0,0 +1,370 @@
+import type { Stats } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { closeSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { hubGitSync } from "../hub/git.ts";
+import { realPath } from "../hub/project.ts";
+
+export interface AgyMcpOptions {
+  projectRoot: string;
+  stateDir: string;
+  serverJs: string;
+  hookScript: string;
+  instanceId: string;
+  launchId: string;
+  peer?: string;
+}
+
+const PLUGIN_DIR = ".agents/plugins/agent-hub";
+const PLUGIN_KEY = "agent-hub";
+const MANIFEST_FILE = `${PLUGIN_DIR}/plugin.json`;
+const MCP_FILE = `${PLUGIN_DIR}/mcp_config.json`;
+const HOOKS_FILE = `${PLUGIN_DIR}/hooks.json`;
+const FILES = [MANIFEST_FILE, MCP_FILE, HOOKS_FILE] as const;
+export const AGY_PLUGIN_FILES = FILES;
+const EVENTS = ["SessionStart", "PreInvocation", "PostInvocation", "PreToolUse", "PostToolUse", "Stop"] as const;
+const MANAGED_DESCRIPTION = "Managed by ahub agy launcher.";
+const MAX_CONFIG_BYTES = 256 * 1024;
+type JsonObject = Record<string, any>;
+type Target = { path: string; relative: typeof FILES[number]; current?: Buffer; stat?: Stats; next: Buffer; changed: boolean };
+type DirectoryIdentity = { path: string; stat: Stats };
+type Plan = { file: string; tracked: boolean; changed: boolean; action: string; root: string; pluginDir: string; canonicalRoot: string; canonicalPluginDir?: string; directories?: DirectoryIdentity[]; targets: Target[] };
+
+function object(value: unknown): value is JsonObject { return !!value && typeof value === "object" && !Array.isArray(value); }
+function jsonFile(value: unknown, name: string): JsonObject {
+  if (!object(value)) throw new Error(`${name} must be a JSON object`);
+  return value;
+}
+function parseJson(bytes: Buffer, name: string): JsonObject {
+  try { return jsonFile(JSON.parse(bytes.toString("utf8")), name); }
+  catch (error) { if (error instanceof SyntaxError) throw new Error(`${name} is invalid JSON`); throw error; }
+}
+function shellQuote(value: string): string { return `'${value.replace(/'/g, `'\\''`)}'`; }
+function shellUnquote(value: string): string | undefined {
+  if (!value.startsWith("'") || !value.endsWith("'")) return undefined;
+  let out = "";
+  for (let index = 1; index < value.length - 1;) {
+    if (value.startsWith("'\\''", index)) { out += "'"; index += 4; }
+    else if (value[index] === "'") return undefined;
+    else out += value[index++];
+  }
+  return out;
+}
+
+function validateOptions(options: AgyMcpOptions) {
+  const peer = options.peer ?? "agy";
+  if (!/^[a-z][a-z0-9-]{0,31}$/.test(peer)) throw new Error("agy peer id is invalid");
+  for (const [name, value] of Object.entries({ projectRoot: options.projectRoot, stateDir: options.stateDir, serverJs: options.serverJs, hookScript: options.hookScript })) {
+    if (typeof value !== "string" || !isAbsolute(value) || value.length > 4096 || /[\u0000-\u001f\u007f]/.test(value)) throw new Error(`${name} must be an absolute control-free path`);
+  }
+  for (const [name, value] of Object.entries({ instanceId: options.instanceId, launchId: options.launchId })) {
+    if (typeof value !== "string" || !/^[A-Za-z0-9._:-]{1,128}$/.test(value)) throw new Error(`${name} is invalid`);
+  }
+  const root = resolve(options.projectRoot);
+  return { root, peer };
+}
+
+function safeDirectory(path: string): Stats | undefined {
+  const stat = lstatSync(path, { throwIfNoEntry: false });
+  if (stat && (!stat.isDirectory() || stat.isSymbolicLink())) throw new Error(`${path} must be a project directory, not a link`);
+  return stat;
+}
+
+function safeFile(path: string): { stat: Stats; bytes: Buffer } | undefined {
+  const stat = lstatSync(path, { throwIfNoEntry: false });
+  if (!stat) return undefined;
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.size > MAX_CONFIG_BYTES) throw new Error(`${path} must be a bounded regular file, not a link`);
+  const bytes = readFileSync(path);
+  if (bytes.length > MAX_CONFIG_BYTES) throw new Error(`${path} exceeds the configuration size limit`);
+  return { stat, bytes };
+}
+
+function pluginDirectories(root: string): DirectoryIdentity[] {
+  const directories: DirectoryIdentity[] = [];
+  for (const relative of [".", ".agents", ".agents/plugins", PLUGIN_DIR]) {
+    const path = relative === "." ? root : join(root, relative);
+    const stat = safeDirectory(path);
+    if (!stat) throw new Error(`${path} must be an existing project directory`);
+    directories.push({ path, stat });
+  }
+  return directories;
+}
+
+function verifyPluginDirectory(plan: Pick<Plan, "root" | "pluginDir" | "canonicalRoot" | "canonicalPluginDir" | "directories">, target: string): void {
+  if (!plan.canonicalPluginDir || !plan.directories) throw new Error("managed agy plugin directory identity is unavailable");
+  if (realPath(plan.root) !== plan.canonicalRoot || realPath(plan.pluginDir) !== plan.canonicalPluginDir || plan.canonicalPluginDir !== join(plan.canonicalRoot, PLUGIN_DIR)) {
+    throw new Error("managed agy plugin path changed; inspect it before writing");
+  }
+  for (const expected of plan.directories) {
+    const current = safeDirectory(expected.path);
+    if (!current || current.dev !== expected.stat.dev || current.ino !== expected.stat.ino) throw new Error("managed agy plugin directory changed; inspect it before writing");
+  }
+  if (!FILES.some(file => join(plan.root, file) === target)) {
+    throw new Error("atomic write target is outside the managed agy plugin files");
+  }
+}
+
+function hookCommand(phase: typeof EVENTS[number], options: AgyMcpOptions, peer: string): string {
+  return `AGENTHUB_HOOK_EVENT='${phase}' AGENTHUB_INSTANCE_ID='${options.instanceId}' AGENTHUB_LAUNCH_ID='${options.launchId}' AGENTHUB_HOOK_PURPOSE='facts' AGENTHUB_PEER_ID=${shellQuote(peer)} AGENTHUB_STATE_DIR=${shellQuote(options.stateDir)} AGENTHUB_PROJECT_DIR=${shellQuote(resolve(options.projectRoot))} bun ${shellQuote(options.hookScript)}`;
+}
+
+function desired(options: AgyMcpOptions, root: string, peer: string): Record<typeof FILES[number], JsonObject> {
+  const events: JsonObject = {};
+  for (const phase of EVENTS) {
+    if (phase === "PostInvocation") { events[phase] = []; continue; }
+    const command = { type: "command", command: hookCommand(phase, options, peer), timeout: 5 };
+    events[phase] = phase === "PreToolUse" || phase === "PostToolUse"
+      ? [{ matcher: ".*", hooks: [command] }]
+      : [command];
+  }
+  return {
+    [MANIFEST_FILE]: { name: PLUGIN_KEY, description: MANAGED_DESCRIPTION },
+    [MCP_FILE]: { mcpServers: { [PLUGIN_KEY]: { command: "bun", args: ["run", options.serverJs], env: { AGENTHUB_PEER_ID: peer, AGENTHUB_STATE_DIR: options.stateDir, AGENTHUB_PROJECT_DIR: root } } } },
+    [HOOKS_FILE]: { [PLUGIN_KEY]: events },
+  };
+}
+
+function parseManagedHookCommand(command: unknown, phase: typeof EVENTS[number], options: AgyMcpOptions, peer: string): { instanceId: string; launchId: string } | undefined {
+  if (typeof command !== "string") return undefined;
+  const prefix = `AGENTHUB_HOOK_EVENT='${phase}' AGENTHUB_INSTANCE_ID='`;
+  const middle = `' AGENTHUB_LAUNCH_ID='`;
+  const suffix = `' AGENTHUB_HOOK_PURPOSE='facts' AGENTHUB_PEER_ID=${shellQuote(peer)} AGENTHUB_STATE_DIR=${shellQuote(options.stateDir)} AGENTHUB_PROJECT_DIR=${shellQuote(resolve(options.projectRoot))} bun `;
+  if (!command.startsWith(prefix)) return undefined;
+  const rest = command.slice(prefix.length);
+  const launchSplit = rest.indexOf(middle);
+  if (launchSplit < 1) return undefined;
+  const instanceId = rest.slice(0, launchSplit);
+  const afterInstance = rest.slice(launchSplit + middle.length);
+  const pathSplit = afterInstance.indexOf(suffix);
+  if (pathSplit < 1) return undefined;
+  const launchId = afterInstance.slice(0, pathSplit);
+  const hookScript = shellUnquote(afterInstance.slice(pathSplit + suffix.length));
+  if (!/^[A-Za-z0-9._:-]{1,128}$/.test(instanceId) || !/^[A-Za-z0-9._:-]{1,128}$/.test(launchId) || !hookScript || !isAbsolute(hookScript) || !hookScript.endsWith("/src/cli/facts-hook.ts")) return undefined;
+  return { instanceId, launchId };
+}
+
+function managedHookLaunch(value: JsonObject, options: AgyMcpOptions, peer: string): { instanceId: string; launchId: string } | undefined {
+  if (Object.keys(value).length !== 1 || !Object.hasOwn(value, PLUGIN_KEY)) return undefined;
+  const events = value[PLUGIN_KEY];
+  if (!object(events) || Object.keys(events).length !== EVENTS.length || EVENTS.some(phase => !Object.hasOwn(events, phase))) return undefined;
+  let identity: { instanceId: string; launchId: string } | undefined;
+  for (const phase of EVENTS) {
+    const rows = events[phase];
+    if (phase === "PostInvocation") { if (!Array.isArray(rows) || rows.length !== 0) return undefined; continue; }
+    if (!Array.isArray(rows) || rows.length !== 1 || !object(rows[0])) return undefined;
+    let command: unknown;
+    if (phase === "PreToolUse" || phase === "PostToolUse") {
+      const row = rows[0];
+      if (Object.keys(row).sort().join(",") !== "hooks,matcher" || row.matcher !== ".*" || !Array.isArray(row.hooks) || row.hooks.length !== 1 || !object(row.hooks[0])) return undefined;
+      command = row.hooks[0];
+    } else command = rows[0];
+    if (!object(command) || Object.keys(command).sort().join(",") !== "command,timeout,type" || command.type !== "command" || command.timeout !== 5) return undefined;
+    const found = parseManagedHookCommand(command.command, phase, options, peer);
+    if (!found || (identity && (identity.instanceId !== found.instanceId || identity.launchId !== found.launchId))) return undefined;
+    identity = found;
+  }
+  return identity;
+}
+
+function nextDocuments(current: Record<typeof FILES[number], JsonObject | undefined>, wanted: Record<typeof FILES[number], JsonObject>): Record<typeof FILES[number], JsonObject> {
+  const nextMcp = current[MCP_FILE] ? { ...current[MCP_FILE] } : {};
+  const currentServers = nextMcp.mcpServers;
+  const servers = currentServers === undefined ? {} : currentServers;
+  if (!object(servers)) throw new Error(`${MCP_FILE} mcpServers must be an object`);
+  nextMcp.mcpServers = { ...servers, [PLUGIN_KEY]: wanted[MCP_FILE].mcpServers[PLUGIN_KEY] };
+  return { [MANIFEST_FILE]: wanted[MANIFEST_FILE], [MCP_FILE]: nextMcp, [HOOKS_FILE]: wanted[HOOKS_FILE] };
+}
+
+function internalPlan(options: AgyMcpOptions): Plan {
+  const { root, peer } = validateOptions(options);
+  const rootStat = safeDirectory(root);
+  if (!rootStat) throw new Error("project root must be an existing directory");
+  const canonicalRoot = realPath(root);
+  const pluginDir = join(root, PLUGIN_DIR);
+  let parentsPresent = true;
+  for (const relative of [".agents", ".agents/plugins", PLUGIN_DIR]) {
+    if (!parentsPresent) break;
+    parentsPresent = !!safeDirectory(join(root, relative));
+  }
+  let directories: DirectoryIdentity[] | undefined;
+  let canonicalPluginDir: string | undefined;
+  if (parentsPresent) {
+    directories = pluginDirectories(root);
+    canonicalPluginDir = realPath(pluginDir);
+    if (canonicalPluginDir !== join(canonicalRoot, PLUGIN_DIR)) throw new Error("managed agy plugin path traverses a symlink");
+  }
+  const snapshots = Object.fromEntries(FILES.map(relative => {
+    const path = join(root, relative);
+    const found = parentsPresent ? safeFile(path) : undefined;
+    return [relative, found];
+  })) as Record<typeof FILES[number], { stat: Stats; bytes: Buffer } | undefined>;
+  const current = {} as Record<typeof FILES[number], JsonObject | undefined>;
+  for (const relative of FILES) {
+    const found = snapshots[relative];
+    current[relative] = found ? parseJson(found.bytes, relative) : undefined;
+  }
+
+  const manifest = current[MANIFEST_FILE];
+  if (manifest && (Object.keys(manifest).sort().join(",") !== "description,name" || manifest.name !== PLUGIN_KEY || manifest.description !== MANAGED_DESCRIPTION)) {
+    throw new Error(`${MANIFEST_FILE} is a foreign agent-hub plugin manifest; it was not changed`);
+  }
+  const mcp = current[MCP_FILE];
+  if (mcp) {
+    if (Object.hasOwn(mcp, "mcpServers") && !object(mcp.mcpServers)) throw new Error(`${MCP_FILE} mcpServers must be an object`);
+    const entry = mcp.mcpServers?.[PLUGIN_KEY];
+    if (entry !== undefined && (!object(entry) || Object.keys(entry).sort().join(",") !== "args,command,env" || entry.command !== "bun" || !Array.isArray(entry.args) || entry.args.length !== 2 || entry.args[0] !== "run" || typeof entry.args[1] !== "string" || !isAbsolute(entry.args[1]) || !object(entry.env) || Object.keys(entry.env).sort().join(",") !== "AGENTHUB_PEER_ID,AGENTHUB_PROJECT_DIR,AGENTHUB_STATE_DIR" || entry.env.AGENTHUB_PEER_ID !== peer || entry.env.AGENTHUB_PROJECT_DIR !== root || entry.env.AGENTHUB_STATE_DIR !== options.stateDir)) {
+      throw new Error(`${MCP_FILE} agent-hub is a foreign MCP entry; it was not changed`);
+    }
+  }
+  const hooks = current[HOOKS_FILE];
+  const oldLaunch = hooks ? managedHookLaunch(hooks, options, peer) : undefined;
+  if (hooks && !oldLaunch) throw new Error(`${HOOKS_FILE} agent-hub is a foreign hooks entry; it was not changed`);
+
+  const wanted = desired(options, root, peer);
+  const docs = nextDocuments(current, wanted);
+  const targets = FILES.map(relative => {
+    const old = snapshots[relative];
+    const next = Buffer.from(`${JSON.stringify(docs[relative], null, 2)}\n`);
+    return { path: join(root, relative), relative, ...(old ? { current: old.bytes, stat: old.stat } : {}), next, changed: !old || !isDeepStrictEqual(current[relative], docs[relative]) };
+  });
+  const git = hubGitSync(["ls-files", "--", ...FILES], { cwd: root, encoding: "utf8", timeout: 3000 });
+  const tracked = git.status === 0 && !!git.stdout.trim();
+  const changed = targets.some(target => target.changed);
+  return { file: pluginDir, tracked, changed, action: changed ? "create or update the managed agent-hub plugin" : "keep the managed agent-hub plugin", root, pluginDir, canonicalRoot, ...(canonicalPluginDir ? { canonicalPluginDir } : {}), ...(directories ? { directories } : {}), targets };
+}
+
+/** Preview the native plugin's three project-scoped files without writing or exposing foreign contents. */
+export function agyMcpPlan(options: AgyMcpOptions): { file: string; tracked: boolean; changed: boolean; action: string } {
+  const { file, tracked, changed, action } = internalPlan(options);
+  return { file, tracked, changed, action };
+}
+
+function identityMatches(path: string, before?: Stats): boolean {
+  const now = lstatSync(path, { throwIfNoEntry: false });
+  return before ? !!now && now.dev === before.dev && now.ino === before.ino : !now;
+}
+
+function atomicWrite(path: string, bytes: Buffer, expected: Stats | undefined, plan: Plan): { dev: number; ino: number } {
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  let fd: number | undefined;
+  let tempIdentity: { dev: number; ino: number } | undefined;
+  try {
+    verifyPluginDirectory(plan, path);
+    fd = openSync(temporary, "wx", 0o600);
+    const tempStat = fstatSync(fd);
+    tempIdentity = { dev: tempStat.dev, ino: tempStat.ino };
+    writeFileSync(fd, bytes);
+    closeSync(fd); fd = undefined;
+    verifyPluginDirectory(plan, path);
+    if (!identityMatches(path, expected)) throw new Error(`${path} changed while the managed plugin was being written`);
+    renameSync(temporary, path);
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) throw new Error(`${path} changed while the managed plugin was written`);
+    return { dev: stat.dev, ino: stat.ino };
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+    try {
+      const current = lstatSync(temporary, { throwIfNoEntry: false });
+      if (current && tempIdentity && current.dev === tempIdentity.dev && current.ino === tempIdentity.ino) unlinkSync(temporary);
+    } catch { /* A temp path that no longer names our file is not ours to remove. */ }
+  }
+}
+
+function rollback(plan: Plan, written: { target: Target; own: { dev: number; ino: number } }[], createdDirs: { path: string; dev: number; ino: number }[]): void {
+  for (const { target, own } of written.reverse()) {
+    try {
+      const now = lstatSync(target.path, { throwIfNoEntry: false });
+      if (!now || now.dev !== own.dev || now.ino !== own.ino) continue;
+      if (target.current) atomicWrite(target.path, target.current, now, plan);
+      else unlinkSync(target.path);
+    } catch { /* Never replace a path whose ownership changed during rollback. */ }
+  }
+  for (const { path, dev, ino } of createdDirs.reverse()) {
+    try { const now = lstatSync(path); if (now.isDirectory() && !now.isSymbolicLink() && now.dev === dev && now.ino === ino) rmdirSync(path); }
+    catch { /* Keep a directory that is no longer empty or no longer ours. */ }
+  }
+}
+
+export function ensureAgyMcp(options: AgyMcpOptions): { changed: boolean; tracked: boolean } {
+  const plan = internalPlan(options);
+  if (!plan.changed) return { changed: false, tracked: plan.tracked };
+  const createdDirs: { path: string; dev: number; ino: number }[] = [];
+  const written: { target: Target; own: { dev: number; ino: number } }[] = [];
+  try {
+    for (const relative of [".agents", ".agents/plugins", PLUGIN_DIR]) {
+      const path = join(plan.root, relative);
+      const prior = safeDirectory(path);
+      if (prior) continue;
+      mkdirSync(path, { mode: 0o700 });
+      const stat = safeDirectory(path)!;
+      createdDirs.push({ path, dev: stat.dev, ino: stat.ino });
+    }
+    plan.directories = pluginDirectories(plan.root);
+    plan.canonicalPluginDir = realPath(plan.pluginDir);
+    if (plan.canonicalRoot !== realPath(plan.root) || plan.canonicalPluginDir !== join(plan.canonicalRoot, PLUGIN_DIR)) throw new Error("managed agy plugin path changed; inspect it before writing");
+    for (const target of plan.targets) {
+      if (!target.changed) continue;
+      if (!identityMatches(target.path, target.stat)) throw new Error(`${target.path} changed while the managed plugin was being prepared`);
+      const own = atomicWrite(target.path, target.next, target.stat, plan);
+      written.push({ target, own });
+    }
+  } catch (error) {
+    rollback(plan, written, createdDirs);
+    throw error;
+  }
+  return { changed: true, tracked: plan.tracked };
+}
+
+export function agyMcpReady(options: AgyMcpOptions): boolean {
+  return !internalPlan(options).changed;
+}
+
+export function cleanupAgyMcp(options: AgyMcpOptions): void {
+  const plan = internalPlan(options);
+  const present = plan.targets.filter(target => target.current !== undefined);
+  if (!present.length) return;
+  if (present.length !== FILES.length) throw new Error("managed agy plugin is incomplete; inspect it before cleanup");
+  const currentHooks = parseJson(readFileSync(join(plan.root, HOOKS_FILE)), HOOKS_FILE);
+  const launch = managedHookLaunch(currentHooks, options, options.peer ?? "agy");
+  if (!launch || launch.instanceId !== options.instanceId || launch.launchId !== options.launchId) return;
+  // A stale cleanup never removes files a newer config update has replaced.
+  if (plan.changed) return;
+  const deleted: { path: string; bytes: Buffer; own?: { dev: number; ino: number } }[] = [];
+  try {
+    for (const target of plan.targets) {
+      const stat = lstatSync(target.path);
+      if (!target.stat || stat.dev !== target.stat.dev || stat.ino !== target.stat.ino) throw new Error(`${target.path} changed before agy plugin cleanup`);
+    }
+    for (const target of plan.targets) {
+      if (!identityMatches(target.path, target.stat)) throw new Error(`${target.path} changed before agy plugin cleanup`);
+      if (target.relative === MCP_FILE) {
+        const currentMcp = parseJson(target.current!, MCP_FILE);
+        const servers = { ...currentMcp.mcpServers };
+        delete servers[PLUGIN_KEY];
+        const nextMcp = { ...currentMcp, mcpServers: servers };
+        const retain = Object.keys(servers).length > 0 || Object.keys(currentMcp).some(key => key !== "mcpServers");
+        if (retain) {
+          const own = atomicWrite(target.path, Buffer.from(`${JSON.stringify(nextMcp, null, 2)}\n`), target.stat, plan);
+          deleted.push({ path: target.path, bytes: target.current!, own });
+        } else {
+          unlinkSync(target.path);
+          deleted.push({ path: target.path, bytes: target.current! });
+        }
+      } else {
+        unlinkSync(target.path);
+        deleted.push({ path: target.path, bytes: target.current! });
+      }
+    }
+  } catch (error) {
+    for (const item of deleted.reverse()) {
+      try {
+        const current = lstatSync(item.path, { throwIfNoEntry: false });
+        if (item.own) {
+          if (current?.dev === item.own.dev && current.ino === item.own.ino) atomicWrite(item.path, item.bytes, current, plan);
+        } else if (!current) atomicWrite(item.path, item.bytes, undefined, plan);
+      } catch { /* Restore only a path still owned by this cleanup or a path that remains missing. */ }
+    }
+    throw error;
+  }
+}

package/src/cli/console-state.ts

@@ -22,6 +22,7 @@ export interface ConsoleState {
   settingsRows?: SettingRow[]; settingsKnown?: boolean; settingsUndo?: string; settingsProblem?: string;
   settingsEdit?: SettingsEdit; settingsSequence?: number;
   pendingRestart?: { key: string; reason: string }[];
+  retainedConfig?: { key: string; reason: string }[];
   features?: readonly string[];
   /** Older embedding callers omit choices and retain the original STAI/off toggle. */
   petChoices?: readonly CharacterId[]; petCharacter?: CharacterId; petSize?: PetSize; petGlyphs?: "ascii" | "blocks";
@@ -893,6 +894,7 @@ export function renderConsoleLines(s: ConsoleState, columns: number, rows = 24,
     if (p.toolsOnly) summary.push(span(definitionOf(id)?.attach?.pullOnlyForms?.includes("tui") ? ` pull-only, read ${typeof p.lastInboxAt === "number" ? relative(p.lastInboxAt, now) : "never"}` : " tools-only: ahub claude", "attention"));
   }
   if (s.pendingRestart?.length) summary.push(span(`${summary.length ? " | " : ""}restart pending: ${s.pendingRestart.map(row => row.key).join(", ")}`, "attention"));
+  if (s.retainedConfig?.length) summary.push(span(`${summary.length ? " | " : ""}config retained: ${s.retainedConfig.map(row => row.key).join(", ")}; run ahub settings reload`, "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)];
@@ -947,6 +949,10 @@ export function renderConsoleLines(s: ConsoleState, columns: number, rows = 24,
       const info = s.settingsProblem ?? (!s.settingsKnown ? "settings loading..." : row?.restartReason ?? row?.note ?? row?.label ?? "Settings");
       lines.push(...wrap(info, columns).slice(0, 2).map(text => [span(text, s.settingsProblem ? "failure" : "info")]));
       if (s.pendingRestart?.length) lines.push(fitLine([span(`pending restart: ${s.pendingRestart.map(row => `${row.key}: ${row.reason}`).join("; ")}`, "attention")], columns));
+      if (s.retainedConfig?.length) {
+        lines.push(fitLine([span(`config retained: ${s.retainedConfig.map(row => row.key).join(", ")}; run ahub settings reload`, "attention")], columns));
+        for (const pending of s.retainedConfig) lines.push(fitLine([span(`${pending.key}: ${pending.reason}`, "attention")], columns));
+      }
     }
     if (s.panel === 3) {
       const done = progress.total ? Math.floor(progress.counts.approved * 20 / progress.total) : 0;

package/src/cli/console.ts

@@ -196,6 +196,7 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
       captureConsoleSelection(state);
       if (status.status?.tasks && status.ok !== false) state.taskCounts = status.status.tasks;
       if (status.status && status.ok !== false) state.pendingRestart = Array.isArray(status.status.pendingRestart) ? status.status.pendingRestart : [];
+      if (status.status && status.ok !== false) state.retainedConfig = Array.isArray(status.status.retainedConfig) ? status.status.retainedConfig : [];
       if (status.status) state.features = Array.isArray(status.status.features) ? status.status.features : [];
       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) {
@@ -216,6 +217,7 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
           state.settingsRows = settings.rows; state.settingsKnown = true; state.settingsProblem = undefined;
           state.settingsUndo = typeof settings.undo === "string" ? settings.undo : undefined;
           state.pendingRestart = Array.isArray(settings.pendingRestart) ? settings.pendingRestart : [];
+          state.retainedConfig = Array.isArray(settings.retainedConfig) ? settings.retainedConfig : [];
         } else state.settingsProblem = String(settings.error ?? "settings are unavailable");
       }
       reconcileDetail();

package/src/cli/facts-hook.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env bun
+import { definitionOf } from "../adapters/registry.ts";
 // Managed Claude hook transport for turn-free facts, native observations and runtime permissions.
 // 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.
@@ -57,7 +58,19 @@ export function scopedWriteBlocked(phase: string, permission: unknown, tool: unk
 }
 
 /** 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> {
+export async function factsHook(stdin: string, stateDir: string, peer: string, timeoutMs = 2000, nativeEvent?: string): Promise<string | undefined> {
+  if (nativeEvent !== undefined) {
+    if (Buffer.byteLength(stdin, "utf8") > 1024 * 1024) return undefined;
+    const port = definitionOf(peer)?.hooks?.factsHook;
+    const payload: unknown = JSON.parse(stdin);
+    if (!port?.decode(nativeEvent, payload)) return undefined;
+    const hub = await ControlClient.connect(stateDir, { role: "tools", peer }, timeoutMs);
+    try {
+      const reply = await hub.request({ t: "native_facts", event: nativeEvent, payload, ...nativeHookIdentity(stateDir, peer) }, timeoutMs);
+      const output = reply.ok ? port.encode(nativeEvent, typeof reply.text === "string" ? reply.text : undefined) : undefined;
+      return output ? JSON.stringify(output) : undefined;
+    } finally { hub.close(); }
+  }
   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 };
   const phase = ({ SessionStart: "session", UserPromptSubmit: "start", PostToolUse: "post", Stop: "stop" } as Record<string, string>)[String(input.hook_event_name)] ?? "pre";
   const hub = await ControlClient.connect(stateDir, { role: "tools", peer }, timeoutMs);
@@ -88,7 +101,7 @@ export async function factsHook(stdin: string, stateDir: string, peer: string, t
 if (import.meta.main) {
   try {
     const stateDir = process.env.AGENTHUB_STATE_DIR;
-    const out = stateDir ? await factsHook(await Bun.stdin.text(), stateDir, process.env.AGENTHUB_PEER_ID ?? "claude") : undefined;
+    const out = stateDir ? await factsHook(await Bun.stdin.text(), stateDir, process.env.AGENTHUB_PEER_ID ?? "claude", 2000, process.env.AGENTHUB_HOOK_EVENT) : undefined;
     if (out) console.log(out);
   } catch {
     // a hook that fails must not get in the way of the tool call

package/src/cli/init.ts

@@ -5,6 +5,7 @@ import { existsSync, lstatSync, mkdirSync, readFileSync, statSync, unlinkSync, w
 import { join } from "node:path";
 import { hubGitSync } from "../hub/git.ts";
 import { KIMI_MCP_FILE } from "./kimi-mcp.ts";
+import { AGY_PLUGIN_FILES } from "./agy-mcp.ts";
 
 const TEMPLATES = join(import.meta.dir, "..", "..", "templates");
 const BEGIN = "<!-- AGENT_HUB:BEGIN (managed by `ahub init`, edits inside are overwritten) -->";
@@ -96,6 +97,12 @@ function changes(cwd: string, requested?: ProfileName, shadow = false): PlannedW
     if (!lines.split("\n").includes(entry)) lines = `${lines}${lines && !lines.endsWith("\n") ? "\n" : ""}${entry}\n`;
   }
   if (existsSync(join(cwd, KIMI_MCP_FILE)) && hubGitSync(["ls-files", "--error-unmatch", "--", KIMI_MCP_FILE], { cwd, encoding: "utf8", timeout: 3000 }).status !== 0 && !lines.split("\n").includes(KIMI_MCP_FILE)) lines = `${lines}${lines && !lines.endsWith("\n") ? "\n" : ""}${KIMI_MCP_FILE}\n`;
+  const agyPlugin = ".agents/plugins/agent-hub/";
+  if (existsSync(join(cwd, agyPlugin))) {
+    const tracked = new Set(hubGitSync(["ls-files", "--", agyPlugin], { cwd, encoding: "utf8", timeout: 3000 }).stdout.trim().split("\n").filter(Boolean));
+    const entries = tracked.size ? AGY_PLUGIN_FILES.filter(file => !tracked.has(file)) : [agyPlugin];
+    for (const entry of entries) if (!lines.split("\n").includes(entry)) lines = `${lines}${lines && !lines.endsWith("\n") ? "\n" : ""}${entry}\n`;
+  }
   if (existsSync(join(cwd, JCODE_MCP_FILE)) && hubGitSync(["ls-files", "--error-unmatch", "--", JCODE_MCP_FILE], { cwd, encoding: "utf8", timeout: 3000 }).status !== 0 && !lines.split("\n").includes(JCODE_MCP_FILE)) lines = `${lines}${lines && !lines.endsWith("\n") ? "\n" : ""}${JCODE_MCP_FILE}\n`;
   write(ignore, lines, "ignore runtime state and machine-local configuration");
   return changed;

package/src/cli/launch.ts

@@ -12,6 +12,8 @@ import type { InstancesConfig } from "../hub/instances.ts";
 import { kimiAcpCommand } from "../adapters/definitions/native-daemon-kimi.ts";
 export const CLAUDE_CHANNEL = "plugin:agent-hub@agent-hub";
 
+export { retainedLaunchWarning } from "../adapters/definitions/native-cli-retained.ts";
+
 /** Consume only ahub's selector, never native arguments after the passthrough delimiter. */
 export function instanceLaunchArguments(command: string, raw: readonly string[], instances?: InstancesConfig): { instance?: string; args: string[]; hubStarted?: true } {
   if (!definitionOf(command)) return { args: [...raw] };
@@ -52,7 +54,7 @@ export function nativeLaunchEnv(tool: string, source: NodeJS.ProcessEnv, instanc
   delete env.AGENTHUB_UNATTENDED;
   // Channel evidence for the plugin (issue #205): set beside the development-channel flag `buildLaunch` always passes.
   const definition = definitionOf(tool, instances);
-  if (definition?.identity.mcp === "channel-plugin") env.AGENTHUB_CHANNEL = "1";
+  if (definition?.identity.mcp === "channel-plugin" && !definition.attach?.pullOnlyForms?.includes("tui")) env.AGENTHUB_CHANNEL = "1";
   if (definition?.attach?.pullOnlyForms?.includes("tui")) delete env.AGENTHUB_MODE; // its MCP child must attach pull-only, never as a tools socket
   return env;
 }

package/src/cli/main.ts

@@ -255,8 +255,8 @@ function exec(bin: string, argv: string[], tool?: "claude" | "codex" | "kimi", e
   process.exit(res.status ?? 1);
 }
 
-function execWithEnv(bin: string, argv: string[], extra: NodeJS.ProcessEnv, executionCwd = cwd): never {
-  const env: NodeJS.ProcessEnv = { ...nativeLaunchEnv(selectedInstance ?? "pi", extra, declaredInstances), AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd };
+function execWithEnv(bin: string, argv: string[], extra: NodeJS.ProcessEnv, peer: string, executionCwd = cwd): never {
+  const env: NodeJS.ProcessEnv = { ...nativeLaunchEnv(peer, extra, declaredInstances), AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd };
   delete env.AGENTHUB_RECOVERY_OPERATION;
   delete env.AGENTHUB_UNATTENDED;
   const res = spawnSync(bin, argv, { cwd: executionCwd, stdio: "inherit", env });
@@ -854,11 +854,11 @@ const commands: Record<string, () => Promise<void> | void> = {
     if (selectedInstance && !args.includes("--print-command") && !args.includes("--dry-run")) {
       const hub = await nativeConnect(); hub.close();
     }
-    const context: NativeCliEntryContext = { args, cwd, stateDir, cliDir: import.meta.dir, unattendedEnv, definition: entry.definition,
+    const context: NativeCliEntryContext = { args, cwd, stateDir, cliDir: import.meta.dir, unattendedEnv, person: caller.role === "console", definition: entry.definition,
       ...(selectedInstance ? { instance: selectedInstance } : {}), ...(nativeSelection.hubStarted ? { hubStarted: true as const } : {}),
       projectConfig, connect: nativeConnect, fail,
       exec: (bin, argv, tool) => exec(bin, argv, tool, context.executionCwd),
-      execWithEnv: (bin, argv, env) => execWithEnv(bin, argv, env, context.executionCwd), takeFlags,
+      execWithEnv: (bin, argv, env) => execWithEnv(bin, argv, env, selectedInstance ?? entry.command, context.executionCwd), takeFlags,
       helpers: { launcherPreview: (tool, raw, projectRoot, state, unattended) => launcherPreview(tool, raw, projectRoot, state, unattended, selectedInstance), readControl, recordTerminalLaunch, recoveryLock, processSignature,
         buildLaunch, claudeObservationHooks, recordClaudeLaunch, cleanupStaleClaudeSettings, cleanupClaudeSettings,
         nativeLaunchEnv, runClaudeLaunch, childEnv, qwenSessionId, configureJcodeMcp, configureKimiMcp,
@@ -906,6 +906,7 @@ const commands: Record<string, () => Promise<void> | void> = {
     hub.close();
     if (!res.ok) fail(res.error);
     if (res.recorded) return console.log("recorded only ([FYI]); no peer was interrupted");
+    if (res.dropped === "hop") return console.log(res.notice);
     console.log(paint([{ text: res.targets.length ? `queued for: ${res.targets.join(", ")}` : "no peers attached; nothing delivered" }], false));
     if (typeof res.notice === "string" && res.notice) console.log(paint([{ text: res.notice }], false));
   },

package/src/cli/output.ts

@@ -9,6 +9,7 @@ import { formatReport, formatTaskReport, type Report, type TaskReport } from "..
 export interface DoctorCheck { section: "Tools" | "Hub" | "Config" | "Models" | "Memory"; level: "ok" | "warn" | "fail" | "unknown"; name: string; detail: string }
 export interface StatusOutput {
   pendingRestart?: readonly { key: string; reason: string }[];
+  retainedConfig?: readonly { key: string; reason: string }[];
   taskStalls?: readonly { task: number; cause: { kind: string; peer?: string; dependency?: number; code: string } }[];
   pendingTaskOffers?: readonly { task: number; peer: string }[];
   isolatedChecks?: { pending?: number; orphans?: string[]; unknownReceipts?: readonly string[]; maintenanceUnavailable?: boolean };
@@ -191,6 +192,10 @@ export function renderStatus(data: StatusOutput, columns?: number, now = Date.no
   const out = lines(`agent-hub${data.version ? ` ${data.version}` : ""}  pid ${data.pid ?? "unknown"}  control 127.0.0.1:${data.controlPort ?? "unknown"}`, columns, "info");
   if (data.cwd) out.push(...lines(data.cwd, columns));
   for (const pending of data.pendingRestart ?? []) out.push(...detail("pending restart", `${pending.key}: ${pending.reason}`, columns, "attention"));
+  if (data.retainedConfig?.length) {
+    out.push(...detail("config retained", `${data.retainedConfig.map(row => row.key).join(", ")}; run ahub settings reload`, columns, "attention"));
+    for (const pending of data.retainedConfig) out.push(...detail("retained reason", `${pending.key}: ${pending.reason}`, columns, "attention"));
+  }
   for (const stall of data.taskStalls ?? []) out.push(...detail(`task #${stall.task} stalled`, `${stall.cause.kind}${stall.cause.peer ? ` ${stall.cause.peer}` : ""}${stall.cause.dependency ? ` #${stall.cause.dependency}` : ""}: ${stall.cause.code}; configure the peer, ahub task assign ${stall.task} <peer>, or ahub task cancel ${stall.task} --reason <text>`, columns, "attention"));
   for (const offer of data.pendingTaskOffers ?? []) out.push(...detail("task offer", `open ${offer.peer}: task #${offer.task} is waiting for it`, columns, "attention"));
   if (data.memoryProfile) {

package/src/cli/preview.ts

@@ -4,7 +4,7 @@ import { childEnv } from "../hub/child-process.ts";
 import { startModeOf } from "../hub/start-mode.ts";
 import { instanceLaunchArguments, buildLaunch, buildKimiLaunch, buildKimiTuiLaunch, nativeLaunchEnv, claudeObservationHooks } from "./launch.ts";
 import { kimiMcpPlan } from "./kimi-mcp.ts";
-import { jcodeCommand } from "../adapters/jcode.ts";
+import { jcodeCommand, jcodeTuiCommand } from "../adapters/jcode.ts";
 import { qwenSessionId } from "../hub/crash.ts";
 import { relayModelIds } from "../models/relay.ts";
 import { buildPiLaunch } from "../pi/launch.ts";
@@ -24,7 +24,7 @@ export function launcherPreview(tool: "claude" | "codex" | "kimi" | "pi" | "qwen
   const result = preview({ tool, args, cwd, stateDir, cliDir: import.meta.dir, unattended, config, definition,
     baseEnvNames: Object.keys(childEnv()).concat(["AGENTHUB_STATE_DIR", "AGENTHUB_PROJECT_DIR"]),
     helpers: { buildLaunch: (native, argv, ctx) => buildLaunch(native, argv, { ...ctx, ...(selected.instance ? { instance: selected.instance } : {}) }), claudeObservationHooks, buildKimiLaunch, buildKimiTuiLaunch, nativeLaunchEnv, childEnv,
-      startModeOf, kimiMcpPlan, jcodeCommand, qwenSessionId, relayModelIds, buildPiLaunch },
+      startModeOf, kimiMcpPlan, jcodeCommand, jcodeTuiCommand, qwenSessionId, relayModelIds, buildPiLaunch },
   });
   if (!selected.instance) return result;
   return { ...result, instance: selected.instance,

package/src/hub/bus.ts

@@ -7,6 +7,11 @@ import { PreEffectToolRefusal } from "./tool-refusal.ts";
 
 export type { DeliveryReceipt } from "./peers.ts";
 
+export interface PublishResult {
+  targets: PeerId[];
+  dropped?: "hop" | "fyi";
+}
+
 export type BusEvent =
   | { t: "envelope"; env: Envelope; dropped?: "hop" | "fyi" }
   | { t: "overflow"; env: Envelope; peer: PeerId }
@@ -294,6 +299,7 @@ export class Bus {
     // Persist each deferred -> queued transition while deliveries are still fenced. A failed checkpoint
     // leaves the hold and the original pending head intact; a crash after it resumes from the journal.
     this.flushDeferredHub();
+    this.deferHub = false;
     this.recoveryHeld = false;
     this.onQueues?.();
     for (const id of this.peers.keys()) void this.drain(id);
@@ -698,8 +704,13 @@ export class Bus {
 
   /** Returns the peers the envelope was accepted for, including durable deferred notices. */
   publish(env: Envelope): PeerId[] {
+    return this.publishResult(env).targets;
+  }
+
+  /** Publication outcome distinguishes a policy drop from an empty audience. */
+  publishResult(env: Envelope): PublishResult {
     if (this.storageError) throw new Error("delivery journal unavailable");
-    if (this.seen.has(env.id) || this.deferredHub.has(env.id)) return [];
+    if (this.seen.has(env.id) || this.deferredHub.has(env.id)) return { targets: [] };
     if (this.recoveryHeld && (this.deferHub || this.replayingHub) && env.from === HUB && env.priority !== "fyi" && env.hop <= MAX_HOP) {
       if (this.deferredHub.size >= MAX_DEFERRED_HUB) throw new RecoveryDeferredHubError();
       const targets = this.audience(env);
@@ -707,21 +718,21 @@ export class Bus {
       this.deferredHub.set(copy.id, copy);
       try { this.persist(); }
       catch (error) { this.deferredHub.delete(copy.id); throw error; }
-      return targets;
+      return { targets };
     }
     return this.publishNow(env);
   }
 
-  private publishNow(env: Envelope): PeerId[] {
+  private publishNow(env: Envelope): PublishResult {
     if (this.storageError) throw new Error("delivery journal unavailable");
-    if (this.seen.has(env.id)) return [];
+    if (this.seen.has(env.id)) return { targets: [] };
     this.seen.set(env.id, env);
     if (this.seen.size > SEEN_CAP) this.seen.delete(this.seen.keys().next().value as string);
 
     // fyi is for the record (console now, task board from M4), never worth an agent's turn.
     const dropped = env.hop > MAX_HOP ? "hop" : env.priority === "fyi" ? "fyi" : undefined;
     this.emit({ t: "envelope", env, ...(dropped ? { dropped } : {}) });
-    if (dropped) { this.persist(); return []; }
+    if (dropped) { this.persist(); return { targets: [], dropped }; }
 
     const hushed = this.hushed(env);
     if (hushed.length) this.emit({ t: "quiet", env, peers: hushed.map((h) => h.peer), reason: hushed[0]!.reason });
@@ -756,7 +767,7 @@ export class Bus {
     }
     const offRoster = targets.filter(id => !this.isRostered(id));
     if (offRoster.length) this.emit({ t: "off_roster", env, peers: offRoster });
-    return targets;
+    return { targets };
   }
 
   isRostered(peer: PeerId): boolean { return this.opts.rostered?.(peer) ?? true; }