@staix/agent-hub 0.12.36 → 0.12.38

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/help.ts

@@ -25,6 +25,8 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub sdlc queue <owner/repo> | release <owner/repo> [live-issue...]", "read-only merge and release evidence (person only)"],
     ["ahub sdlc accept <task> --issue <n> [--repo owner/repo]", "accept the task's spec issue at its current body; build entry needs it in enforce (person only)"],
     ["ahub sdlc plan-review <task> <revision> <reason...> [--review full|delta|none --reviewers N --ci full|focused|reuse]", "record planner review, scope and host-read issue metadata"],
+    ["ahub sdlc train report|configure|cut <release-id> [revision] [json]", "plan a release and freeze its approved scope after resource/quota admission"],
+    ["ahub sdlc release-assign <task> <revision> <release-id|none> <reason>", "assign approved/in-flight work without changing execution"],
     ["ahub sdlc costs [owner/repo]", "read bounded planner cost metrics for linked merged PRs"],
     ["ahub backlog groom | return <task> <revision> <reason...>", "read grooming findings or return accepted untouched work to backlog (planner/person)"],
     ["ahub status [--json] [--full] [--color=auto|always|never]", "the hub, its peers, model backends and task counts"],

package/src/cli/identity.ts

@@ -13,7 +13,7 @@ export const LIVE_TEST_PERSON_REFUSAL = "live-test cannot write person-attribute
 
 /** Person verdicts and user-authored workflow content are never delegated. */
 export function liveTestRefusal(command: string, args: readonly string[], context: { repairedFresh?: boolean } = {}): boolean {
-  if (command === "sdlc" && args[0] === "plan-review") return true;
+  if (command === "sdlc" && (args[0] === "plan-review" || args[0] === "release-assign" || args[0] === "train" && args[1] !== "report")) return true;
   if (args.some(arg => arg === "--as-user" || arg.startsWith("--as-user="))) return true;
   const sub = command === "recovery" ? recoveryAction(args) : args.find(arg => arg !== "--json");
   return ["task", "role", "goal"].includes(command)

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

@@ -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));
   },
@@ -1118,6 +1119,25 @@ const commands: Record<string, () => Promise<void> | void> = {
       finally { hub.close(); }
       return;
     }
