@staix/agent-hub 0.34.1 → 0.35.0

package/src/hub/deliverable-files.ts

@@ -7,7 +7,7 @@ import { isDenied } from "../local/deny.ts";
 import { isHubWritePath } from "./permission-mode.ts";
 import { realPath } from "./project.ts";
 import { insideRoot } from "./path-policy.ts";
-import { DELIVERABLE_LIMITS, deliverableId, type DeliverableClaim, type DeliverableRecord, type DeliverableState } from "./deliverables.ts";
+import { DELIVERABLE_LIMITS, deliverableId, parseDeliverableClaims, type DeliverableClaim, type DeliverableRecord, type DeliverableState } from "./deliverables.ts";
 
 /**
  * The only code that opens a deliverable (#509a). The hub hashes the bytes itself; nothing an agent says about a file is used.
@@ -67,7 +67,7 @@ function locate(path: string, ports: DeliverablePorts): Located {
 const sameFile = (a: Pick<Stats, "dev" | "ino">, b: Pick<Stats, "dev" | "ino">) => a.dev === b.dev && a.ino === b.ino;
 
 /** sha256 and size of one vetted file, or a refusal. */
-async function digest(path: string, found: Located): Promise<{ sha256: string; bytes: number }> {
+async function digest(path: string, found: Located, read?: { limit: number; current: () => void }): Promise<{ sha256: string; bytes: number; data?: Uint8Array; identity: { dev: number; ino: number } }> {
   let handle;
   deliverableHooks.beforeOpen?.(path);
   try { handle = await open(found.real, constants.O_RDONLY | NOFOLLOW); }
@@ -75,21 +75,54 @@ async function digest(path: string, found: Located): Promise<{ sha256: string; b
   try {
     const before = await handle.stat();
     if (!before.isFile() || !sameFile(before, found.stat) || before.size !== found.stat.size || before.mtimeMs !== found.stat.mtimeMs) return refuse(path, "the file changed while it was being checked");
-    const hash = createHash("sha256"), buffer = Buffer.allocUnsafe(CHUNK);
+    if (read && before.ctimeMs !== found.stat.ctimeMs) return refuse(path, "the file changed while it was being checked");
+    const hash = createHash("sha256"), buffer = Buffer.allocUnsafe(CHUNK), chunks: Uint8Array[] = [];
+    const limit = read?.limit ?? DELIVERABLE_LIMITS.fileBytes;
     let bytes = 0;
     for (;;) {
+      read?.current();
       const { bytesRead } = await handle.read(buffer, 0, CHUNK, bytes);
       if (!bytesRead) break;
       bytes += bytesRead;
-      if (bytes > DELIVERABLE_LIMITS.fileBytes) return refuse(path, "larger than the size limit");
+      if (bytes > limit) return refuse(path, "larger than the size limit");
       hash.update(buffer.subarray(0, bytesRead));
+      if (read) chunks.push(Uint8Array.from(buffer.subarray(0, bytesRead)));
     }
     const after = await handle.stat();
     if (after.size !== bytes || after.size !== before.size || after.mtimeMs !== before.mtimeMs) return refuse(path, "the file changed while it was being read");
-    return { sha256: hash.digest("hex"), bytes };
+    if (read && (!sameFile(after, before) || after.ctimeMs !== before.ctimeMs)) return refuse(path, "the file changed while it was being read");
+    read?.current();
+    return { sha256: hash.digest("hex"), bytes, identity: { dev: before.dev, ino: before.ino }, ...(read ? { data: Buffer.concat(chunks, bytes) } : {}) };
   } finally { await handle.close().catch(() => {}); }
 }
 
+export interface GuardedDeliverableRead {
+  data: Uint8Array;
+  sha256: string;
+  bytes: number;
+  /** Host-only physical identity; never stored as a visual record or used as content proof. */
+  identity: { dev: number; ino: number };
+}
+
+/** Reuse the deliverable guard and opened-descriptor reader; this export refuses private files before reading any bytes. */
+export async function readGuardedDeliverable(path: string, ports: DeliverablePorts, limit = DELIVERABLE_LIMITS.fileBytes): Promise<GuardedDeliverableRead> {
+  parseDeliverableClaims([{ path, format: "bin" }]);
+  if (!Number.isSafeInteger(limit) || limit < 0 || limit > DELIVERABLE_LIMITS.fileBytes) return refuse(path, "invalid read limit; use the deliverable size limit or a smaller bound");
+  const privacy = (real?: string) => {
+    try {
+      if (ports.private(path) || real !== undefined && ports.private(relative(realPath(ports.cwd), real))) return refuse(path, "private file; choose a public project file and retry");
+    } catch { return refuse(path, "private file or unavailable privacy policy; choose a public project file and retry"); }
+  };
+  privacy();
+  const found = locate(path, ports); privacy(found.real);
+  if (found.stat.size > limit) return refuse(path, "larger than the read limit; choose a smaller file and retry");
+  const result = await digest(path, found, { limit, current: () => privacy(found.real) });
+  const current = locate(path, ports); privacy(current.real);
+  if (!sameFile(current.stat, result.identity) || current.stat.size !== found.stat.size || current.stat.mtimeMs !== found.stat.mtimeMs || current.stat.ctimeMs !== found.stat.ctimeMs)
+    return refuse(path, "the file changed while it was being read; retry with a stable file");
+  return { data: result.data!, sha256: result.sha256, bytes: result.bytes, identity: result.identity };
+}
+
 /** Refuse a bad claim before any effect, without hashing: the path must be inside the project, allowed, and a regular file of a usable size. */
 export function vetDeliverables(claims: readonly DeliverableClaim[], ports: DeliverablePorts): void {
   let total = 0;

package/src/hub/dogfood-profile.ts

@@ -26,7 +26,7 @@ const criterion = (s: unknown): s is string => typeof s === "string" && /^[A-Za-
 
 // Exhaustive maps make producer union changes a compile-time review point.
 const taskStates: Record<TaskState,true> = {backlog:true,proposed:true,in_progress:true,in_review:true,approved:true,changes_requested:true,cancelled:true};
-const usageSources: Record<Extract<StampedEvent,{type:"usage"}>["source"],true> = {omniroute:true,claude_transcript:true,claude_result:true,codex_appserver:true,kimi_wire:true,jcode_acp:true};
+const usageSources: Record<Extract<StampedEvent,{type:"usage"}>["source"],true> = {omniroute:true,claude_transcript:true,claude_result:true,codex_appserver:true,kimi_wire:true,jcode_acp:true,agy_transcript:true};
 const attributions: Record<Attribution,true> = {delivery:true,single_open:true,unattributed:true};
 const screenItems: Record<ScreenItem,true> = {task:true,summary:true,"review note":true,handoff:true,note:true};
 const screenMisses: Record<ScreenMiss,true> = {"too long":true,"off campus":true,timeout:true,unreadable:true,failed:true};

package/src/hub/envelope.ts

@@ -16,7 +16,7 @@ export interface Envelope {
   kind: Kind;
   priority: Priority;
   body: string; // agent conclusions only, never tool noise
-  refs?: { repo?: string; branch?: string; commit?: string; paths?: string[]; task?: string; reviewRevision?: string; reviewPackage?: string; reviewResponse?: string; taskOffer?: number; taskCancelled?: number; taskRecipient?: "owner" | "reviewer" | "planner"; planReview?: number; planReviewFlow?: number; planAuthor?: string; backlog?: number[]; supervision?: boolean; supervisionKey?: string; completedFor?: number; boundedCheck?: string; budgetResume?: string; budgetResumeMoves?: { id: number; title: string; to: PeerId | null; role: "owner" | "reviewer" }[]; budgetResumeEarlier?: string[]; invocation?: string; invocationRemote?: true; question?: string; handoff?: { project: string; task: number } };
+  refs?: { visual?: string; repo?: string; branch?: string; commit?: string; paths?: string[]; task?: string; reviewRevision?: string; reviewPackage?: string; reviewResponse?: string; taskOffer?: number; taskCancelled?: number; taskRecipient?: "owner" | "reviewer" | "planner"; planReview?: number; planReviewFlow?: number; planAuthor?: string; backlog?: number[]; supervision?: boolean; supervisionKey?: string; completedFor?: number; boundedCheck?: string; budgetResume?: string; budgetResumeMoves?: { id: number; title: string; to: PeerId | null; role: "owner" | "reviewer" }[]; budgetResumeEarlier?: string[]; invocation?: string; invocationRemote?: true; question?: string; handoff?: { project: string; task: number } };
   /** The body must not be shown outside its recipients: console tail and log print a stub instead (PII tasks). */
   private?: boolean;
   /** Sent by a distinct session (`<peer>~<origin>`, agent-hub#1036): a connection that named a peer id but is not that peer's current session. It grants nothing; it marks the sender for the log. */

package/src/hub/events.ts

@@ -14,6 +14,7 @@ export const EVENTS_SCHEMA = 1;
  * ids, routing and sizes, tasks carry ids and states, so the file can be exported without leaking what agents wrote.
  */
 export type HubEvent =
+  | { type: "model_change"; peer: string; previousModel: string | null; model: string | null; by: "person"; source: "cli" | "dashboard"; appliesFrom: "next_turn"; afterTurn?: string }
   | { type: "release_authorization"; by: PeerId; authorization: string; commit: string; version: string; docsDigest: string; documents: number }
   | { type: "permission_mode"; peer: string; from: import("./permission-mode.ts").PermissionMode; to: import("./permission-mode.ts").PermissionMode }
   | { type: "role"; peer?: string; task?: number; actor: string; stage: "prepared" | "assigned"; roles: { id: string; layer: "shipped" | "project"; hash: string }[] }
@@ -27,12 +28,14 @@ export type HubEvent =
   | { type: "envelope"; id: string; from: string; to?: string[]; priority: string; hop: number; kind?: string; task?: string; bytes?: number; private?: boolean; dropped?: string; origin?: import("./provenance.ts").Origin }
   /** #604 PR B: one per peer-role or tools-role hello, with the same fields an envelope's `origin` carries. No cwd, root or token. */
   | ({ type: "attach" } & import("./provenance.ts").Origin)
+  /** Visual payloads and paths stay local; observer events carry counts only. */
+  | { type: "visual"; id: string; kind: "mermaid" | "comparison" | "table" | "beforeAfter"; bytes: number; files: number; task?: number }
   | { type: "overflow" | "undeliverable"; id: string; from: string; peer: string }
   | { type: "stale"; id: string; from: string; peer: string; task?: string }
   | { type: "quiet"; id: string; from: string; peers: string[] }
   | { type: "fact"; peer: string; id: string; files: number; plans: number; unknown: number; named: number; bytes: number; via: "hook" | "steer" | "done"; ms?: number; hookMs?: number; rttMs?: number; accepted?: boolean; unanswered?: boolean; probe?: boolean; coverage?: boolean }
   | { type: "fact_ack"; peer: string; id: string; via: string; ms: number }
-  | ({ type: "route"; peer: string; route: string; tier: string; source: "override" | "dimensions" | "hold" | "classifier" | "default" | "load" | "cooldown" | "pin"; score: number; ms: number; stateless?: boolean; decision?: string; turn?: string; task?: number; pii?: boolean; severity?: number; spinning?: number; exploring?: number; production?: number } & Partial<SwitchTrace>)
+  | ({ type: "route"; peer: string; route: string; tier: string; source: "override" | "dimensions" | "hold" | "classifier" | "default" | "load" | "cooldown" | "pin" | "decision"; score: number; ms: number; decisionMode?: "off" | "shadow"; chosenAlias?: string | null; chosenEffort?: string | null; margin?: number; decisionLatencyMs?: number; decisionReason?: string; fallbackApplied?: boolean; decider?: { provider: string; model: string; version?: string; latencyMs: number } | null; stateless?: boolean; decision?: string; turn?: string; task?: number; pii?: boolean; severity?: number; spinning?: number; exploring?: number; production?: number } & Partial<SwitchTrace>)
   | { type: "cooldown"; peer: string; alias: string; event: "start" | "end"; failures: number; ms?: number }
   | { type: "route_outcome"; peer: string; decision: string; turnId: string; turn: "completed" | "failed"; task?: number; pii: boolean; latched: boolean; next?: { severity: number; tests: "pass" | "fail" | "none"; repeat: boolean }; advisor?: "approve" | "redo" | "failed" }
   | { type: "advisor"; peer: string; route: string; trigger: string; verdict: "approve" | "redo" | "failed"; discardedChars: number }
@@ -40,7 +43,8 @@ export type HubEvent =
   | { type: "stuck"; peer: string; task: number; category: "repetition" | "false_progress" | "drift" | "desperation" | "capability_gap"; streak: number; latched: boolean }
   | { type: "capability"; peer: string; state: "verified" | "lost"; via?: string }
   /** A hub run began: every peer is detached until its next state event (#248: attachments never span a crash). */
-  | { type: "hub_start"; instance: string }
+  /** `personAttribution`: this run writes `task` and `attribution` on permission, question, completion and agent_cli events (#1278). A log with no such start says nothing about which task a person interaction belonged to. */
+  | { type: "hub_start"; instance: string; personAttribution?: true }
   /** #248: the add-ons a peer works with, names and versions from a closed list, at each attach. */
   | { type: "tooling"; peer: string; addons: import("./tooling.ts").Addon[] }
   /** #258: a task brief handed to its owner: how many hub-memory items (and fails among them) and supplemental items (legacy claudeMem field), never their text. New local-library records identify source amem. */
@@ -50,22 +54,22 @@ export type HubEvent =
   | { type: "turn_start"; peer: string; turn: string }
   | { type: "native_thread"; peer: string; thread: string; fresh: boolean }
   | ({ type: "turn_end"; peer: string; turn: string; ms: number; tokens?: number; files?: number; snapshotMs?: number; preparedRoles?: RoleIdentity[] | null } & Partial<TaskAttribution>)
-  | { type: "native_turn_end"; peer: string; id?: string }
+  | { type: "native_turn_end"; peer: string; id?: string; reason?: "user_canceled" | "error" | "max_invocations" | "max_forced_invocations" | "max_token_budget_exceeded" | "terminal_step_type" | "terminal_custom_hook" }
   | { type: "conduct"; peer: string; action: string; task?: number; target?: string }
-  | { type: "agent_cli"; peer: string; command: string; refused: boolean; delegated?: true }
-  | { type: "permission"; id: string; peer: string; event: "requested" | "answered" | "expired" | "cancelled"; latencyMs?: number; surface?: "console" | "dashboard" | "terminal"; option?: "allow_once" | "allow_always" | "reject_once" | "reject_always" }
+  | ({ type: "agent_cli"; peer: string; command: string; refused: boolean; delegated?: true } & Partial<TaskAttribution>)
+  | ({ type: "permission"; id: string; peer: string; event: "requested" | "answered" | "expired" | "cancelled"; latencyMs?: number; surface?: "console" | "dashboard" | "terminal"; option?: "allow_once" | "allow_always" | "reject_once" | "reject_always" } & Partial<TaskAttribution>)
   /** #1053: one question a peer asked the person, and how it ended. Counts, ids and a closed reason only: never a prompt, an option, an answer or other text. */
-  | { type: "question"; set: string; peer: string; event: "asked" | "answered" | "pending" | "superseded" | "cancelled" | "expired" | "unavailable"; latencyMs?: number; surface?: "terminal" | "console" | "dashboard" | "acon"; person?: string; reason?: "superseded" | "stopped" | "turn_aborted" | "session_changed" | "expired" | "unattended"; questions?: number; private?: boolean }
+  | ({ type: "question"; set: string; peer: string; event: "asked" | "answered" | "pending" | "superseded" | "cancelled" | "expired" | "unavailable"; latencyMs?: number; surface?: "terminal" | "console" | "dashboard" | "acon"; person?: string; reason?: "superseded" | "stopped" | "turn_aborted" | "session_changed" | "expired" | "unattended"; questions?: number; private?: boolean } & Partial<TaskAttribution>)
   /** Completed native turns that received supervision, not feed enqueues or inferred costs. */
   | { type: "supervision_turn"; peer: string; turn: string; tokens?: number; ms?: number }
   /** #1054: a run a person started settled (or a restart cut it short). Ids, a closed outcome and a duration only: never the prompt or the reply. */
   /** #1054: a person (or the hub on a person's command) marked a result read. A receipt only: never read from a snapshot. */
   | { type: "completion_seen"; id: string; surface: "terminal" | "console" | "dashboard" | "acon" }
-  | { type: "completion"; id: string; peer: string; outcome: "done" | "failed" | "limit" | "interrupted"; ms: number }
+  | ({ type: "completion"; id: string; peer: string; outcome: "done" | "failed" | "limit" | "interrupted"; ms: number } & Partial<TaskAttribution>)
   | { type: "hook_stats"; peer: string; n: number; startupMs: number; hubMs: number; maxStartupMs: number }
   | { type: "cohort"; id: number; event: "formed" | "joined" | "lifted"; silent: boolean; tasks: number[]; owners: string[] }
-  | ({ type: "tokens"; peer: string; n: number } & Partial<TaskAttribution>)
-  | ({ type: "usage"; peer: string; source: "omniroute" | "claude_transcript" | "claude_result" | "codex_appserver" | "kimi_wire" | "jcode_acp"; id: string; reasoningTokens?: number; measuredAt?: string; requestedModel?: string; servedModel?: string; provider?: string; inputTokens?: number; outputTokens?: number; cacheReadTokens?: number; cacheWriteTokens?: number; totalTokens?: number } & Partial<TaskAttribution>)
+  | ({ type: "tokens"; peer: string; n: number; source?: "kimi_wire"; id?: string } & Partial<TaskAttribution>)
+  | ({ type: "usage"; peer: string; source: "omniroute" | "claude_transcript" | "claude_result" | "codex_appserver" | "kimi_wire" | "jcode_acp" | "agy_transcript"; id: string; reasoningTokens?: number; measuredAt?: string; requestedModel?: string; servedModel?: string; provider?: string; inputTokens?: number; outputTokens?: number; cacheReadTokens?: number; cacheWriteTokens?: number; totalTokens?: number } & Partial<TaskAttribution>)
   | { type: "planning"; by: string; task?: number; release?: number; fields: string[]; revision: number }
   | { type: "task"; id: number; event: string; by: string; state: string; owner: string | null; reviewer: string | null; class: string; profile?: string; profileClass?: string; role?: string; roleIdentity?: { id: string; layer: "shipped" | "project"; hash: string }; pii: boolean; reason?: string; release?: number | null; priority?: number | null; plannedStart?: number | null; due?: number | null }
   | { type: "overlap"; task: number; owner: string; others: { task: number; owner: string; paths: string[]; symbols?: string[] }[] }
@@ -139,18 +143,24 @@ export function tokenDeltas(): (peer: string, total: number, session: string) =>
  */
 export function readEvents(file: string, since = 0): StampedEvent[] {
   if (!existsSync(file)) return [];
-  return readFileSync(file, "utf8").split("\n").flatMap((line) => {
-    if (!line.trim()) return [];
-    try {
-      const e = JSON.parse(line) as StampedEvent;
-      const measuredAt = e.type === "usage" && typeof e.measuredAt === "string" ? e.measuredAt : e.at;
-      return Date.parse(measuredAt) >= since ? [e] : [];
-    } catch {
-      return [];
-    }
+  return readFileSync(file, "utf8").split("\n").flatMap(line => {
+    const event = parseEventLine(line, since);
+    return event === undefined ? [] : [event];
   });
 }
 
+/** The historical event-reader predicate, shared without adding shape or line-size restrictions. */
+export function parseEventLine(line: string, since = 0): StampedEvent | undefined {
+  if (!line.trim()) return undefined;
+  try {
+    const e = JSON.parse(line) as StampedEvent;
+    const measuredAt = e.type === "usage" && typeof e.measuredAt === "string" ? e.measuredAt : e.at;
+    return Date.parse(measuredAt) >= since ? e : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /** `7d`, `24h`, `90m` or an ISO date, as epoch ms; undefined when it is neither. */
 export function parseSince(text: string, now = Date.now()): number | undefined {
   const m = /^(\d+)([dhm])$/.exec(text);

package/src/hub/execution-lineage.ts

@@ -0,0 +1,120 @@
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+import { EXECUTION_REFERENCE_LIMITS, executionReferenceKey, executionText, parseExecutionReference, type ExecutionReferenceV1 } from "./execution-reference.ts";
+
+/** Snapshot admission is host-owned; never accept these authority flags from a caller or producer. */
+export const LINEAGE_LIMITS = Object.freeze({ nodes: 100, edges: 200, bytes: 256 * 1024, sourceNodes: 2048, sourceEdges: 4096, sourceBytes: 4 * 1024 * 1024, token: 128, state: 64, cursor: 512, minimumBytes: 4096 });
+export type LineageStrength = "declared" | "host-observed" | "runner-attested" | "unknown";
+export type LineageRelation = "dispatched" | "attempted" | "produced" | "reviewed" | "declared-external";
+export interface LineageNode { ref: ExecutionReferenceV1; state: string; strength: LineageStrength }
+export interface LineageEdge { from: ExecutionReferenceV1; to: ExecutionReferenceV1; relation: LineageRelation; strength: LineageStrength }
+export interface ExecutionLineageSource {
+  id: string; revision: string; projectKey: string; scope: string;
+  /** Host-owned ephemeral signing key, never supplied by a query or persisted by this reader. */
+  cursorKey: string;
+  authorized: boolean; diagnostics: boolean;
+  health: "ready" | "missing" | "corrupt" | "unsupported" | "withheld";
+  /** Owner-authorized PUBLIC root neighborhood, complete at this revision. Apply privacy in the
+   * owner's indexed read before these arrays or their bounds exist; never pass hidden rows here. */
+  nodes: readonly LineageNode[];
+  edges: readonly LineageEdge[];
+}
+export interface LineageQuery { root: ExecutionReferenceV1; cursor?: string; nodes?: number; edges?: number; bytes?: number }
+export type LineageResult = { state: "unavailable"; reason?: "missing" | "corrupt" | "unsupported" | "withheld" | "cursor_invalid" | "invalid" }
+  | { state: "available"; nodes: LineageNode[]; edges: LineageEdge[]; truncated: boolean; cursor?: string };
+const STRENGTHS: readonly string[] = ["declared", "host-observed", "runner-attested", "unknown"];
+const RELATIONS: readonly string[] = ["dispatched", "attempted", "produced", "reviewed", "declared-external"];
+const bytes = (value: unknown): number => Buffer.byteLength(JSON.stringify(value), "utf8");
+const hash = (value: unknown): string => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+const limit = (value: number | undefined, cap: number, min = 1): number => {
+  if (value === undefined) return cap;
+  if (!Number.isSafeInteger(value) || value < min || value > cap) throw new Error("invalid limit");
+  return value;
+};
+
+/** Pure bounded projection. No IO, clocks, probes, model calls, persistence or inference. */
+export function readExecutionLineage(source: ExecutionLineageSource, query: LineageQuery): LineageResult {
+  const unavailable = (reason: NonNullable<Extract<LineageResult, { state: "unavailable" }>["reason"]>): LineageResult =>
+    ({ state: "unavailable", ...(source.authorized && source.diagnostics ? { reason } : {}) });
+  // Authority precedes even a source-health or root read: absent and denied are indistinguishable.
+  if (!source.authorized) return { state: "unavailable" };
+  if (source.health !== "ready") return unavailable(source.health);
+  let root: ExecutionReferenceV1, nodeLimit: number, edgeLimit: number, byteLimit: number;
+  try {
+    root = parseExecutionReference(query.root);
+    nodeLimit = limit(query.nodes, LINEAGE_LIMITS.nodes); edgeLimit = limit(query.edges, LINEAGE_LIMITS.edges);
+    byteLimit = limit(query.bytes, LINEAGE_LIMITS.bytes, LINEAGE_LIMITS.minimumBytes);
+  } catch { return unavailable("invalid"); }
+  try {
+    const rootKey = executionReferenceKey(root);
+    if (![source.id, source.revision, source.scope].every(value => executionText(value, LINEAGE_LIMITS.token)) ||
+        !executionText(source.cursorKey, LINEAGE_LIMITS.token) || Buffer.byteLength(source.cursorKey) < 32 ||
+        !executionText(source.projectKey, EXECUTION_REFERENCE_LIMITS.projectKey) || root.projectKey !== source.projectKey) return unavailable("invalid");
+    // ponytail: oversized neighborhoods need source-owner indexed paging, never a larger inbox scan.
+    if (source.nodes.length > LINEAGE_LIMITS.sourceNodes || source.edges.length > LINEAGE_LIMITS.sourceEdges) return unavailable("unsupported");
+    const nodes = new Map<string, LineageNode>();
+    let size = 0;
+    for (const raw of source.nodes) {
+      const ref = parseExecutionReference(raw.ref), key = executionReferenceKey(ref);
+      if (ref.projectKey !== source.projectKey || !executionText(raw.state, LINEAGE_LIMITS.state) ||
+          !/^[a-z][a-z0-9_-]*$/.test(raw.state) || !STRENGTHS.includes(raw.strength) || nodes.has(key)) return unavailable("corrupt");
+      const node = { ref, state: raw.state, strength: raw.strength };
+      nodes.set(key, node); size += bytes(node);
+    }
+    if (!nodes.has(rootKey)) return unavailable("missing");
+    const edges: LineageEdge[] = [], edgeKeys = new Set<string>();
+    const adjacent = new Map<string, string[]>();
+    for (const raw of source.edges) {
+      const from = parseExecutionReference(raw.from), to = parseExecutionReference(raw.to);
+      const fromKey = executionReferenceKey(from), toKey = executionReferenceKey(to);
+      if (!nodes.has(fromKey) || !nodes.has(toKey)) return unavailable("corrupt");
+      if (!RELATIONS.includes(raw.relation) || !STRENGTHS.includes(raw.strength) ||
+          (raw.relation === "declared-external" && raw.strength !== "declared")) return unavailable("corrupt");
+      const edge = { from, to, relation: raw.relation, strength: raw.strength }, key = JSON.stringify(edge);
+      if (edgeKeys.has(key)) continue;
+      edgeKeys.add(key); edges.push(edge); size += bytes(edge);
+      for (const [a, b] of [[fromKey, toKey], [toKey, fromKey]] as const) {
+        const neighbors = adjacent.get(a) ?? []; neighbors.push(b); adjacent.set(a, neighbors);
+      }
+    }
+    if (size > LINEAGE_LIMITS.sourceBytes) return unavailable("unsupported");
+    const seen = new Set([rootKey]), queue = [rootKey];
+    for (let i = 0; i < queue.length; i++) for (const key of adjacent.get(queue[i]!) ?? []) {
+      if (!seen.has(key)) { seen.add(key); queue.push(key); }
+    }
+    const visibleNodes = queue.map(key => nodes.get(key)!);
+    const visibleEdges = edges.filter(edge => seen.has(executionReferenceKey(edge.from)) && seen.has(executionReferenceKey(edge.to)));
+    const binding = hash([source.id, source.revision, source.scope, root, nodeLimit, edgeLimit, byteLimit, visibleNodes, visibleEdges]);
+    const sign = (n: number, e: number): string => createHmac("sha256", source.cursorKey).update(JSON.stringify([binding, n, e])).digest("hex");
+    let n = 0, e = 0;
+    if (query.cursor !== undefined) {
+      if (typeof query.cursor !== "string" || query.cursor.length > LINEAGE_LIMITS.cursor || !/^[A-Za-z0-9_-]+$/.test(query.cursor)) return unavailable("cursor_invalid");
+      let cursor: unknown;
+      try { cursor = JSON.parse(Buffer.from(query.cursor, "base64url").toString("utf8")); }
+      catch { return unavailable("cursor_invalid"); }
+      if (!Array.isArray(cursor) || cursor.length !== 4) return unavailable("cursor_invalid");
+      const [cursorBinding, nextN, nextE, signature] = cursor;
+      if (cursorBinding !== binding || !Number.isSafeInteger(nextN) || !Number.isSafeInteger(nextE) || nextN < 0 || nextE < 0 ||
+          nextN > visibleNodes.length || nextE > visibleEdges.length || typeof signature !== "string" ||
+          !/^[0-9a-f]{64}$/.test(signature) || !timingSafeEqual(Buffer.from(signature, "hex"), Buffer.from(sign(nextN, nextE), "hex"))) return unavailable("cursor_invalid");
+      n = nextN; e = nextE;
+    }
+    const pageNodes: LineageNode[] = [], pageEdges: LineageEdge[] = [];
+    const page = (nextN: number, nextE: number): Extract<LineageResult, { state: "available" }> => {
+      const truncated = nextN < visibleNodes.length || nextE < visibleEdges.length;
+      return { state: "available", nodes: pageNodes, edges: pageEdges, truncated,
+        ...(truncated ? { cursor: Buffer.from(JSON.stringify([binding, nextN, nextE, sign(nextN, nextE)])).toString("base64url") } : {}) };
+    };
+    while (n < visibleNodes.length && pageNodes.length < nodeLimit) {
+      pageNodes.push(visibleNodes[n]!);
+      if (bytes(page(n + 1, e)) > byteLimit) { pageNodes.pop(); break; }
+      n++;
+    }
+    while (e < visibleEdges.length && pageEdges.length < edgeLimit) {
+      pageEdges.push(visibleEdges[e]!);
+      if (bytes(page(n, e + 1)) > byteLimit) { pageEdges.pop(); break; }
+      e++;
+    }
+    if (!pageNodes.length && !pageEdges.length && (n < visibleNodes.length || e < visibleEdges.length)) return unavailable("unsupported");
+    return page(n, e);
+  } catch { return unavailable("corrupt"); }
+}

package/src/hub/execution-reference.ts

@@ -0,0 +1,36 @@
+import { types } from "node:util";
+/** ExecutionReferenceV1 is an opaque address, never authority or a resolver instruction. */
+export const EXECUTION_PRODUCERS = ["ahub", "ares", "amem", "vmem"] as const;
+export interface ExecutionReferenceV1 {
+  v: 1;
+  tool: typeof EXECUTION_PRODUCERS[number];
+  projectKey: string;
+  kind: string;
+  id: string;
+  revision?: string;
+  sha256?: string;
+}
+export const EXECUTION_REFERENCE_LIMITS = Object.freeze({ id: 256, projectKey: 256, revision: 128, kind: 64 });
+const invalid = (): never => { throw new Error("execution reference has invalid fields or bounds; use the ExecutionReferenceV1 contract"); };
+export function executionText(value: unknown, max: number): value is string {
+  return typeof value === "string" && value.length > 0 && value.length <= max &&
+    Buffer.byteLength(value, "utf8") <= max && !/[\p{Cc}\p{Cs}]/u.test(value);
+}
+export function parseExecutionReference(input: unknown): ExecutionReferenceV1 {
+  if (!input || typeof input !== "object" || types.isProxy(input) || Array.isArray(input) ||
+      ![Object.prototype, null].includes(Object.getPrototypeOf(input)) || Object.getOwnPropertySymbols(input).length) return invalid();
+  const fields = Object.getOwnPropertyDescriptors(input);
+  const keys = ["v", "tool", "projectKey", "kind", "id", "revision", "sha256"];
+  if (Object.entries(fields).some(([key, field]) => !keys.includes(key) || !("value" in field))) return invalid();
+  const get = (key: string): unknown => fields[key]?.value;
+  const tool = get("tool"), projectKey = get("projectKey"), kind = get("kind"), id = get("id");
+  if (get("v") !== 1 || !EXECUTION_PRODUCERS.includes(tool as ExecutionReferenceV1["tool"]) ||
+      !executionText(projectKey, EXECUTION_REFERENCE_LIMITS.projectKey) || !executionText(id, EXECUTION_REFERENCE_LIMITS.id) ||
+      !executionText(kind, EXECUTION_REFERENCE_LIMITS.kind) || !/^[a-z][a-z0-9._-]*$/.test(kind)) return invalid();
+  const revision = get("revision"), sha256 = get("sha256");
+  if ((Object.hasOwn(fields, "revision") && !executionText(revision, EXECUTION_REFERENCE_LIMITS.revision)) ||
+      (Object.hasOwn(fields, "sha256") && (typeof sha256 !== "string" || !/^[0-9a-f]{64}$/.test(sha256)))) return invalid();
+  return { v: 1, tool: tool as ExecutionReferenceV1["tool"], projectKey, kind, id,
+    ...(revision === undefined ? {} : { revision: revision as string }), ...(sha256 === undefined ? {} : { sha256: sha256 as string }) };
+}
+export const executionReferenceKey = (ref: ExecutionReferenceV1): string => JSON.stringify(parseExecutionReference(ref));

package/src/hub/hub-tools.ts

@@ -8,7 +8,7 @@ import { NOTE_KINDS } from "./envelope.ts";
 
 /** Restricted to the fixed current-child tools server, never an ordinary peer tool. */
 /** The fixed MCP surface of a current owned implementer child; independent of broader project roles. */
-export const IMPLEMENTER_HUB_TOOL_NAMES: readonly string[] = Object.freeze(["hub_task_accept", "hub_task_decline", "hub_task_done", "hub_checkpoint", "hub_send", "hub_task_show", "hub_task_propose", "hub_remember", "hub_inbox", "hub_permission_request", "hub_study_show", "hub_experiment_show", "hub_experiment_record", "hub_study_handoff", "hub_specs", "hub_delivery_resolve", "hub_evidence_record"]);
+export const IMPLEMENTER_HUB_TOOL_NAMES: readonly string[] = Object.freeze(["hub_task_accept", "hub_task_decline", "hub_task_done", "hub_checkpoint", "hub_send", "hub_task_show", "hub_task_propose", "hub_remember", "hub_visual", "hub_visual_show", "hub_inbox", "hub_permission_request", "hub_study_show", "hub_experiment_show", "hub_experiment_record", "hub_study_handoff", "hub_specs", "hub_delivery_resolve", "hub_evidence_record"]);
 
 export const IMPLEMENTER_PERMISSION_TOOL = {
   name: "hub_permission_request",
@@ -22,6 +22,23 @@ export const ACTIONABLE_MESSAGE_INSTRUCTION = "Do not use [FYI] for PR ready, do
 const str = { type: "string" } as const;
 const id = { type: "integer", description: "task id" } as const;
 const toolWriteRequestId = { type: "string", minLength: 1, maxLength: 256, pattern: "^v1/[A-Za-z0-9._-]{1,128}/[1-9][0-9]{0,15}/[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$", description: "control-transport-only request_id returned by an outcome-unknown write; inspect first and retry with the same key and identical arguments only if absent. Direct in-process tool calls cannot use request_id" } as const;
+const visualSideSchema = { oneOf: [
+  { type: "object", properties: { text: { type: "string", maxLength: 20 * 1024 } }, required: ["text"], additionalProperties: false },
+  { type: "object", properties: { path: { type: "string", minLength: 1, maxLength: 4096 }, alt: { type: "string", maxLength: 1000 } }, required: ["path", "alt"], additionalProperties: false },
+] } as const;
+const visualTitle = { type: "string", maxLength: 300 } as const;
+const visualCaption = { type: "string", maxLength: 2000 } as const;
+const visualInputSchema = { oneOf: [
+  { type: "object", properties: { kind: { const: "mermaid" }, source: { type: "string", minLength: 1, maxLength: 20 * 1024 }, title: visualTitle }, required: ["kind", "source"], additionalProperties: false },
+  { type: "object", properties: { kind: { const: "comparison" }, title: visualTitle, options: { type: "array", minItems: 2, maxItems: 6, items: {
+    type: "object", properties: { title: visualTitle, summary: { type: "string", maxLength: 4000 }, recommended: { type: "boolean" },
+      pros: { type: "array", maxItems: 10, items: { type: "string", maxLength: 2000 } }, cons: { type: "array", maxItems: 10, items: { type: "string", maxLength: 2000 } } }, required: ["title"], additionalProperties: false,
+  } } }, required: ["kind", "options"], additionalProperties: false },
+  { type: "object", properties: { kind: { const: "table" }, caption: visualCaption, columns: { type: "array", maxItems: 12, items: {
+    type: "object", properties: { key: { type: "string", minLength: 1, maxLength: 128 }, label: visualTitle, align: { enum: ["start", "end"] }, format: { enum: ["text", "number", "percent"] } }, required: ["key", "label"], additionalProperties: false,
+  } }, rows: { type: "array", maxItems: 500, items: { type: "object", additionalProperties: { oneOf: [{ type: "string", maxLength: 4000 }, { type: "number" }] } } } }, required: ["kind", "columns", "rows"], additionalProperties: false },
+  { type: "object", properties: { kind: { const: "beforeAfter" }, caption: visualCaption, before: visualSideSchema, after: visualSideSchema }, required: ["kind", "before", "after"], additionalProperties: false },
+] } as const;
 const refs = {
   type: "object",
   description: "where the work lives",
@@ -159,6 +176,8 @@ export const TASK_TOOLS: HubTool[] = [
   tool("hub_memory_show", "Read up to 8 visible memory ids or unique prefixes (6..64 UTF-8 bytes each). Original ids redirect; unavailable ids share one refusal. Whole output <=8 KB.", { ids: { type: "array", minItems: 1, maxItems: 8, items: { type: "string", minLength: 6, maxLength: 64, description: "6 to 64 UTF-8 bytes" } } }, ["ids"]),
   tool("hub_memory_graph", "Read screened memory neighbourhoods, fails first. Symbol starts also include optional current-head one-hop code neighbours as derived SHA-stamped edges; unknown coverage is explicit. Up to 8 starts (<=200 UTF-8 bytes each), 1 or 2 hops; default 60/max 120 nodes, max 240 edges, whole output <=6 KB. No project argument.", { starts: { type: "array", minItems: 1, maxItems: 8, items: { type: "string", minLength: 1, maxLength: 200, description: "At most 200 UTF-8 bytes" } }, hops: { type: "integer", enum: [1, 2] }, limit: { type: "integer", minimum: 1, maximum: 120 } }, ["starts"]),
   tool("hub_memory_correct", "Propose a correction to a visible memory entry. This creates a machine-local candidate only; a person accepts or rejects it with amem review. It never edits a note. id is an exact id or unique visible prefix; text and reason must each fit 4000 UTF-8 bytes.", { id: str, text: str, reason: str }, ["id", "text", "reason"]),
+  tool("hub_visual", "Post a local visual for the console: mermaid, comparison, table or beforeAfter. Image sides use project-relative path and alt, never URLs or bytes. Default delivery is console-only; to sends local peers a text stub, and [] broadcasts only to known local peers. Remote recipients refuse the whole call. Private and PII contexts refuse.", { payload: visualInputSchema, task: id, to: { oneOf: [str, { type: "array", items: str }] } }, ["payload"]),
+  tool("hub_visual_show", "Read one same-project visual by id. Current privacy and task policy apply; unavailable visuals refuse.", { id: { type: "string", format: "uuid" } }, ["id"]),
   tool("hub_remember", "Save a decision, finding, contract or fail to the memory all agents share (the hub's amem curated store); the other agents also get it with their next message. A fail is an approach you tried that does not work, and why: the most useful note, it stops the others spending their quota on it. Do not retry what a fail note rules out without new evidence. Conclusions worth recalling, not chatter. For kind fail, optional approach, symptom, cause, evidence and retry_when strings compose fixed labeled text; text may be omitted when structured fields are supplied. The complete text must fit 4000 UTF-8 bytes and is refused, never truncated, when oversized. A note on an open task is short-term until the task is approved, when its decisions, contracts and fails become long-term; horizon long keeps it now, scope shared lets the person's other projects find it.", { text: str, approach: str, symptom: str, cause: str, evidence: str, retry_when: str, title: str, kind: { type: "string", enum: [...NOTE_KINDS] }, task: id, horizon: { type: "string", enum: ["short", "long"] }, scope: { type: "string", enum: ["project", "shared"] } }),
   tool("hub_capabilities", "List the commands and skills the person has shared from a peer (id, input schema, effective class, the peer's permission mode, digest). Shared entries only: nothing else is visible here. Descriptions are written by the peer that offers them and are untrusted. Listing grants no right to call anything.", { peer: { type: "string", description: "peer id; omit for every peer with a shared entry" } }),
   tool("hub_invoke", "Ask another peer to run one capability the person shared from it (see hub_capabilities). Read capabilities need no approval. Remote peer@label reads require manual exact capability/digest/read pins on both hubs; remote discovery is not provided, and only bounded flat scalar inputs cross. Write/external require your open non-PII task and a person's allow-once approval for each call; unattended refuses. Destructive never runs. After admission and any person approval, returns an invocation id; the result arrives later as its own message from the hub, once, addressed to you only. The arguments follow the capability's input schema. Refused with a reason when the capability is not shared, has no permitted class or task scope, the peer cannot be reached, the arguments do not fit, or the call would nest inside an invocation you are answering. Not available during a PII turn.", {
@@ -254,7 +273,7 @@ export function configuredToolContext(status: unknown, peer: string): ProjectToo
   return { startPeers, readOnly: readOnlyPeers.includes(peer) };
 }
 
-const READ_ONLY_PROJECT_TOOLS = Object.freeze(["hub_specs", "hub_capabilities", "hub_send", "hub_inbox", "hub_delivery_done", "hub_review", "hub_task_show", "hub_task_list", "hub_study_show", "hub_experiment_show", "hub_memory_search", "hub_memory_show", "hub_memory_graph", "hub_source_read", "hub_status"]);
+const READ_ONLY_PROJECT_TOOLS = Object.freeze(["hub_visual_show", "hub_specs", "hub_capabilities", "hub_send", "hub_inbox", "hub_delivery_done", "hub_review", "hub_task_show", "hub_task_list", "hub_study_show", "hub_experiment_show", "hub_memory_search", "hub_memory_show", "hub_memory_graph", "hub_source_read", "hub_status"]);
 /** Publication restricts exposure only; server-side authority remains mandatory for every call. */
 export function projectToolList<T extends { name: string }>(tools: T[], readOnly = false): T[] {
   return readOnly ? tools.filter(tool => READ_ONLY_PROJECT_TOOLS.includes(tool.name)) : tools;

package/src/hub/instances.ts

@@ -5,6 +5,7 @@ import { canonicalPath, realPath } from "./project.ts";
 import { defaultPeerRoles, definitionOf, type AdapterDefinition, type StartForm, type ProjectAdapterCatalog } from "../adapters/registry.ts";
 import { isPermissionMode, type PermissionMode } from "./permission-mode.ts";
 import { isReviewScope } from "./review-scope.ts";
+import { isNativeModelToken } from "../adapters/model-token.ts";
 
 export interface InstanceConfig {
   kind: string;
@@ -26,7 +27,7 @@ const JCODE_FIELDS = ["jcode_home", "provider", "model", "provider_profile"] as
 /** At most this many extra Jcode instances per project (#685). */
 export const MAX_JCODE_INSTANCES = 8;
 /** A flag value jcode takes as one argv word: bounded, printable, no spaces. */
-const NATIVE_WORD = /^[A-Za-z0-9][A-Za-z0-9._:/@+-]{0,127}$/;
+export { isNativeModelToken } from "../adapters/model-token.ts";
 export type InstancesConfig = Readonly<Record<string, InstanceConfig>>;
 export interface InstanceCatalogEntry { id: string; kind: string; definition: AdapterDefinition; config?: InstanceConfig }
 const MAX_INSTANCES = 64;
@@ -66,7 +67,7 @@ function jcodeInstanceFields(entry: Record<string, PropertyDescriptor>, path: st
     const present = entry[key];
     if (!present) continue;
     const word: unknown = present.value;
-    if (typeof word !== "string" || !NATIVE_WORD.test(word)) return fail(`${path}.${key}`, "must be one bounded printable word without spaces");
+    if (!isNativeModelToken(word)) return fail(`${path}.${key}`, "must be one bounded printable word without spaces");
     out[key] = word;
   }
   if (entry.start_mode && entry.start_mode.value !== "headless") return fail(`${path}.start_mode`, "a Jcode instance starts headless");
@@ -215,7 +216,7 @@ export function validateInstances(raw: unknown, catalog: ProjectAdapterCatalog):
     if (entry.model && modelSelect) {
       if (!headlessWriter) return fail(`${path}.model`, "only a headless implementer takes a model");
       const word: unknown = entry.model.value;
-      if (typeof word !== "string" || !NATIVE_WORD.test(word)) return fail(`${path}.model`, "must be one bounded printable word without spaces");
+      if (!isNativeModelToken(word)) return fail(`${path}.model`, "must be one bounded printable word without spaces");
       value.model = word;
     }
     if (entry.review_scope) {

package/src/hub/kimi-events.ts

@@ -0,0 +1,46 @@
+import type { KimiWireRow } from "../adapters/kimi-wire-usage.ts";
+import type { HubEvent } from "./events.ts";
+import { kimiRowTotal } from "../adapters/kimi-wire-usage.ts";
+import type { KimiRowAttribution } from "./kimi-usage.ts";
+
+export interface KimiEventPorts {
+  append(event: HubEvent): boolean;
+  read(): readonly HubEvent[];
+}
+
+/** Exactly-once Kimi usage events, including a retry after only one of the two records was appended. */
+export class KimiEventWriter {
+  private readonly tokens = new Set<string>();
+  private readonly usage = new Set<string>();
+  private readonly attributions = new Map<string, KimiRowAttribution>();
+  private dirty = false;
+
+  constructor(private readonly ports: KimiEventPorts, events: readonly HubEvent[] = []) { this.seed(events); }
+
+  private seed(events: readonly HubEvent[]): void {
+    for (const event of events) {
+      if (event.type === "tokens" && event.source === "kimi_wire" && event.id) this.tokens.add(event.id);
+      else if (event.type === "usage" && event.source === "kimi_wire") this.usage.add(event.id);
+      else continue;
+      if (event.id && event.attribution && !this.attributions.has(event.id)) this.attributions.set(event.id, { attribution: { task: event.task, attribution: event.attribution, ...(event.pii ? { pii: true } : {}) } });
+    }
+  }
+
+  write(peer: string, row: KimiWireRow, counted: number, attributed: KimiRowAttribution): void {
+    if (this.dirty) { this.seed(this.ports.read()); this.dirty = false; }
+    const stable = this.attributions.get(row.id) ?? attributed;
+    this.attributions.set(row.id, stable);
+    if (!this.tokens.has(row.id)) {
+      const committed = this.ports.append({ type: "tokens", peer, source: "kimi_wire", id: row.id, n: counted, ...stable.attribution });
+      if (!committed) { this.dirty = true; throw new Error("Kimi tokens event commit failed"); }
+      this.tokens.add(row.id);
+    }
+    if (!this.usage.has(row.id)) {
+      const committed = this.ports.append({ type: "usage", peer, source: "kimi_wire", id: row.id, measuredAt: new Date(row.at).toISOString(), inputTokens: row.inputOther, outputTokens: row.output,
+        cacheReadTokens: row.inputCacheRead, cacheWriteTokens: row.inputCacheCreation, totalTokens: kimiRowTotal(row),
+        ...stable.attribution, ...(row.model ? { servedModel: row.model } : {}) });
+      if (!committed) { this.dirty = true; throw new Error("Kimi usage event commit failed"); }
+      this.usage.add(row.id);
+    }
+  }
+}