@staix/agent-hub 0.34.0 → 0.35.0

package/src/adapters/reviewer-print.ts

@@ -1,3 +1,5 @@
+import type { ModelOverrideSelection } from "./registry-types.ts";
+import { isNativeModelToken } from "./model-token.ts";
 import type { ChildProcess } from "node:child_process";
 import { OwnedPrintChild, PrintChildCleanupError, type OwnedInputContext, type OwnedInputObserver } from "./claude-print-child.ts";
 import { randomUUID } from "node:crypto";
@@ -6,6 +8,7 @@ import { BasePeer } from "../hub/peers.ts";
 import type { DeliveryFailureCause } from "../hub/delivery-failure.ts";
 import type { Envelope } from "../hub/envelope.ts";
 import type { ReviewerMcpSession, ReviewerToolName } from "./reviewer-mcp.ts";
+import { createReviewerPolicyWatch, type ReviewerPolicyProbe, type ReviewerPolicyWatch } from "./reviewer-policy-watch.ts";
 
 /** #722: the closed list of legs a reviewer's per-review start can fail on. A class names a leg, never a path, content or token. */
 export const REVIEWER_CAUSE_CLASSES = ["version", "binary", "mcp_inventory", "plugins_hooks_apps", "sandbox_proof", "credential_root", "timeout", "unknown"] as const;
@@ -33,6 +36,9 @@ class ReviewerAdmissionError extends Error {
   constructor(readonly reason: "stale_binding" | "policy_changed") { super("review admission changed"); }
 }
 class ReviewerInputAdmissionError extends Error {}