+    if (sub === "train") {
+      const operation = args[1], releaseId = Number(args[2]), revision = Number(args[3]);
+      if (!Number.isSafeInteger(releaseId) || releaseId <= 0) fail("usage: ahub sdlc train report|configure|cut <release-id> [revision] [configuration-json]");
+      if (operation === "report" && args.length === 3) return console.log(await taskOp("hub_release_report", { id: releaseId }));
+      if (!Number.isSafeInteger(revision) || revision < 0) fail("train mutation requires its current revision");
+      if (operation === "cut" && args.length === 4) return console.log(await taskOp("hub_release_cut", { id: releaseId, revision }));
+      if (operation === "configure" && args.length === 5) {
+        let fields;
+        try { fields = JSON.parse(args[4]!); } catch { return fail("release train configuration must be JSON"); }
+        if (!fields || typeof fields !== "object" || Array.isArray(fields) || Object.keys(fields).some(key => !["state", "cut", "hotfix"].includes(key))) fail("invalid release train configuration fields");
+        return console.log(await taskOp("hub_release_configure", { ...fields, id: releaseId, revision }));
+      }
+      fail("usage: ahub sdlc train report|configure|cut <release-id> [revision] [configuration-json]");
+    }
+    if (sub === "release-assign") {
+      const revision = Number(args[2]), release = args[3] === "none" ? null : Number(args[3]);
+      if (!Number.isSafeInteger(id) || id! <= 0 || !Number.isSafeInteger(revision) || revision < 0 || release !== null && (!Number.isSafeInteger(release) || release <= 0) || args.length < 5) fail("usage: ahub sdlc release-assign <task> <planning-revision> <release-id|none> <reason...>");
+      return console.log(await taskOp("hub_release_assign", { id, revision, release, reason: args.slice(4).join(" ") }));
+    }
     if (sub === "costs") {
       if (args.length > 2) fail("usage: ahub sdlc costs [owner/repository]");
       return console.log(await taskOp("hub_sdlc_costs", { ...(args[1] ? { repo: args[1] } : {}) }));

package/src/cli/memory.ts

@@ -1,13 +1,12 @@
 import { detectCliIdentity } from "./identity.ts";
 import { createStalenessProbe } from "../hub/memory-staleness.ts";
-import { looksSecret, type MemoryStore, type StoreOptions } from "@staix/agent-mem";
+import { looksSecret, type MemoryStore } from "@staix/agent-mem";
 import type { SyncOptions } from "@staix/agent-mem";
 import { MEMORY_USAGE as CORE_MEMORY_USAGE, rawMemoryCommand, rawGoalCommand } from "@staix/agent-mem";
-import { memoryProjectKey } from "@staix/agent-mem";
 import { mentionsPrivatePath, promotionScreen, withoutPii } from "../hub/memory-policy.ts";
 import { currentRouting, detectSignals } from "../hub/routing.ts";
 import { loadConfig } from "../hub/daemon.ts";
-import { bindProfileMemory, openProfileMemory, MEMORY_PROFILE_UNAVAILABLE, type MemoryProfileReceipt } from "../hub/memory-profile.ts";
+import { bindProfileMemory, memoryProjectFor, openProfileMemory, MEMORY_PROFILE_UNAVAILABLE, MEMORY_SPLIT_INCOMPLETE, type MemoryProfileReceipt, type ProfileMemoryOptions } from "../hub/memory-profile.ts";
 
 export { GOAL_USAGE } from "@staix/agent-mem";
 export const MEMORY_USAGE = `${CORE_MEMORY_USAGE} | decay [--days N] [--json] | profile-check [--json]`;
@@ -18,9 +17,9 @@ const loadConfigSafe = (cwd: string) => { try { return loadConfig(cwd); } catch
 
 
 /** Bind each command at entry; the CLI closes default opens and injected stores remain caller-owned. */
-function commandStores(provided?: MemoryStore, options: StoreOptions = {}) {
+function commandStores(provided: MemoryStore | undefined, options: ProfileMemoryOptions) {
   try { return { ...(provided ? bindProfileMemory(provided) : openProfileMemory(options)), owned: !provided }; }
-  catch { throw new Error(MEMORY_PROFILE_UNAVAILABLE); }
+  catch (error) { throw new Error(error instanceof Error && error.message === MEMORY_SPLIT_INCOMPLETE ? error.message : MEMORY_PROFILE_UNAVAILABLE); }
 }
 function profileOutput(text: string, json: boolean, profile: MemoryProfileReceipt | undefined, person: boolean): string {
   if (!profile) return text;
@@ -44,9 +43,9 @@ export async function memoryCommand(args: string[], cwd: string, opts: { store?:
     const cutoffMs = (opts.now ?? Date.now)() - days * 24 * 3600_000;
     if (!Number.isSafeInteger(days) || !Number.isFinite(cutoffMs) || Math.abs(cutoffMs) > 8_640_000_000_000_000) fail("--days is outside the supported date range");
     const cutoff = new Date(cutoffMs).toISOString();
-    const project = memoryProjectKey(cwd), routing = currentRouting(cwd), paths = privatePaths();
+    const project = memoryProjectFor(cwd), routing = currentRouting(cwd), paths = privatePaths();
     // Review must not promote a held source while reading it: only explicit person actions may append rows.
-    const context = commandStores(opts.store, { deferPromotions: true, now: opts.now });
+    const context = commandStores(opts.store, { project, deferPromotions: true, now: opts.now });
     const store = context.store;
     try {
       context.binding.assertCurrent();
@@ -68,11 +67,12 @@ export async function memoryCommand(args: string[], cwd: string, opts: { store?:
     } finally { if (context.owned) store.close(); }
   }
   let showStale = false;
-  const context = commandStores(opts.store, { ttlMs: (loadConfigSafe(cwd)?.memory.short_ttl_days ?? 14) * 24 * 3600_000,
-    screen: promotionScreen(memoryProjectKey(cwd), cwd, () => currentRouting(cwd), privatePaths) });
+  const project = memoryProjectFor(cwd);
+  const context = commandStores(opts.store, { project, ttlMs: (loadConfigSafe(cwd)?.memory.short_ttl_days ?? 14) * 24 * 3600_000,
+    screen: promotionScreen(project, cwd, () => currentRouting(cwd), privatePaths) });
   try {
     context.binding.assertCurrent();
-    const text = await rawMemoryCommand(args, cwd, { ...opts, store: context.store, open: () => context.store,
+    const text = await rawMemoryCommand(args, cwd, { ...opts, project, store: context.store, open: () => context.store,
       readable: notes => {
       const paths = privatePaths(), visible = withoutPii(notes, currentRouting(cwd), cwd, paths);
       if (args[0] !== "show" || args.includes("--json")) return visible;
@@ -92,10 +92,11 @@ export async function memoryCommand(args: string[], cwd: string, opts: { store?:
 export async function goalCommand(args: string[], cwd: string, opts: { store?: MemoryStore; link?: (goal: string, task: string) => Promise<string>; person?: boolean } = {}): Promise<string> {
   const person = opts.person ?? detectCliIdentity(process.env).role === "console";
   const policy = (): string[] => { try { return loadConfig(cwd).pii?.paths ?? []; } catch (e) { return fail(`the project's config does not load (${(e as Error).message}); fix it before using long-term tasks`); } };
-  const context = commandStores(opts.store);
+  const project = memoryProjectFor(cwd);
+  const context = commandStores(opts.store, { project });
   try {
     context.binding.assertCurrent();
-    const text = await rawGoalCommand(args, cwd, { ...opts, store: context.store, open: () => context.store,
+    const text = await rawGoalCommand(args, cwd, { ...opts, project, store: context.store, open: () => context.store,
       clean: (title, milestones, project) => !looksSecret(`${title}\n${milestones.join("\n")}`) && withoutPii([{ title, text: milestones.join("\n"), project }], currentRouting(cwd), cwd, policy()).length > 0,
     });
     return profileOutput(text, args.includes("--json"), context.binding.status(context.store), person);