+class ReviewerPolicyCleanupError extends PrintChildCleanupError {
+  constructor() { super("review policy worker cleanup unconfirmed; run ahub status and stop the peer before retrying"); }
+}
 
 export interface ReviewerPrintUsage { input_tokens?: number; output_tokens?: number; cache_creation_input_tokens?: number; cache_read_input_tokens?: number }
 export interface ReviewerIsolationReceipt {
@@ -60,6 +66,8 @@ export interface ReviewerPrepareContext {
   /** Host-framed public review evidence, never configuration-selected argv. */
   input?: string;
   task?: number;
+  /** Captured host runtime override, absent leaves the backend's native default unchanged. */
+  modelOverride?: string;
 }
 export interface ReviewerLaunch {
   command: readonly string[];
@@ -74,6 +82,8 @@ export interface ReviewerLaunch {
   stop?: (child: ChildProcess) => Promise<void>;
   /** Latch a change in native policy for the running review, not just at spawn. */
   watchCurrent?: true;
+  /** Fixed host factory: periodic work is separate from the synchronous current() authority fence. */
+  startPolicyWatch?: () => ReviewerPolicyProbe;
 }
 export interface ReviewerBackend {
   id: string;
@@ -120,6 +130,8 @@ export interface ReviewerFailure {
 
 export interface ReviewerReviewBinding { readonly head?: string; readonly flowRevision?: number }
 export interface ReviewerPrintOptions {
+  /** Host-only choice sampled once at the next turn/review boundary. */
+  getModelOverride?: () => ModelOverrideSelection;
   cwd: string;
   command?: readonly string[];
   mcpConfig: string;
@@ -149,6 +161,7 @@ export interface ReviewerPrintOptions {
 
 type ReviewTarget = Omit<ReviewerFailure, "cause">;
 interface ReviewBatch { targets: (ReviewTarget | undefined)[]; next: number; failures: ReviewerFailure[] }
+interface ReviewPolicyOwner { readonly child: OwnedPrintChild; readonly watch: ReviewerPolicyWatch; readonly cleanup: () => Promise<void>; readonly closed: () => void }
 const reviewTarget = (env: Envelope): ReviewTarget | undefined => {
   const task = reviewTask(env);
   if (task === undefined || env.private) return undefined;
@@ -170,6 +183,7 @@ export class ReviewerPrintPeer extends BasePeer {
   private child: OwnedPrintChild | undefined;
   private childCleanup: (() => Promise<void>) | undefined;
   private childCurrent: (() => boolean) | undefined;
+  private policyWatch: ReviewPolicyOwner | undefined;
   private reviewMcpClose: (() => void) | undefined;
   private activeDeliveryId: string | undefined;
   private batch: ReviewBatch | undefined;
@@ -221,6 +235,7 @@ export class ReviewerPrintPeer extends BasePeer {
   async start(): Promise<void> {
     // A retained child means a review's process group was never confirmed gone: no new review beside it.
     if (this.child) throw new Error(`${this.id}: an earlier review's process group is still running; stop it first`);
+    if (this.policyWatch) throw new ReviewerPolicyCleanupError();
     if (this.preparation) throw new Error(`${this.id}: reviewer preparation is still running`);
     this.receipt = undefined;
     const generation = ++this.generation;
@@ -242,8 +257,8 @@ export class ReviewerPrintPeer extends BasePeer {
     this.preparation?.abort.abort();
     await this.preparation?.done.catch(() => {});
     this.settle("needs_review", reason ?? "review stopped before settlement");
-    if (this.child) this.setState("busy"); // unavailable, not offline, until the group is confirmed gone
-    await this.kill(); // throws when the child could not be stopped; its handle is kept and the peer stays busy
+    if (this.child || this.policyWatch) this.setState("busy"); // unavailable until both owned resources are confirmed gone
+    await this.kill(true); // An explicit stop may retry an earlier failed worker join.
     this.setState("offline");
   }
 
@@ -319,7 +334,7 @@ export class ReviewerPrintPeer extends BasePeer {
         if (error instanceof PrintChildCleanupError) {
           // Unavailable until a stop confirms the group gone: no new review runs beside the survivors.
           this.opts.log?.(`[${this.id}] review of task #${task}: ${error.message}`);
-          this.settle("needs_review", `review process group still running: ${error.message}`);
+          this.settle("needs_review", error instanceof ReviewerPolicyCleanupError ? error.message : `review process group still running: ${error.message}`);
           return;
         }
         // Once an earlier review in this batch ran, the batch had effects: hold it for a person, never requeue it.
@@ -376,20 +391,21 @@ export class ReviewerPrintPeer extends BasePeer {
     return reoffered;
   }
 
-  private prepare(sessionId: string, input?: string, task?: number, mcpConfig?: string): Promise<ReviewerLaunch> {
+  private prepare(sessionId: string, input?: string, task?: number, mcpConfig?: string, modelOverride?: string): Promise<ReviewerLaunch> {
     const abort = new AbortController();
     const done = (async () => {
       if (this.opts.backend.taskMcp && !this.opts.taskMcp) throw new Error("task-bound reviewer MCP is unavailable");
       const launch = await this.opts.backend.prepare({ peer: this.id, cwd: this.opts.cwd, sessionId,
         mcpConfig: this.opts.backend.taskMcp ? (mcpConfig ?? '{"mcpServers":{}}') : this.opts.mcpConfig,
         systemPrompt: this.opts.systemPrompt, privatePaths: this.opts.privatePaths ?? [], command: this.opts.command, signal: abort.signal,
-        ...(input === undefined ? {} : { input }), ...(task === undefined ? {} : { task }) });
+        ...(input === undefined ? {} : { input }), ...(task === undefined ? {} : { task }), ...(modelOverride === undefined ? {} : { modelOverride }) });
       if ("unavailable" in launch) throw new ReviewerUnavailableError(launch.unavailable, launch.causeClass ?? "unknown", launch.detail);
       const proof = launch.isolation;
       const policy = this.opts.backend.nativePolicy
         ? proof?.enforcement === "native-policy" && proof.freshSession === true && proof.hubToolsOnly === true
         : proof?.strictMcp === true && proof.ephemeral === true;
-      if (abort.signal.aborted || !proof || proof.backend !== this.opts.backend.id || proof.readOnly !== true || !policy || !proof.binary || !proof.version || !proof.profile || !proof.evidence.length || !launch.command.length) {
+      if (abort.signal.aborted || !proof || proof.backend !== this.opts.backend.id || proof.readOnly !== true || !policy || !proof.binary || !proof.version || !proof.profile || !proof.evidence.length || !launch.command.length
+        || launch.watchCurrent && (!launch.current || !launch.startPolicyWatch)) {
         await launch.cleanup?.();
         throw new ReviewerUnavailableError("reviewer isolation is unavailable or preparation was cancelled", "unknown");
       }
@@ -410,6 +426,8 @@ export class ReviewerPrintPeer extends BasePeer {
     const revision=Number(env.refs?.reviewRevision);
     const binding: ReviewerReviewBinding=Object.freeze({head:env.refs?.commit,flowRevision:Number.isSafeInteger(revision)&&revision>0?revision:undefined});
     this.assertAdmission(env, task, binding);
+    const selection = this.opts.getModelOverride?.();
+    if (selection?.model !== undefined && !isNativeModelToken(selection.model)) throw new ReviewerAdmissionError("policy_changed");
     let facts: string | undefined;
     try { facts = this.opts.facts?.(env); } catch (error) { this.opts.log?.(`[${this.id}] review facts for task #${task} failed: ${(error as Error).message}`); }
     const input = `${frame(env)}${facts ? `\n\n${facts}` : ""}`;
@@ -433,10 +451,18 @@ export class ReviewerPrintPeer extends BasePeer {
     this.reviewMcpClose=closeMcp;
     let ownedChild: OwnedPrintChild | undefined, releasing: Promise<void> | undefined;
     let inputReleased = false, childClosed = false, launchCleanupConfirmed = false;
-    let policyTimer: ReturnType<typeof setInterval> | undefined;
+    let inputFinished = false;
+    const finishInput = () => {
+      const closedWithoutChild = !ownedChild || ownedChild.process.pid === undefined;
+      if (!inputFinished && mcpCloseConfirmed && launchCleanupConfirmed && (closedWithoutChild || inputReleased && childClosed)) {
+        inputFinished = true;
+        try { this.opts.inputFinished?.(inputContext, [env]); } catch { /* A cleanup receipt never changes the verdict. */ }
+      }
+    };
+    let policyOwner: ReviewPolicyOwner | undefined;
     const release = () => releasing ??= Promise.resolve().then(() => launch?.cleanup?.()).then(() => {});
     try {
-    launch = await this.prepare(sessionId, input, task, mcp?.config);
+    launch = await this.prepare(sessionId, input, task, mcp?.config, selection?.model);
     if (generation !== this.generation) throw new ReviewerAdmissionError("stale_binding");
     this.assertAdmission(env, task, binding);
     if (launch.current?.() === false) throw new ReviewerUnavailableError("reviewer isolation changed before child spawn", "binary");
@@ -448,9 +474,24 @@ export class ReviewerPrintPeer extends BasePeer {
       onInputReleased: () => { inputReleased = true; this.opts.inputReleased?.(inputContext, [env]); },
       onError: () => { if (this.child === child) this.child = undefined; },
       onSpawn: () => {
+        try { selection?.applied(); } catch { /* Native spawn remains authoritative. */ }
         this.runningBinding={task,binding};
         this.reviewing = task; this.reviewSeq++;
-        if (this.childCurrent) policyTimer = setInterval(() => { this.reviewToken(task); }, 100);
+        if (launch!.watchCurrent) {
+          try {
+            const sequence = this.reviewSeq, probe = launch!.startPolicyWatch!();
+            const watch = createReviewerPolicyWatch(probe, () => {
+              // Batch generation alone is insufficient: later reviews can reuse its task and generation.
+              if (this.policyWatch === policyOwner && this.child === child && generation === this.generation
+                && this.reviewing === task && this.reviewSeq === sequence) this.abortReview("review policy changed");
+            });
+            policyOwner = { child, watch, cleanup: release, closed: () => {
+              childClosed = true; launchCleanupConfirmed = true; finishInput();
+            } };
+            this.policyWatch = policyOwner;
+            watch.start();
+          } catch { this.abortReview("review policy changed"); }
+        }
       },
       onFrame: event => {
         try {
@@ -465,6 +506,7 @@ export class ReviewerPrintPeer extends BasePeer {
       onLimit: () => this.abortReview("review output limit exceeded"),
       onLeaderExit: () => {
         if (this.child === child) { this.reviewing = undefined; this.runningBinding=undefined; }
+        void this.stopPolicyWatch(policyOwner).catch(() => {});
       },
     });
     // Owned before any await, so a stop that lands before "spawn" still finds and kills it.
@@ -478,16 +520,16 @@ export class ReviewerPrintPeer extends BasePeer {
     } finally {
       if (this.activeTrace?.value === trace) this.activeTrace = undefined;
       closeMcp();
-      if (policyTimer) clearInterval(policyTimer);
+      // Joining the watcher precedes deletion of files it can still read, even when native cleanup failed.
+      await this.stopPolicyWatch(policyOwner);
       try {
         if (!ownedChild || this.child !== ownedChild) {
           await release(); if (this.childCleanup === release) this.childCleanup = undefined;
           launchCleanupConfirmed = true;
+          if (this.policyWatch === policyOwner) this.policyWatch = undefined;
         }
       } catch { this.opts.log?.(`[${this.id}] reviewer isolation cleanup incomplete`); }
-      const closedWithoutChild = !ownedChild || ownedChild.process.pid === undefined;
-      if (mcpCloseConfirmed && launchCleanupConfirmed && (closedWithoutChild || inputReleased && childClosed))
-        try { this.opts.inputFinished?.(inputContext, [env]); } catch { /* receipt cleanup never changes the review verdict */ }
+      finishInput();
     }
   }
 
@@ -498,13 +540,33 @@ export class ReviewerPrintPeer extends BasePeer {
   }
 
   /** Revokes the verdict authority at once, then stops the child; on failure the handle is kept and the error thrown. */
-  private async kill(): Promise<void> {
+  private async stopPolicyWatch(owner: ReviewPolicyOwner | undefined, retry = false): Promise<void> {
+    if (!owner) return;
+    try { await owner.watch.stop(retry); }
+    catch { throw new ReviewerPolicyCleanupError(); }
+    // Retain the owner until native teardown and private cleanup also succeed, so a failed stop can be retried.
+  }
+
+  private async kill(retryWorker = false): Promise<void> {
     this.reviewing = undefined;
     this.runningBinding=undefined;
-    const child = this.child;
-    if (!child) return;
-    await child.stop();
-    if (this.child === child) { await this.childCleanup?.(); this.child = undefined; this.childCleanup = undefined; this.childCurrent = undefined; }
+    const owner = this.policyWatch, child = this.child ?? owner?.child;
+    const cleanup = this.childCleanup ?? owner?.cleanup;
+    const workerStopped = this.stopPolicyWatch(owner, retryWorker);
+    void workerStopped.catch(() => {}); // Native OAuth grace may outlast a failed join; observe it immediately.
+    let childError: unknown, workerError: unknown;
+    try { await child?.stop(); } catch (error) { childError = error; }
+    try { await workerStopped; } catch (error) { workerError = error; }
+    if (workerError) throw workerError;
+    if (childError) throw childError;
+    if (child) {
+      await cleanup?.();
+      owner?.closed();
+      if (this.child === child) this.child = undefined;
+      if (this.childCleanup === cleanup) this.childCleanup = undefined;
+      if (this.policyWatch === owner) this.policyWatch = undefined;
+      if (!this.child && !this.policyWatch) this.childCurrent = undefined;
+    }
   }
 }
 

package/src/cli/agents.ts

@@ -6,7 +6,7 @@ import { withoutOrcaEnv } from "../hub/orca-env.ts";
 /** #691: what `ahub agents` and `ahub doctor` show for each gated native CLI. */
 export interface AgentVersionRow { id: CompatId; executable?: string; verdict: CompatVerdict; policy: string }
 
-const PROBE_ENV = { JCODE_NO_TELEMETRY: "1", JCODE_DISABLE_CLAUDE_MCP: "1" };
+const PROBE_ENV = { JCODE_NO_TELEMETRY: "1", JCODE_DISABLE_CLAUDE_MCP: "1", AGY_CLI_DISABLE_AUTO_UPDATE: "1" };
 
 /** The one place that decides what is run for an id: the configured argv (including pi.cmd) plus the probe words. */
 function probeTarget(id: CompatId, commands: Partial<Record<CompatId, readonly string[]>>): { executable: string; args: string[] } | undefined {

package/src/cli/facts-hook.ts

@@ -64,10 +64,12 @@ export async function factsHook(stdin: string, stateDir: string, peer: string, t
     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 decoded = port?.decode(nativeEvent, payload);
+    if (!port || !decoded) return undefined;
+    const forwarded = payload && typeof payload === "object" && !Array.isArray(payload) ? { ...payload, agentHubTranscriptPath: decoded.transcriptPath } : payload;
     const hub = await ControlClient.connect(stateDir, { role: "tools", peer, ...(nativeHookIdentity(stateDir, peer).nativeLaunchId ? { launchId: nativeHookIdentity(stateDir, peer).nativeLaunchId } : {}) }, timeoutMs);
     try {
-      const reply = await hub.request({ t: "native_facts", event: nativeEvent, payload, ...nativeHookIdentity(stateDir, peer) }, timeoutMs);
+      const reply = await hub.request({ t: "native_facts", event: nativeEvent, payload: forwarded, ...nativeHookIdentity(stateDir, peer), startedMs: performance.now() }, 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(); }

package/src/cli/help.ts

@@ -79,6 +79,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub roster [--json] [--color=auto|always|never]", "every known peer, participation, start mode and retained work"],
     ["ahub roster add <peer> | remove <peer> [--yes] [--now]", "person or configured conductor: change live participation through settings; removal previews retained messages and task handoff; remove also deletes the roster key of an instance no longer declared"],
     ["ahub autonomy on [--all-projects] [--yes] | off [--all-projects] | status [--json]", "person only: apply the autonomy preset and machine default with one confirmation, optionally to every registered project; off removes fixed preset keys (manual edits included); status reports modes, floor enforcement and Claude homes; settings undo restores a live-hub project write"],
+    ["ahub model set <peer> <model> | clear <peer> | list [--json]", "person only: select a runtime model at the next turn, clear its override, or inspect effective models and pending changes; unsupported peers need a restart"],
     ["ahub settings [list] [--json] | get <key> [--json]", "the settings the dashboard can change, each with its value, the file it comes from and when it applies"],
     ["ahub settings set <key> <value|inherit> [--yes] [--preview] [--now] | undo | reload", "validated settings: conductor set is limited to exact live operational keys; undo/reload and other keys are person only; --preview saves nothing; conductor writes keep the person undo record"],
     ["ahub settings edit <config.local.json|sdlc.toml> (set <path> <json> | remove <path>)... [--reason <text>] [--preview] [--yes] | backups [--json]", "human only: structural config (instances, review, snapshots, approvals, context.gate, research.runners, sdlc.toml mode and required_checks) validated by the hub's own loaders, previewed as a diff and written with a backup; a key that runs code or locates secrets needs its name typed, never --yes"],
@@ -145,9 +146,9 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub usage limits [--peer <id>] [--limit <n>] [--json] [--color=auto|always|never]", "current quota windows and the history of pauses, resumes and resets"],
     ["ahub usage total [--json] [--color=auto|always|never]", "lifetime development tokens since the first event, per peer and overall"],
     ["ahub export [--since 7d|<iso>]", "structured events (events.jsonl) as JSON lines; never message bodies; the configured conductor gets a bounded projection (last 1000 events)"],
-    ["ahub research [--since 30d] [--all] [--json]", "success, first-pass, rework and check-failure rates, tokens and wall time per approved task, from the opt-in research records"],
+    ["ahub research [--since 30d] [--all] [--json]", "success, first-pass, rework and check-failure rates, tokens and wall time per approved task (cancelled tasks have records too and are not counted), from the opt-in research records"],
     ["ahub research addons [--since 30d] [--all] [--json]", "approved tasks with each add-on (claude-mem, ponytail, ripwire, ...) on against off, with intervals; association, not cause"],
-    ["ahub research export [--format jsonl|csv] [--since 30d] [--all]", "the research records for outside analysis: ids, counts and tokens, never text"],
+    ["ahub research export [--format jsonl|csv | --dataset <dir>] [--since 30d] [--all]", "the research records for outside analysis: ids, counts and tokens, never text; --dataset writes per-project tasks.jsonl, manifest.json and quality.json (family names only, with each field's unknown count, quota gaps and token attribution share) to a directory in your home outside every project"],
     ["ahub research backfill", "build this project's research records once from events.jsonl (person or configured conductor)"],
     ["ahub bench run <suite.json> --arm <label> [--repeat N] [--tasks a,b] [--addon <name>=on|off]... [--memory off|claude-mem|native|both]", "run a benchmark suite against the peers attached here, in a project kept for benchmarks (it resets the work tree; person or configured conductor); --addon and --memory declare the arm's add-on and memory state and refuse a setup that differs"],
     ["ahub bench list|status [--json]", "benchmark runs on this machine / the one running now"],

package/src/cli/identity.ts

@@ -15,6 +15,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 === "model") return true; // #1317: even listing runtime overrides is person-only, never live-test delegated.
   if (command === "sdlc" && (args[0] === "authorize-release" || args[0] === "plan-review" || args[0] === "release-assign" || args[0] === "merge" || args[0] === "train" && args[1] !== "report")) return true;
   if (args.some(arg => arg === "--as-user" || arg.startsWith("--as-user="))) return true;
   if (command === "pet" && (args.includes("--window") || args.includes("--palette"))) return false;
@@ -143,6 +144,7 @@ const isPeerReadForm = (command: string, args: readonly string[]): boolean => {
  * The branches above them are the older authority rules and stay unchanged.
  */
 export function classifyPeerCommand(command: string, args: readonly string[], catalog?: ProjectAdapterCatalog): PeerCommandAccess {
+  if (command === "model") return "console";
   if (command === "recovery" && recoveryAction(args) === "reattach") return "console";
   const native = catalog?.definitionOf(command) ?? definitionOf(command);
   if (native?.cli.personOnlyFlags?.some(flag => args.includes(flag))) return "console";
@@ -194,6 +196,7 @@ export function classifyPeerCommand(command: string, args: readonly string[], ca
 
 /** No argument text is included: notices and refusal logs must not copy task text or credentials. */
 export function cliCommandLabel(command: string, args: readonly string[], catalog?: ProjectAdapterCatalog): string {
+  if (command === "model") return ["list", "set", "clear"].includes(args[0] ?? "") ? `model ${args[0]}` : "model";
   if (command === "peer") return args[0] === "takeover" ? "peer takeover" : "peer";
   if (command === "backlog") return ["list", "add", "pull", "pull-ready", "split", "return", "plan", "pin", "undo"].includes(args[0] ?? "") ? `backlog ${args[0]}` : "backlog";
   if (command === "board" && args[0] === "import") return "board import";

package/src/cli/kimi-facts-hook.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env bun
+import { factsHook } from "./facts-hook.ts";
+
+try {
+  const stateDir = process.env.AGENTHUB_STATE_DIR, event = process.argv[2], peer = process.env.AGENTHUB_PEER_ID;
+  const out = stateDir && event && peer ? await factsHook(await Bun.stdin.text(), stateDir, peer, 2000, event) : undefined;
+  if (out) console.log(out);
+} catch {
+  // Native hooks fail open; a missing or refused observation never changes the turn.
+}
+process.exit(0);

package/src/cli/kimi-plugin.ts

@@ -0,0 +1,157 @@
+import { randomUUID } from "node:crypto";
+import { closeSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmdirSync, unlinkSync, writeFileSync, type Stats } from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
+import { processLiveness, processSignature } from "../pi/process-signature.ts";
+
+export interface KimiPluginOptions { home: string; hookScript: string; launchId: string; replaceStale?: boolean; now?: number; ownerPid?: number; ownerSignature?: string; liveness?: typeof processLiveness }
+type JsonObject = Record<string, any>;
+type Snapshot = { stat: Stats; bytes: Buffer };
+type Target = { path: string; next: Buffer; before?: Snapshot };
+type Plan = { root: string; managed: string; installed: string; record?: JsonObject; targets: Target[]; changed: boolean };
+
+const EVENTS = ["TurnStarted", "Stop", "StopFailure", "Interrupt", "SessionEnd", "TaskStarted", "Notification"] as const;
+const ID = "agent-hub";
+const MAX_INSTALLED = 1024 * 1024;
+const MAX_HOOK = 8 * 1024 * 1024;
+const object = (value: unknown): value is JsonObject => !!value && typeof value === "object" && !Array.isArray(value);
+const directory = (path: string, required = true) => {
+  const stat = lstatSync(path, { throwIfNoEntry: false });
+  if (stat && (!stat.isDirectory() || stat.isSymbolicLink())) throw new Error(`${path} must be a plain directory`);
+  if (!stat && required) throw new Error(`${path} must exist`);
+  return stat;
+};
+function file(path: string, cap: number): Snapshot | undefined {
+  const stat = lstatSync(path, { throwIfNoEntry: false });
+  if (!stat) return undefined;
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.size > cap) throw new Error(`${path} must be a bounded regular file`);
+  return { stat, bytes: readFileSync(path) };
+}
+function parse(value: Snapshot | undefined, name: string): JsonObject | undefined {
+  if (!value) return undefined;
+  try {
+    const row = JSON.parse(value.bytes.toString("utf8"));
+    if (!object(row)) throw new Error("not an object");
+    return row;
+  } catch { throw new Error(`${name} is not valid JSON`); }
+}
+function atomic(path: string, bytes: Buffer, before: Stats | undefined): void {
+  const current = lstatSync(path, { throwIfNoEntry: false });
+  if (before ? !current || current.dev !== before.dev || current.ino !== before.ino : current) throw new Error(`${path} changed before its managed write`);
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  let fd: number | undefined;
+  try {
+    fd = openSync(temporary, "wx", 0o600);
+    writeFileSync(fd, bytes);
+    closeSync(fd); fd = undefined;
+    renameSync(temporary, path);
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+    try { unlinkSync(temporary); } catch { /* rename consumed it */ }
+  }
+}
+function removeFile(path: string, expected: Buffer): void {
+  const current = lstatSync(path, { throwIfNoEntry: false });
+  if (!current || !current.isFile() || current.isSymbolicLink() || current.nlink !== 1 || !readFileSync(path).equals(expected)) return;
+  unlinkSync(path);
+}
+function manifest(): JsonObject {
+  return { name: ID, version: "1.0.0", description: "Managed by the ahub kimi launcher for this launch only.", hooks: EVENTS.map(event => ({ event, command: `bun ./kimi-hook.js ${event}`, timeout: 5 })) };
+}
+function ownerProof(options: KimiPluginOptions): { pid: number; signature: string } {
+  const pid = options.ownerPid ?? process.pid, signature = options.ownerSignature ?? processSignature(pid);
+  if (!Number.isSafeInteger(pid) || pid <= 0 || !signature) throw new Error("Kimi plugin ownership cannot be proven");
+  return { pid, signature };
+}
+function staleOwner(record: JsonObject, options: KimiPluginOptions): boolean {
+  const owner = record.agentHubOwner;
+  if (!object(owner) || !Number.isSafeInteger(owner.pid) || owner.pid <= 0 || typeof owner.signature !== "string" || !owner.signature) return false;
+  try { return (options.liveness ?? processLiveness)(owner.pid, owner.signature) === "gone"; } catch { return false; }
+}
+function plan(options: KimiPluginOptions): Plan {
+  if (!isAbsolute(options.home) || !isAbsolute(options.hookScript) || !/^[A-Za-z0-9._:-]{1,128}$/.test(options.launchId)) throw new Error("Kimi home, hook bundle and launch identity must be valid");
+  directory(options.home);
+  const hook = file(options.hookScript, MAX_HOOK);
+  if (!hook) throw new Error("Kimi hook bundle is missing");
+  const root = join(options.home, "plugins"), managed = join(root, "managed", ID), installed = join(root, "installed.json");
+  const installedBefore = file(installed, MAX_INSTALLED), document = parse(installedBefore, installed);
+  if (document && (document.version !== 1 || !Array.isArray(document.plugins))) throw new Error(`${installed} has an unsupported shape`);
+  const records = document?.plugins ?? [];
+  if (records.some((row: unknown) => !object(row))) throw new Error(`${installed} has an invalid plugin row`);
+  const record = records.find((row: JsonObject) => row.id === ID);
+  if (record && record.agentHubLaunch !== options.launchId && options.replaceStale === true && !staleOwner(record, options)) throw new Error("Kimi's agent-hub plugin owner is active or unknown; it was not changed");
+  if (record && (record.root !== managed || record.source !== "local-path" || record.origin !== "custom" || record.enabled !== true || typeof record.originalSource !== "string"
+    || record.agentHubLaunch !== options.launchId && options.replaceStale !== true)) {
+    throw new Error("Kimi's agent-hub plugin belongs to another launch or is disabled; it was not changed");
+  }
+  const manifestBefore = file(join(managed, "kimi.plugin.json"), MAX_INSTALLED), hookBefore = file(join(managed, "kimi-hook.js"), MAX_HOOK);
+  const nextManifest = Buffer.from(`${JSON.stringify(manifest(), null, 2)}\n`);
+  const now = new Date(options.now ?? Date.now()).toISOString();
+  const changed = !record || record.agentHubLaunch !== options.launchId || !record.agentHubOwner || !manifestBefore?.bytes.equals(nextManifest) || !hookBefore?.bytes.equals(hook.bytes) || record.originalSource !== dirname(options.hookScript);
+  const nextRecord = {
+    id: ID, root: managed, source: "local-path", origin: "custom", enabled: true,
+    installedAt: typeof record?.installedAt === "string" ? record.installedAt : now,
+    updatedAt: changed ? now : typeof record?.updatedAt === "string" ? record.updatedAt : now,
+    originalSource: dirname(options.hookScript), agentHubLaunch: options.launchId,
+    agentHubOwner: record && record.agentHubLaunch === options.launchId && record.agentHubOwner ? record.agentHubOwner : ownerProof(options),
+  };
+  const nextDocument = { version: 1, plugins: [...records.filter((row: JsonObject) => row.id !== ID), nextRecord] };
+  return { root, managed, installed, ...(record ? { record } : {}), changed,
+    targets: [
+      { path: join(managed, "kimi.plugin.json"), next: nextManifest, ...(manifestBefore ? { before: manifestBefore } : {}) },
+      { path: join(managed, "kimi-hook.js"), next: hook.bytes, ...(hookBefore ? { before: hookBefore } : {}) },
+      { path: installed, next: Buffer.from(`${JSON.stringify(nextDocument, null, 2)}\n`), ...(installedBefore ? { before: installedBefore } : {}) },
+    ] };
+}
+
+export function kimiPluginPreview(home: string, hookScript: string): { file: string; changed: true; action: string } {
+  if (!isAbsolute(home) || !isAbsolute(hookScript)) throw new Error("Kimi home and hook bundle must be absolute paths");
+  directory(home, false);
+  if (!file(hookScript, MAX_HOOK)) throw new Error("Kimi hook bundle is missing");
+  return { file: join(home, "plugins", "managed", ID), changed: true, action: "only after Kimi 2.5.2 is confirmed, install the launch-scoped completion plugin and remove it on exit; other versions keep the existing TUI with no plugin" };
+}
+
+export function kimiPluginPlan(options: KimiPluginOptions): { file: string; changed: boolean; action: string } {
+  const current = plan(options);
+  return { file: current.managed, changed: current.changed, action: current.changed ? "create or update the launch-scoped Kimi plugin" : "keep the launch-scoped Kimi plugin" };
+}
+
+function locked<T>(options: KimiPluginOptions, run: () => T): T {
+  if (!isAbsolute(options.home)) throw new Error("Kimi home must be an absolute path");
+  directory(options.home);
+  const path = join(options.home, "agent-hub-plugin.lock");
+  let fd: number;
+  try { fd = openSync(path, "wx", 0o600); }
+  catch { throw new Error(`Another Kimi plugin replacement is active or left a stale lock; retry after it exits or inspect ${path}`); }
+  try { return run(); }
+  finally { closeSync(fd); unlinkSync(path); }
+}
+
+export function ensureKimiPlugin(options: KimiPluginOptions): { changed: boolean } {
+  return locked(options, () => {
+    const current = plan(options);
+    if (!current.changed) return { changed: false };
+    for (const path of [join(options.home, "plugins"), join(options.home, "plugins", "managed"), current.managed]) {
+      if (!directory(path, false)) mkdirSync(path, { mode: 0o700 });
+    }
+    for (const target of current.targets) atomic(target.path, target.next, target.before?.stat);
+    return { changed: true };
+  });
+}
+
+export function cleanupKimiPlugin(options: KimiPluginOptions): void {
+  locked(options, () => {
+    const current = plan({ ...options, replaceStale: false });
+    const installedBefore = file(current.installed, MAX_INSTALLED), document = parse(installedBefore, current.installed);
+    const records = document?.plugins;
+    if (!document || !Array.isArray(records) || records.some((row: unknown) => !object(row))) throw new Error(`${current.installed} changed during the launch`);
+    const record = records.find((row: JsonObject) => row.id === ID);
+    if (!record) return;
+    if (record.root !== current.managed || record.enabled !== true) throw new Error("Kimi's agent-hub plugin changed during the launch; leaving it installed");
+    const next = { version: 1, plugins: records.filter((row: JsonObject) => row.id !== ID) };
+    atomic(current.installed, Buffer.from(`${JSON.stringify(next, null, 2)}\n`), installedBefore?.stat);
+    const [manifestTarget, hookTarget] = current.targets;
+    removeFile(join(current.managed, "kimi.plugin.json"), manifestTarget!.next);
+    removeFile(join(current.managed, "kimi-hook.js"), hookTarget!.next);
+    try { rmdirSync(current.managed); } catch { /* foreign or changed files stay */ }
+  });
+}

package/src/cli/main.ts

@@ -70,6 +70,8 @@ import { loadConfig } from "../hub/daemon.ts";
 import { factsHook } from "./facts-hook.ts";
 import { hubHome, projectContext, projectRoot, realPath } from "../hub/project.ts";
 import { Registry, type Project } from "../hub/registry.ts";
+import { datasetInputFor, exportResearchDataset, projectFamilyOf } from "../hub/research-dataset.ts";
+import { readEvidence } from "../hub/research-record.ts";
 import { inspectProject, startProject, stopProject, runProjectDaemon } from "../hub/lifecycle.ts";
 import { processLiveness, processSignature } from "../pi/process-signature.ts";
 import { openManager, startManager, stopManager } from "../hub/manager.ts";
@@ -114,7 +116,7 @@ import { renderTidyPreview, renderTidyResult, renderWorktrees } from "./worktree
 import { formatMemoryStaleAnchors } from "../hub/memory-stale-anchors.ts";
 import { AGENT_MEM_VERSION, assertAgentMemVersion, selectedMemoryProfile } from "../hub/memory-profile.ts";
 import { checkMemoryProfiles, formatMemoryProfileCheck } from "../hub/memory-profile-check.ts";
-import { addonReport, appendRecords, formatAddons, formatResearch, LABELS, labelTarget, RESEARCH_SCHEMA, projectKey, readStores, researchReport, taskRecords, toCsv, type Label, type TaskRecord } from "../hub/research.ts";
+import { addonReport, appendRecords, closedAtOf, formatAddons, formatResearch, LABELS, labelTarget, RESEARCH_SCHEMA, projectKey, readStores, researchReport, taskRecords, toCsv, type Label, type TaskRecord } from "../hub/research.ts";
 import { summarize, summarizeByTask } from "../hub/report.ts";
 import { readDogfood } from "../hub/dogfood-read.ts";
 import { dogfoodSince, formatDogfood } from "../hub/dogfood.ts";
@@ -126,7 +128,7 @@ import { agentShellCause, classifyPeerCommand, cliCommandLabel, detectCliIdentit
 import { recordCliAudit, recordDelegatedCliAudit } from "./identity-audit.ts";
 import { runConsole } from "./console.ts";
 import { paint, permissionBoundary, resolveColor, wrap, type Span } from "./console-state.ts";
-import { outputWidth, renderRoster, renderStatus, renderBoard, renderBacklog, renderBoardColumns, boardColumnModel, renderBudget, renderDoctor, renderProjects, renderQueue, renderTurns, renderOrphans, renderOrphanCleanup, renderQueueShow, renderModelsStatus, renderExecutionBudgetStatus, renderReport, renderUsage, renderLimits, renderTotal, type DoctorCheck } from "./output.ts";
+import { outputWidth, renderRuntimeModels, renderRoster, renderStatus, renderBoard, renderBacklog, renderBoardColumns, boardColumnModel, renderBudget, renderDoctor, renderProjects, renderQueue, renderTurns, renderOrphans, renderOrphanCleanup, renderQueueShow, renderModelsStatus, renderExecutionBudgetStatus, renderReport, renderUsage, renderLimits, renderTotal, type DoctorCheck } from "./output.ts";
 import { renderHelp, configuredAcpHelp } from "./help.ts";
 import { renderBacklogResult, renderGroom, renderReleaseChange, renderReleaseList, renderReleaseNew, renderReleaseShow, renderTaskCancel, renderTaskShow } from "./task-output.ts";
 import { renderAuthorization, renderSdlcCosts, renderSdlcExplain, renderSdlcMerge, renderSdlcMetrics, renderSdlcQueue, renderSdlcRelease, renderSdlcStatus } from "./sdlc-output.ts";
@@ -851,11 +853,14 @@ function benchRunArgs(rest: string[]) {
 }
 /** Another project is `ahub --project <dir> research`; anything unknown is refused rather than ignored. */
 function researchArgs(): void {
-  const sub = args[0], flags = new Set(["--all", "--json", "--since", "--format"]), valued = new Set(["--since", "--format"]);
+  const sub = args[0], flags = new Set(["--all", "--json", "--since", "--format", "--dataset"]), valued = new Set(["--since", "--format", "--dataset"]);
   for (let i = sub === "export" || sub === "backfill" || sub === "addons" ? 1 : 0; i < args.length; i++) {
     if (!flags.has(args[i]!)) fail(`ahub research: unknown argument ${args[i]} (another project: ahub --project <dir> research)`);
     if (valued.has(args[i]!)) i++;
   }
+  if (args.includes("--dataset") && (sub !== "export" || args.includes("--format"))) fail("ahub research: --dataset belongs to export and replaces --format (usage: ahub research export --dataset <dir> [--since] [--all])");
+  const at = args.indexOf("--dataset");
+  if (at >= 0 && (args[at + 1] === undefined || args[at + 1]!.startsWith("--"))) fail("ahub research: --dataset takes a directory");
 }
 const SOURCE_USAGE = "usage: ahub source add <path|url> [--json] [--color=auto|always|never] | list [--json] [--color=auto|always|never]";
 /** #933: a local conductor form's argument check, run before the `admit` handshake so a usage error leaves no admitted row. */
@@ -1179,7 +1184,7 @@ const commands: Record<string, () => Promise<void> | void> = {
   up: async () => {
     const unattended = unattendedEnv || args.includes("--unattended");
     if (unattended) console.error(UNATTENDED_WARNING);
-    const status = await startProject(registeredProject(), { unattended, liveTest, ...(recoveryLauncherCurrent ? { current: recoveryLauncherCurrent, env: { ...personEnv(process.env), AGENTHUB_RECOVERY_OPERATION: continuationId, AGENTHUB_PEER_ID: continuationPeer, AGENTHUB_RECOVERY_CONDUCTOR: continuationPeer, AGENTHUB_RECOVERY_CONTINUATION: continuationId } } : {}) });
+    const status = await startProject(registeredProject(), { unattended, liveTest, starting: pid => console.error(`ahub: hub is still starting, pid ${pid}; waiting for readiness, run ahub status in another terminal to inspect progress`), ...(recoveryLauncherCurrent ? { current: recoveryLauncherCurrent, env: { ...personEnv(process.env), AGENTHUB_RECOVERY_OPERATION: continuationId, AGENTHUB_PEER_ID: continuationPeer, AGENTHUB_RECOVERY_CONDUCTOR: continuationPeer, AGENTHUB_RECOVERY_CONTINUATION: continuationId } } : {}) });
     console.log(`ahub up (ws://127.0.0.1:${status.controlPort}), state in ${stateDir}`);
     if (recoveryLauncherCurrent) { recoveryLauncherCurrent(); return; }
     // #608: the default agent set, only for a person's own `ahub up` (never an agent's, a live test's, or an upgrade or recovery relaunch, which set AGENTHUB_RECOVERY_OPERATION).
@@ -1220,6 +1225,26 @@ const commands: Record<string, () => Promise<void> | void> = {
     return entry.execute(context);
   }])),
 
+  model: async () => {
+    const { parseModelCommand, projectModelStatus } = await import("./model.ts");
+    let command;
+    try { command = parseModelCommand(args); } catch (error) { return fail((error as Error).message); }
+    const hub = await connect();
+    try {
+      if (!hub.features.includes("model_overrides")) return fail("running hub lacks model_overrides support; upgrade and restart the hub, then retry ahub model list");
+      const { json, ...message } = command;
+      const result = await hub.request({ t: "model", ...message });
+      if (result.ok !== true) return fail(String(result.error ?? "model request refused; upgrade and restart the hub before retrying"), result.refusalAudited === true, result.authorityRefused);
+      if (command.op !== "list" && result.appliesFrom !== "next_turn") return fail("model change is unconfirmed; inspect ahub model list before retrying");
+      const values = command.op === "list" ? result.models : [result.model];
+      if (!Array.isArray(values) || values.length > 512) return fail("model reply is not a supported bounded row list; upgrade and restart the hub, then retry ahub model list");
+      const models = values.map(projectModelStatus);
+      if (models.some(row => row === null)) return fail("model reply invalid; upgrade and restart the hub, then retry ahub model list");
+      const options = { json };
+      if (options.json) console.log(JSON.stringify({ models }, null, 2));
+      else printOutput(renderRuntimeModels(models.filter((row): row is NonNullable<typeof row> => row !== null)), false);
+    } finally { hub.close(); }
+  },
   models: async () => {
     const action = outputArguments()[0] ?? "status";
     const options = ["status", "start", "setup"].includes(action) ? outputOptions() : undefined;
@@ -2526,17 +2551,31 @@ const commands: Record<string, () => Promise<void> | void> = {
     const [sub] = args;
     researchArgs();
     if (sub === "backfill") {
-      const project = researchProject();
-      const written = appendRecords(project.id, taskRecords(readEvents(join(stateDir, "events.jsonl")), project.id, { version: VERSION, source: "backfill" }));
+      const project = researchProject(), familyOf = projectFamilyOf(cwd);
+      const written = appendRecords(project.id, taskRecords(readEvents(join(stateDir, "events.jsonl")), project.id, { version: VERSION, source: "backfill" }, { ...readEvidence(stateDir, project.id), ...(familyOf ? { familyOf } : {}) }));
       return console.log(`${written} research record${written === 1 ? "" : "s"} written from this project's events`);
     }
     const all = args.includes("--all");
-    const records = readStores(all ? undefined : researchProject(false).id);
     const from = since();
+    if (sub === "export" && args.includes("--dataset")) {
+      // #1277: the dataset is read-only over the stores; a project that was never researched has no file and no directory. The target is refused inside any registered project.
+      const registry = new Registry();
+      let registered: Project[];
+      try { registered = registry.list(); } finally { registry.close(); }
+      const here = researchProject(false), chosen = all ? registered : [here];
+      const inputs = chosen.flatMap(p => { const input = datasetInputFor(p); return input ? [input] : []; });
+      if (!inputs.length) return fail(all ? "no registered project has research records" : "this project has no research records; turn research on and run ahub research backfill");
+      try {
+        const written = exportResearchDataset(args[args.indexOf("--dataset") + 1]!, inputs, { ...(from > 0 ? { since: from } : {}) }, [...registered, here]);
+        for (const w of written) console.log(`${w.projectKeyHash}: ${w.counts.tasks} task${w.counts.tasks === 1 ? "" : "s"} (${w.counts.approved} approved, ${w.counts.cancelled} cancelled), ${w.counts.labels} label${w.counts.labels === 1 ? "" : "s"} -> ${w.dir}`);
+      } catch (error) { return fail((error as Error).message); }
+      return;
+    }
+    const records = readStores(all ? undefined : researchProject(false).id);
     if (sub === "export") {
       const format = args[args.indexOf("--format") + 1] ?? "jsonl";
       if (args.includes("--format") && !["jsonl", "csv"].includes(format)) fail("--format takes jsonl or csv");
-      const kept = records.filter((r) => r.kind === "label" || Date.parse(r.approvedAt) >= from);
+      const kept = records.filter((r) => r.kind === "label" || Date.parse(closedAtOf(r) ?? "") >= from);
       return void process.stdout.write(args.includes("--format") && format === "csv" ? toCsv(kept) : kept.map((r) => JSON.stringify(r)).join("\n") + (kept.length ? "\n" : ""));
     }
     if (sub === "addons") {
@@ -2544,7 +2583,7 @@ const commands: Record<string, () => Promise<void> | void> = {
       const rows = addonReport(records, from);
       return console.log(args.includes("--json") ? JSON.stringify(rows, null, 2) : formatAddons(rows).join("\n"));
     }
-    if (sub !== undefined && !sub.startsWith("--")) fail("usage: ahub research [--since 30d] [--all] [--json] | addons [--since] [--all] [--json] | export [--format jsonl|csv] [--since] [--all] | backfill");
+    if (sub !== undefined && !sub.startsWith("--")) fail("usage: ahub research [--since 30d] [--all] [--json] | addons [--since] [--all] [--json] | export [--format jsonl|csv | --dataset <dir>] [--since] [--all] | backfill");
     const r = researchReport(records, from);
     console.log(args.includes("--json") ? JSON.stringify(r, null, 2) : formatResearch(r).join("\n"));
   },