@staix/agent-hub 0.12.44 → 0.13.0

package/src/hub/hub-tools.ts

@@ -1,3 +1,4 @@
+import { redFirstSchema } from "./test-integrity.ts";
 import { SDLC_STAGES } from "./sdlc.ts";
 import { projectProfile, profileData, PROFILE_CLASS_NAMES, type ProfileName, type ProfileSelection } from "./profiles.ts";
 import { catalogSection, type CatalogRole } from "./roles.ts";
@@ -17,10 +18,26 @@ const refs = {
   additionalProperties: false,
 } as const;
 const list = (description: string) => ({ type: "array", items: str, description }) as const;
+const reviewFindings = {
+  type: "array", maxItems: 64,
+  description: "Head-bound findings; open Important findings carry across heads until explicitly fixed, false_positive or person-accepted; omission never settles them. Nits stay on their head. accepted is person-only and requires rationale. Nit count is capped by sdlc.max_nits (default 5).",
+  items: { type: "object", properties: {
+    id: { type: "string", minLength: 1, maxLength: 96, pattern: "^[A-Za-z0-9._:-]+$" },
+    pass: { type: "string", enum: ["bugs", "security", "compliance"] },
+    severity: { type: "string", enum: ["important", "nit"] },
+    path: { type: "string", minLength: 1, maxLength: 512 },
+    disposition: { type: "string", enum: ["open", "fixed", "false_positive", "accepted"] },
+    rationale: { type: "string", minLength: 1, maxLength: 2048 },
+  }, required: ["id", "pass", "severity", "disposition"], additionalProperties: false },
+} as const;
 const costPlanProperties = {
   review: { type: "object", properties: { scope: { type: "string", enum: ["none", "delta", "full"] }, reviewers: { type: "integer", minimum: 0, maximum: 8 } }, required: ["scope", "reviewers"], additionalProperties: false },
   ci: { type: "string", enum: ["focused", "full", "reuse"] },
 } as const;
+const evidencePlanProperties = {
+  proof: { type: "array", maxItems: 32, items: { type: "string", maxLength: 512 }, description: "test paths or check names planned to prove the change" },
+  risks: { type: "array", maxItems: 32, items: { type: "string", maxLength: 512 }, description: "short risks to check during implementation and review" },
+} as const;
 const plan = {
   type: "object",
   description: "what you will change, before you start. Owners of open tasks on the same files or symbols see it, and get a notice when your task is done.",
@@ -75,7 +92,7 @@ export const TASK_TOOLS: HubTool[] = [
   tool("hub_task_done", "Mark your task finished. It goes to its reviewer with your summary and refs; no duplicate hub_send chat is needed. When the project configures a check for its class, the hub runs it first and the result comes as a task message: a failed check keeps the task with you.", { id, summary: { type: "string", description: "what changed, why, and the check you ran with its result" }, refs }, ["id", "summary"]),
   tool("hub_sdlc_record", "Record artifact ids or claimed local checks on your task. This grants no authority or external-check evidence. Only its owner/reviewer or the person may record; only its reviewer/person may name a reviewed head or phase checklist. Phase evidence refs are content hashes, not external verification.", { id, receipt: { type: "object", properties: { stage: { type: "string", enum: ["spec", "plan", "implement", "review", "verify", "merge", "release"] }, repo: str, issue: id, pr: id, localHead: str, localResult: { type: "string", enum: ["passed", "failed", "unknown"] }, reviewedHead: str, phase: { type: "object", properties: { id: str, head: str, tasks: { type: "array", maxItems: 64, items: { type: "object", properties: { id, after: { type: "array", maxItems: 16, items: id } }, required: ["id", "after"], additionalProperties: false } }, criteria: { type: "array", maxItems: 32, items: { type: "object", properties: { id: str, required: { type: "boolean" }, result: { type: "string", enum: ["verified", "failed", "unverified"] }, refs: { type: "array", maxItems: 8, items: str } }, required: ["id", "required", "result", "refs"], additionalProperties: false } } }, required: ["id", "tasks", "criteria"], additionalProperties: false } }, additionalProperties: false } }, ["id", "receipt"]),
   tool("hub_task_list", "The task board. PII tasks show as [pii].", { state: { type: "string", enum: ["proposed", "in_progress", "in_review", "approved", "changes_requested", "cancelled"] }, ready: { type: "boolean", description: "only proposed tasks with nothing left to wait for" } }),
-  tool("hub_review", "Give your verdict on a task you were asked to review: map the changed signatures and call sites to the task's plan or detail, read the check result (hub_task_show has it, with the done summary), and list what is unmet. The verdict notifies the task owner; no duplicate hub_send chat is needed. Consecutive changes_requested verdicts (three by default, `tasks.escalate_after`) move the task to another peer.", { id, head: { type: "string", description: "full SHA actually reviewed; enforce binds approval to the current PR head" }, verdict: { type: "string", enum: ["approved", "changes_requested"] }, note: str, unmet: { type: "array", items: str, description: "each requirement of the plan or detail that the change does not meet" }, coverage: { type: "object", description: "the review brief's reviewable paths you read (reviewed) and any you did not (skipped, each with a reason); in enforce an approval must account for every one", properties: { reviewed: { type: "array", items: str }, skipped: { type: "array", items: { type: "object", properties: { path: str, reason: str }, required: ["path", "reason"] } } } } }, ["id", "verdict"]),
+  tool("hub_review", "Give your verdict on a task you were asked to review: map the changed signatures and call sites to the task's plan or detail, read the check result (hub_task_show has it, with the done summary), and list what is unmet. The verdict notifies the task owner; no duplicate hub_send chat is needed. Consecutive changes_requested verdicts (three by default, `tasks.escalate_after`) move the task to another peer.", { id, head: { type: "string", description: "full SHA actually reviewed; enforce binds approval to the current PR head" }, findings: reviewFindings, verdict: { type: "string", enum: ["approved", "changes_requested"] }, note: str, unmet: { type: "array", items: str, description: "each requirement of the plan or detail that the change does not meet" }, coverage: { type: "object", description: "the review brief's reviewable paths you read (reviewed) and any you did not (skipped, each with a reason); in enforce an approval must account for every one", properties: { reviewed: { type: "array", items: str }, skipped: { type: "array", items: { type: "object", properties: { path: str, reason: str }, required: ["path", "reason"] } } } } }, ["id", "verdict"]),
   tool("hub_checkpoint", "Answer a checkpoint request from the hub (quota or context window pressure): what you were doing, what is half done, what whoever continues must know. Write the same to .agenthub/checkpoint.md first if you can.", { summary: str, request_id: { type: "string", description: "The request id supplied by a context checkpoint request; required for context checkpoints" } }, ["summary"]),
   tool("hub_memory_search", "Search daemon-scoped visible memory, fails first. Query <=200 UTF-8 bytes; default 8, max 20 lines; whole output <=4 KB. Incomplete excerpts are marked. No project argument.", { query: { type: "string", maxLength: 200, description: "At most 200 UTF-8 bytes, enforced by the daemon" }, limit: { type: "integer", minimum: 1, maximum: 20 } }, ["query"]),
   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"]),
@@ -175,25 +192,46 @@ export function profileTaskTools(profile: ProfileSelection = "dev", stages?: rea
       if (criteria) {
         const { phase, ...current } = fields as { phase: { properties: Record<string, unknown> } } & Record<string, unknown>;
         const { tasks: _retiredImport, ...checklist } = phase.properties;
-        fields = { ...current, criteria: { ...phase, properties: checklist, required: ["id", "criteria"] } };
+        fields = { ...current, redFirst: redFirstSchema, criteria: { ...phase, properties: checklist, required: ["id", "criteria"] } };
       }
       properties.receipt = { ...receipt, properties: fields };
     }
     if (customProfile && tool.name === "hub_task_propose") properties.class = { type: "string", enum: [...new Set([...Object.keys(data.classes), ...PROFILE_CLASS_NAMES.filter(v => projectProfile("dev").classes[v])])] };
-    if (customProfile && properties.plan && tool.name !== "hub_task_accept") properties.plan = { ...plan, properties: Object.fromEntries(data.plan_keys.map(key => [key, plan.properties[key as keyof typeof plan.properties] ?? list(key === "sections" ? "document heading anchors, such as report.md#methods" : key === "sources" ? "citation ids, DOI or source URL ids" : "short claim ids to verify")])) };
+    if (customProfile && properties.plan && tool.name !== "hub_task_accept") properties.plan = { ...plan, properties: { ...Object.fromEntries(data.plan_keys.map(key => [key, plan.properties[key as keyof typeof plan.properties] ?? list(key === "sections" ? "document heading anchors, such as report.md#methods" : key === "sources" ? "citation ids, DOI or source URL ids" : "short claim ids to verify")])) } };
+    if (customProfile && tool.name === "hub_task_done" && data.name !== "dev") {
+      const summaryProp = properties.summary as { type: string; description: string };
+      properties.summary = {
+        ...summaryProp,
+        description: data.name === "research" || data.name === "writing"
+          ? "changed deliverables, provenance, checks and unknowns"
+          : "what changed, why, and the check or verification you ran with its result",
+      };
+    }
     if (customProfile && tool.name === "hub_backlog_split") {
       const parts = properties.parts as { items: { properties: Record<string, unknown> } };
-      const selectedPlan = { ...plan, properties: Object.fromEntries(data.plan_keys.map(key => [key, plan.properties[key as keyof typeof plan.properties] ?? list(key === "sections" ? "document heading anchors, such as report.md#methods" : key === "sources" ? "citation ids, DOI or source URL ids" : "short claim ids to verify")])) };
+      const selectedPlan = { ...plan, properties: { ...Object.fromEntries(data.plan_keys.map(key => [key, plan.properties[key as keyof typeof plan.properties] ?? list(key === "sections" ? "document heading anchors, such as report.md#methods" : key === "sources" ? "citation ids, DOI or source URL ids" : "short claim ids to verify")])) } };
       properties.parts = { ...parts, items: { ...parts.items, properties: { ...parts.items.properties, plan: selectedPlan } } };
     }
     if (criteria && properties.plan) {
       const current = properties.plan as { properties: Record<string, unknown> };
-      properties.plan = { ...current, properties: { ...current.properties, ...costPlanProperties } };
+      properties.plan = { ...current, properties: { ...current.properties, ...costPlanProperties, ...evidencePlanProperties } };
     }
     if (criteria && tool.name === "hub_backlog_split") {
       const parts = properties.parts as { items: { properties: { plan: { properties: Record<string, unknown> } } } };
-      properties.parts = { ...parts, items: { ...parts.items, properties: { ...parts.items.properties, plan: { ...parts.items.properties.plan, properties: { ...parts.items.properties.plan.properties, ...costPlanProperties } } } } };
+      properties.parts = { ...parts, items: { ...parts.items, properties: { ...parts.items.properties, plan: { ...parts.items.properties.plan, properties: { ...parts.items.properties.plan.properties, ...costPlanProperties, ...evidencePlanProperties } } } } };
+    }
+    let description = tool.description;
+    if (customProfile && tool.name === "hub_task_propose") {
+      description = tool.description + ` Selected profile ${data.name}: ${Object.keys(data.classes).join(", ")}. Routing uses their existing base classes.`;
+    } else if (customProfile && tool.name === "hub_review" && data.name !== "dev") {
+      const reviewAction = data.name === "research" || data.name === "writing"
+        ? "assess scope, provenance and unsupported claims against the task's plan or detail"
+        : "assess the deliverables against the task's plan or detail";
+      description = `Give your verdict on a task you were asked to review: ${reviewAction}, read the check result (hub_task_show has it, with the done summary), and list what is unmet. The verdict notifies the task owner; no duplicate hub_send chat is needed. Consecutive changes_requested verdicts (three by default, \`tasks.escalate_after\`) move the task to another peer.`;
+    } else if (customProfile && tool.name === "hub_task_done" && data.name !== "dev") {
+      const summaryLabel = data.name === "research" || data.name === "writing" ? "deliverables, provenance and checks" : "deliverables and checks";
+      description = `Mark your task finished. It goes to its reviewer with your summary (${summaryLabel}) and refs; no duplicate hub_send chat is needed. When the project configures a check for its class, the hub runs it first and the result comes as a task message: a failed check keeps the task with you.`;
     }
-    return { ...tool, ...(customProfile && tool.name === "hub_task_propose" ? { description: tool.description + ` Selected profile ${data.name}: ${Object.keys(data.classes).join(", ")}. Routing uses their existing base classes.` } : {}), inputSchema: { ...tool.inputSchema, properties } };
+    return { ...tool, description, inputSchema: { ...tool.inputSchema, properties } };
   });
 }

package/src/hub/inbox-polling.ts

@@ -0,0 +1,25 @@
+/** Advisory only: reading an inbox is never refused. */
+export class InboxPolling {
+  // ponytail: counters reset on restart; persist only if restarts hide real polling.
+  private readonly streaks = new Map<string, { reads: number[]; noticed: boolean }>();
+
+  reset(peer: string): void { this.streaks.delete(peer); }
+
+  read(peer: string, empty: boolean, assigned: boolean, now: number): { count: number; minutes: number; notice: boolean } | undefined {
+    if (!empty || assigned) { this.reset(peer); return; }
+    let streak = this.streaks.get(peer);
+    const last = streak?.reads.at(-1);
+    if (!streak || last === undefined || now < last || now - last > 10 * 60_000) {
+      streak = { reads: [], noticed: false };
+      this.streaks.set(peer, streak);
+    }
+    streak.reads = streak.reads.filter(at => now - at <= 10 * 60_000);
+    // ponytail: advice counts at most 64 recent reads; use time buckets if full high-rate counts become useful.
+    if (streak.reads.length === 64) streak.reads.shift();
+    streak.reads.push(now);
+    if (streak.reads.length < 3) return;
+    const notice = !streak.noticed;
+    streak.noticed = true;
+    return { count: streak.reads.length, minutes: Math.floor((now - streak.reads[0]!) / 60_000), notice };
+  }
+}

package/src/hub/instance-config.ts

@@ -1,6 +1,9 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import { createProjectAdapterCatalog, defaultPeerRoles, definitionOf, type ProjectAdapterCatalog } from "../adapters/registry.ts";
+import { createProjectAdapterCatalog, defaultPeerRoles, definitionOf, type ProjectAdapterCatalog, type AdapterDefinition } from "../adapters/registry.ts";
+import { readAdapterModuleDeclarations, type AdapterModuleDeclaration } from "../adapters/external-modules.ts";
+import { externalMetadataDefinitions } from "../adapters/external-metadata.ts";
+import { readControl, stateDirFor } from "./control-client.ts";
 import { conductorPeer } from "./conductor.ts";
 import { configRefusal } from "./config-trust.ts";
 import { validateInstances, type InstancesConfig } from "./instances.ts";
@@ -18,13 +21,15 @@ export function readInstanceConfigLayers(cwd: string): InstanceConfigLayer[] {
 
 /** Declaration authority is file provenance, never a suffix or a claim made by a native child. */
 export interface InstanceRoleConfig {
+  adapter_modules?: readonly AdapterModuleDeclaration[];
   adapters?: Readonly<Record<string, import("../adapters/configured-acp.ts").ConfiguredAcpAdapterConfig>>;
   instances?: InstancesConfig;
   catalog: ProjectAdapterCatalog;
   ignored: string[];
 }
-export function readInstanceConfig(cwd: string, layers: readonly InstanceConfigLayer[] = readInstanceConfigLayers(cwd)): InstanceRoleConfig {
-  const ignored: string[] = [];
+export function readInstanceConfig(cwd: string, layers: readonly InstanceConfigLayer[] = readInstanceConfigLayers(cwd), externalDefinitions?: readonly AdapterDefinition[]): InstanceRoleConfig {
+  const moduleConfig = readAdapterModuleDeclarations(cwd, layers);
+  const ignored: string[] = [...moduleConfig.ignored];
   let adapters: Readonly<Record<string, import("../adapters/configured-acp.ts").ConfiguredAcpAdapterConfig>> | undefined, rawInstances: unknown;
   for (const { name, raw } of layers) {
     const keys = ["adapters", "instances"].filter(key => raw[key] !== undefined);
@@ -34,9 +39,16 @@ export function readInstanceConfig(cwd: string, layers: readonly InstanceConfigL
     if (raw.adapters !== undefined) adapters = raw.adapters as Readonly<Record<string, import("../adapters/configured-acp.ts").ConfiguredAcpAdapterConfig>>;
     if (raw.instances !== undefined) rawInstances = raw.instances;
   }
-  const catalog = createProjectAdapterCatalog(adapters);
+  let external = externalDefinitions;
+  if (external === undefined) {
+    // Metadata discovery is optional: retained recovery receipts may name a project that no longer exists.
+    let metadata;
+    try { metadata = readControl(stateDirFor(cwd))?.externalAdapters; } catch { /* no running catalog available */ }
+    external = externalMetadataDefinitions(metadata);
+  }
+  const catalog = createProjectAdapterCatalog(adapters, external);
   const instances = validateInstances(rawInstances, catalog);
-  return { ...(adapters !== undefined ? { adapters } : {}), ...(Object.keys(instances).length ? { instances } : {}), catalog, ignored };
+  return { ...(moduleConfig.modules.length ? { adapter_modules: moduleConfig.modules } : {}), ...(adapters !== undefined ? { adapters } : {}), ...(Object.keys(instances).length ? { instances } : {}), catalog, ignored };
 }
 
 /** Capture ordinary role policy and trusted instance declarations together, without loading daemon configuration. */

package/src/hub/instance-execution.ts

@@ -6,17 +6,29 @@ import { realPath } from "./project.ts";
 import { validateInstances, type InstancesConfig } from "./instances.ts";
 
 const refuse = (reason: string): never => { throw new Error(`instance execution workspace refused: ${reason}`); };
-const GIT_TIMEOUT_MS = 5000, GIT_OUTPUT_BYTES = 1024 * 1024;
-function git(cwd: string, args: string[]): string {
-  const result = hubGitSync(["-C", cwd, ...args], { encoding: "utf8", timeout: GIT_TIMEOUT_MS, maxBuffer: GIT_OUTPUT_BYTES });
-  if (result.error || result.status !== 0) return refuse("Git workspace evidence unavailable");
-  return result.stdout;
+// #225: this runs synchronously on the daemon's event loop (an extra-instance start, turn_revert), and a resolution makes up to four git
+// calls. One allowance covers all of them, so the loop is held for at most GIT_BUDGET_MS in git however many calls remain; a call that
+// finds the allowance spent refuses without starting git. ponytail: the calls stay synchronous because the CLI and recovery callers are
+// synchronous by contract; an async twin for the two daemon call sites is the upgrade if a typical resolution ever costs more than a few ms
+// (measured about 15 ms for four calls on a warm local repository).
+const GIT_BUDGET_MS = 5000, GIT_OUTPUT_BYTES = 1024 * 1024;
+type Gitter = (cwd: string, args: string[]) => string;
+function gitWithin(budgetMs: number, clock: () => number, run: typeof hubGitSync = hubGitSync): Gitter {
+  const deadline = clock() + budgetMs;
+  return (cwd, args) => {
+    const left = Math.floor(deadline - clock());
+    if (left <= 0) return refuse("Git workspace evidence unavailable");
+    const result = run(["-C", cwd, ...args], { encoding: "utf8", timeout: left, maxBuffer: GIT_OUTPUT_BYTES });
+    if (result.error || result.status !== 0) return refuse("Git workspace evidence unavailable");
+    return result.stdout;
+  };
 }
-const commonDirectory = (cwd: string): string => realPath(git(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]).replace(/\n$/, ""));
+const commonDirectory = (git: Gitter, cwd: string): string => realPath(git(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]).replace(/\n$/, ""));
 
 /** Point-in-time read only. No worktree is created, repaired or chosen implicitly. */
-export function resolveInstanceExecutionCwd(projectRoot: string, id: string, declarations: InstancesConfig | undefined, roles: readonly string[], adapterCatalog: ProjectAdapterCatalog): string {
+export function resolveInstanceExecutionCwd(projectRoot: string, id: string, declarations: InstancesConfig | undefined, roles: readonly string[], adapterCatalog: ProjectAdapterCatalog, budgetMs = GIT_BUDGET_MS, clock: () => number = () => performance.now(), run: typeof hubGitSync = hubGitSync): string {
   if (adapterCatalog.definitionOf(id)) return projectRoot;
+  const git = gitWithin(budgetMs, clock, run);
   const declaration = validateInstances(declarations, adapterCatalog)[id];
   if (!declaration) return refuse("extra instance is not declared");
   const implementer = roles.includes("implementer");
@@ -41,7 +53,7 @@ export function resolveInstanceExecutionCwd(projectRoot: string, id: string, dec
     try { return realPath(path) === cwd; } catch { return false; }
   });
   if (matches.length !== 1 || matches[0]!.some(field => field === "prunable" || field.startsWith("prunable "))) return refuse("directory is not an available registered project worktree");
-  if (commonDirectory(root) !== commonDirectory(cwd)) return refuse("worktree belongs to a different Git repository");
+  if (commonDirectory(git, root) !== commonDirectory(git, cwd)) return refuse("worktree belongs to a different Git repository");
   const top = git(cwd, ["rev-parse", "--show-toplevel"]).replace(/\n$/, "");
   if (realPath(top) !== cwd) return refuse("directory is not the registered worktree root");
   if (implementer && !matches[0]!.some(field => field.startsWith("branch refs/heads/") && field.length > "branch refs/heads/".length)) return refuse("an implementer worktree requires an attached branch");

package/src/hub/instances.ts

@@ -1,4 +1,7 @@
 import { types } from "node:util";
+import { statSync } from "node:fs";
+import { dirname, isAbsolute, resolve, sep } from "node:path";
+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";
 
@@ -10,7 +13,17 @@ export interface InstanceConfig {
   review_mode?: "fresh";
   worktree?: string;
   readOnly?: boolean;
+  /** Jcode instances only (#685): their own native data home, and optional model selection. Machine-local, never editable from settings. */
+  jcode_home?: string;
+  provider?: string;
+  model?: string;
+  provider_profile?: string;
 }
+const JCODE_FIELDS = ["jcode_home", "provider", "model", "provider_profile"] as const;
+/** 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 type InstancesConfig = Readonly<Record<string, InstanceConfig>>;
 export interface InstanceCatalogEntry { id: string; kind: string; definition: AdapterDefinition; config?: InstanceConfig }
 const MAX_INSTANCES = 64;
@@ -41,6 +54,58 @@ function roles(value: unknown, field: string): string[] {
   return out;
 }
 
+/** The Jcode-only fields of one declaration (#685). Only the validated values are copied; nothing is read twice. */
+function jcodeInstanceFields(entry: Record<string, PropertyDescriptor>, path: string): Partial<InstanceConfig> {
+  const home: unknown = entry.jcode_home?.value;
+  if (typeof home !== "string" || !isAbsolute(home) || !home.trim() || Buffer.byteLength(home) > 4096 || /\p{Cc}/u.test(home)) return fail(`${path}.jcode_home`, "is required: a nonempty control-free absolute path of at most 4096 UTF-8 bytes, other than the base Jcode's home");
+  const out: Partial<InstanceConfig> = { jcode_home: home };
+  for (const key of ["provider", "model", "provider_profile"] as const) {
+    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");
+    out[key] = word;
+  }
+  if (entry.start_mode && entry.start_mode.value !== "headless") return fail(`${path}.start_mode`, "a Jcode instance starts headless");
+  return out;
+}
+
+/**
+ * The directory a home names, as the disk sees it (#685 review): symlinks and system aliases (`/tmp` and `/private/tmp`) resolved with
+ * `realPath` (never `realpathSync`, which Bun fails on a backslash path), and for a home that does not exist yet the nearest existing
+ * ancestor resolved the same way. Compared case-folded when the volume folds case, so a case-only alias is the same home.
+ */
+function canonicalHome(home: string): { path: string; key: string; identity?: string } {
+  let path: string;
+  try { path = realPath(home); } catch { path = canonicalPath(home); }
+  const stat = (target: string) => { try { return statSync(target); } catch { return undefined; } };
+  let existing = path;
+  while (!stat(existing) && dirname(existing) !== existing) existing = dirname(existing);
+  const info = stat(path), anchor = stat(existing);
+  const swapped = existing.replace(/[A-Za-z]/g, letter => letter === letter.toLowerCase() ? letter.toUpperCase() : letter.toLowerCase());
+  const alias = swapped !== existing ? stat(swapped) : undefined;
+  const folds = !!anchor && !!alias && alias.ino === anchor.ino && alias.dev === anchor.dev;
+  return { path, key: folds ? path.toLowerCase() : path, ...(info ? { identity: `${info.dev}:${info.ino}` } : {}) };
+}
+/**
+ * One native data home per Jcode (#685): an instance may not use the base Jcode's home, another instance's, or one nested
+ * inside either (their stores would overlap), however the path is spelled: a symlink, a system alias or a case-only alias of one
+ * is the same home. Run once with the loaded base `jcode_home`.
+ */
+export function checkJcodeInstanceHomes(declarations: InstancesConfig | undefined, baseHome: string): void {
+  const homes: { id: string; key: string; identity?: string }[] = [{ id: "the base Jcode", ...canonicalHome(baseHome) }];
+  for (const [id, config] of Object.entries(declarations ?? {})) {
+    if (config.jcode_home === undefined) continue; // only a native-home kind carries one
+    const home = canonicalHome(config.jcode_home);
+    for (const other of homes) {
+      const label = other.id === "the base Jcode" ? "base" : other.id;
+      if (home.key === other.key || (home.identity !== undefined && home.identity === other.identity)) return fail(`instances.${id}.jcode_home`, other.id === "the base Jcode" ? "must differ from the base Jcode's home" : `is the same home as ${label}`);
+      if (home.key.startsWith(`${other.key}${sep}`) || other.key.startsWith(`${home.key}${sep}`)) return fail(`instances.${id}.jcode_home`, `is nested inside or around ${other.id === "the base Jcode" ? "the base Jcode's home" : `${label}'s home`}`);
+    }
+    homes.push({ id, ...home });
+  }
+}
+
 /** Declaration support is explicit policy, independent of the native MCP binding mechanism. */
 export function supportsHeadlessInstances(definition: AdapterDefinition): boolean {
   return definition.instances?.mode === "headless" && !!definition.start.create && definition.start.forms.includes("headless");
@@ -57,15 +122,19 @@ export function validateInstances(raw: unknown, catalog: ProjectAdapterCatalog):
   const result: Record<string, InstanceConfig> = Object.create(null);
   if (raw === undefined) return Object.freeze(result);
   const declarations = fields(raw, "instances");
+  let jcodeCount = 0;
   if (Object.keys(declarations).length > MAX_INSTANCES) return fail("instances", "at most 64 extra instances are supported");
   for (const [id, descriptor] of Object.entries(declarations)) {
     if (!PEER_ID.test(id) || RESERVED.has(id) || resolve(id)) return fail("instances", "ids must be nonreserved extra instance ids, not builtin ids");
     const path = `instances.${id}`, entry = fields(descriptor.value, path);
-    if (Object.keys(entry).some(key => !["kind", "roles", "start_mode", "permission_mode", "worktree", "review_mode", "readOnly"].includes(key))) return fail(path, "unsupported field");
+    const declaredKind: unknown = entry.kind?.value;
+    const jcodeFields = typeof declaredKind === "string" && resolve(declaredKind)?.instances?.nativeHome === true;
+    if (Object.keys(entry).some(key => !["kind", "roles", "start_mode", "permission_mode", "worktree", "review_mode", "readOnly", ...(jcodeFields ? JCODE_FIELDS : [])].includes(key))) return fail(path, "unsupported field");
     const kind: unknown = entry.kind?.value;
     if (typeof kind !== "string") return fail(`${path}.kind`, "must name a native kind");
     const definition = resolve(kind), prefix = `${kind}-`;
-    if (!definition) return fail(`${path}.kind`, "unknown native kind");
+    if (!definition) return fail(`${path}.kind`, "unknown native kind (external adapter instances are unsupported in A4)");
+    if (catalog.externalDefinitions.some(item => item.kind === kind)) return fail(`${path}.kind`, "external adapter instances are unsupported in A4");
     if (!id.startsWith(prefix) || !/^[a-z0-9][a-z0-9-]*$/.test(id.slice(prefix.length))) return fail(path, "id must be <kind>-<name>");
     const declaredRoles = entry.roles ? roles(entry.roles.value, `${path}.roles`) : [];
     const reviewer = (definition.reviewerVariant ?? definition).reviewer;
@@ -101,6 +170,10 @@ export function validateInstances(raw: unknown, catalog: ProjectAdapterCatalog):
       if (entry.readOnly.value && entry.permission_mode) return fail(`${path}.permission_mode`, "read-only instances cannot select a permission mode");
     }
     const value: InstanceConfig = { kind, ...(entry.review_mode ? { review_mode: "fresh" as const } : {}) };
+    if (jcodeFields) {
+      if (++jcodeCount > MAX_JCODE_INSTANCES) return fail("instances", `at most ${MAX_JCODE_INSTANCES} extra Jcode instances are supported per project`);
+      Object.assign(value, jcodeInstanceFields(entry, path));
+    }
     if (entry.readOnly) value.readOnly = entry.readOnly.value as boolean;
     if (entry.roles) { value.roles = roles(entry.roles.value, `${path}.roles`); Object.freeze(value.roles); }
     if (entry.start_mode) {

package/src/hub/peers.ts

@@ -1,4 +1,5 @@
 import type { Envelope, EnvelopeOpts, PeerId, PeerState } from "./envelope.ts";
+import type { PermissionMode } from "./permission-mode.ts";
 
 export interface DeliveryReceipt {
   id: string;
@@ -11,6 +12,14 @@ export interface DeliveryReceipt {
 export interface PeerAdapter {
   readonly id: PeerId;
   readonly state: PeerState;
+  /** Host-observed native session identity. An absent port permits owner-token fallback; undefined means unknown. */
+  readonly sessionGeneration?: string | number;
+  /** Defaults to fencing checkpoints when the generation port exists; native legacy exceptions opt out explicitly. */
+  readonly checkpointUsesSessionGeneration?: boolean;
+  /** Effective native approval state; absent peers retain the hub-managed choice. */
+  readonly permissionModeState?: PermissionMode | "unknown" | "unmanaged";
+  /** Resolve only after native acknowledgement. This changes approval frequency, never the sandbox. */
+  setPermissionMode?(mode: PermissionMode): Promise<void>;
   /** A peer the hub drives itself (Pi, the local worker). It cannot be trusted to rate its own urgency: the bus caps it. */
   readonly hubNative?: boolean;
   /** Never handed a delivery: its queue waits for `Bus.pull` (a Claude session that cannot show channel pushes, issue #205). */

package/src/hub/plan-conformance.ts

@@ -0,0 +1,83 @@
+import { createHash } from "node:crypto";
+import { types } from "node:util";
+
+export interface PlanConformance {
+  state: "covered" | "departure" | "unknown";
+  head?: string;
+  outside: string[];
+  untouched: string[];
+}
+/** Repository-relative literal names only. A star is a filename character, never a glob operator. */
+function pathIdentity(raw: unknown): string | undefined {
+  if (typeof raw !== "string" || !raw || raw.length > 1000 || /[\p{Cc}\p{Cf}]/u.test(raw)
+    || raw.startsWith("/") || raw.startsWith("\\") || /^[A-Za-z]:/.test(raw)) return undefined;
+  const path = raw.replace(/^(\.\/)+/, "").replace(/\/{2,}/g, "/").replace(/\/+$/, "") || ".";
+  if (path === "." || path.split("/").some(part => part === "." || part === "..")) return undefined;
+  return path;
+}
+const covers = (planned: string, changed: string) => changed === planned || changed.startsWith(`${planned}/`);
+
+/** A complete file inventory is independent of any plan or coverage claim. */
+export function completePlanInventory(evidence: { head: string; paths: readonly string[]; pathsComplete?: boolean; typesComplete?: boolean } | undefined): string[] | undefined {
+  if (!evidence || typeof evidence.head !== "string" || !/^[a-f0-9]{40}$/.test(evidence.head) || evidence.pathsComplete !== true || evidence.typesComplete !== true || !Array.isArray(evidence.paths) || evidence.paths.length > 1000) return undefined;
+  const paths: string[] = [], seen = new Set<string>();
+  for (const raw of evidence.paths) {
+    const path = pathIdentity(raw); if (path === undefined || seen.has(path)) return undefined;
+    seen.add(path); paths.push(path);
+  }
+  return paths;
+}
+
+/** Compare current complete PR file metadata with the current plan; never inspect patches or the filesystem. */
+export function planConformance(planPaths: readonly string[] | undefined, evidence: { head: string; paths: readonly string[]; pathsComplete?: boolean; typesComplete?: boolean } | undefined): PlanConformance {
+  const head = typeof evidence?.head === "string" && /^[a-f0-9]{40}$/.test(evidence.head) ? evidence.head : undefined;
+  const unknown: PlanConformance = { state: "unknown", ...(head ? { head } : {}), outside: [], untouched: [] };
+  const changed = completePlanInventory(evidence);
+  if (!head || changed === undefined
+    || !Array.isArray(planPaths) || !planPaths.length || planPaths.length > 1000) return unknown;
+  const planned: string[] = [], seenPlan = new Set<string>();
+  for (const raw of planPaths) {
+    const path = pathIdentity(raw); if (path === undefined) return unknown;
+    if (!seenPlan.has(path)) { seenPlan.add(path); planned.push(path); }
+  }
+  const outside = changed.filter(path => !planned.some(plan => covers(plan, path)));
+  const untouched = planned.filter(plan => !changed.some(path => covers(plan, path)));
+  return { state: outside.length ? "departure" : "covered", head, outside, untouched };
+}
+
+/** Hash plain plan data without invoking accessors/toJSON; object key order is immaterial, list order is not. */
+export function planFingerprint(plan: unknown): string {
+  const seen = new Set<object>();
+  const fail = (): never => { throw new Error("invalid plan fingerprint data"); };
+  const encode = (value: unknown, depth: number): string => {
+    if (depth > 64) return fail();
+    if (value === undefined) return "undefined";
+    if (value === null || typeof value === "string" || typeof value === "boolean") return JSON.stringify(value);
+    if (typeof value === "number") return Number.isFinite(value) ? JSON.stringify(value) : fail();
+    if (typeof value !== "object" || types.isProxy(value) || seen.has(value)) return fail();
+    seen.add(value);
+    try {
+      if (Array.isArray(value)) {
+        const descriptors = Object.getOwnPropertyDescriptors(value);
+        if (Reflect.ownKeys(descriptors).length !== value.length + 1) return fail();
+        return "[" + Array.from({ length: value.length }, (_, index) => {
+          const descriptor = descriptors[String(index)];
+          return descriptor && Object.hasOwn(descriptor, "value") ? encode(descriptor.value, depth + 1) : fail();
+        }).join(",") + "]";
+      }
+      if (![Object.prototype, null].includes(Object.getPrototypeOf(value))) return fail();
+      const keys = Reflect.ownKeys(value); if (keys.some(key => typeof key !== "string")) return fail();
+      return "{" + (keys as string[]).sort().map(key => {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key)!;
+        if (!Object.hasOwn(descriptor, "value") || !descriptor.enumerable) return fail();
+        return JSON.stringify(key) + ":" + encode(descriptor.value, depth + 1);
+      }).join(",") + "}";
+    } finally { seen.delete(value); }
+  };
+  return createHash("sha256").update(encode(plan, 0)).digest("hex");
+}
+
+/** Approval blockers only; untouched planned files are advisory. */
+export function planConformanceBlockers(plan: (PlanConformance & { accepted?: boolean }) | undefined): string[] {
+  return !plan ? [] : plan.state === "unknown" ? ["plan conformance unknown"] : plan.state === "departure" && !plan.accepted ? ["plan conformance: changed files outside the plan"] : [];
+}

package/src/hub/profiles.ts

@@ -10,6 +10,7 @@ export type ProfileName = (typeof PROFILE_NAMES)[number];
 export interface ProjectProfile {
   name: string; classes: Record<string, string>; plan_keys: string[]; role_text: Record<string, string>;
   catalog_roles: Record<string, string[]>; agents: string; example_checks: string[];
+  review_checklist?: string[];
 }
 const PROFILES: Record<ProfileName, ProjectProfile> = { dev, research, writing, general };
 export function profileName(raw: unknown): ProfileName {
@@ -34,10 +35,10 @@ export function resolveProfile(raw?: unknown, overrides?: unknown): ProjectProfi
   const original = projectProfile(raw);
   if (overrides === undefined) return original;
   if (!overrides || typeof overrides !== "object" || Array.isArray(overrides)) throw new Error("profile_overrides must be an object");
-  const data = overrides as Record<string, unknown>, allowed = new Set(["classes", "plan_keys", "role_text", "catalog_roles", "agents", "example_checks"]);
+  const data = overrides as Record<string, unknown>, allowed = new Set(["classes", "plan_keys", "role_text", "catalog_roles", "agents", "example_checks", "review_checklist"]);
   if (Object.keys(data).some(key => !allowed.has(key))) throw new Error("unknown profile override field");
   if (!Object.keys(data).length) return original;
-  const result: ProjectProfile = { ...original, classes: { ...original.classes }, plan_keys: [...original.plan_keys], role_text: { ...original.role_text }, catalog_roles: Object.fromEntries(Object.entries(original.catalog_roles).map(([peer, ids]) => [peer, [...ids]])), example_checks: [...original.example_checks] };
+  const result: ProjectProfile = { ...original, classes: { ...original.classes }, plan_keys: [...original.plan_keys], role_text: { ...original.role_text }, catalog_roles: Object.fromEntries(Object.entries(original.catalog_roles).map(([peer, ids]) => [peer, [...ids]])), example_checks: [...original.example_checks], ...(original.review_checklist ? { review_checklist: [...original.review_checklist] } : {}) };
   const text = (value: unknown, cap: number): string => { if (typeof value !== "string" || value.length > cap) throw new Error("profile text is missing or oversized"); return sanitize(value); };
   if (data.classes !== undefined) {
     if (!data.classes || typeof data.classes !== "object" || Array.isArray(data.classes) || Object.keys(data.classes).length > 32) throw new Error("profile classes must be a bounded base-class map");
@@ -63,6 +64,10 @@ export function resolveProfile(raw?: unknown, overrides?: unknown): ProjectProfi
     if (!Array.isArray(data.example_checks) || data.example_checks.length > 16) throw new Error("profile example_checks must be a bounded display list");
     result.example_checks = data.example_checks.map(value => text(value, 2000));
   }
+  if (data.review_checklist !== undefined) {
+    if (!Array.isArray(data.review_checklist) || !data.review_checklist.length || data.review_checklist.length > 16 || data.review_checklist.some(value => typeof value !== "string" || !value.trim() || value.length > 500)) throw new Error("profile review_checklist must be bounded checklist lines");
+    result.review_checklist = data.review_checklist.map(value => sanitize(value.trim()));
+  }
   return result;
 }
 

package/src/hub/release-worktree.ts

@@ -0,0 +1,56 @@
+import { createHash } from "node:crypto";
+import { lstatSync, readFileSync, readlinkSync } from "node:fs";
+import { dirname, relative, resolve } from "node:path";
+import type { ReleaseGit } from "./sdlc-release.ts";
+
+/** Filter-free tracked checkout comparison. Unknown or transformed content refuses. */
+// ponytail: 4096 entries, 4 MiB/file, 32 MiB total and 250 ms; larger/gitlink/transformed checkouts require a future bounded artifact attestation.
+export function releaseTrackedClean(root: string, git: ReleaseGit): boolean {
+  const start = performance.now(), deadline = () => performance.now() - start <= 250;
+  const run = (args: string[]) => {
+    if (!deadline()) return;
+    const result = git(args);
+    return deadline() && result.code === 0 && Buffer.byteLength(result.stdout) <= 2 * 1024 * 1024 ? result.stdout : undefined;
+  };
+  try {
+    const base = resolve(root);
+    if (!lstatSync(base).isDirectory() || lstatSync(base).isSymbolicLink()) return false;
+    if (run(["diff-index", "--cached", "--quiet", "--no-ext-diff", "--no-textconv", "HEAD", "--"]) === undefined) return false;
+    const inventory = run(["ls-files", "--stage", "-z"]);
+    if (inventory === undefined || inventory && !inventory.endsWith("\0")) return false;
+    const entries = inventory ? inventory.slice(0, -1).split("\0") : [];
+    if (entries.length > 4096) return false;
+    let total = 0;
+    for (const entry of entries) {
+      if (!deadline()) return false;
+      const match = /^([0-7]{6}) ([0-9a-f]{40}) ([0-3])\t([\s\S]+)$/.exec(entry);
+      if (!match) return false;
+      const [, mode, oid, stage, name] = match;
+      if (stage !== "0" || !["100644", "100755", "120000"].includes(mode!)) return false;
+      if (!name || name.length > 4096 || name.startsWith("/") || name.includes("\\") || name.split("/").some(part => !part || part === "." || part === "..") || /[\p{Cc}]/u.test(name)) return false;
+      const file = resolve(base, name), within = relative(base, file);
+      if (!within || within === ".." || within.startsWith("../")) return false;
+      for (let parent = dirname(file); parent !== base; parent = dirname(parent)) {
+        if (!deadline()) return false;
+        const info = lstatSync(parent);
+        if (!info.isDirectory() || info.isSymbolicLink()) return false;
+      }
+      const before = lstatSync(file);
+      if (before.size > 4 * 1024 * 1024 || total + before.size > 32 * 1024 * 1024) return false;
+      let bytes: Buffer;
+      if (mode === "120000") {
+        if (!before.isSymbolicLink()) return false;
+        bytes = readlinkSync(file, { encoding: "buffer" });
+      } else {
+        if (!before.isFile() || before.isSymbolicLink() || !!(before.mode & 0o111) !== (mode === "100755")) return false;
+        bytes = readFileSync(file);
+      }
+      total += bytes.length;
+      if (bytes.length > 4 * 1024 * 1024 || total > 32 * 1024 * 1024 || !deadline()) return false;
+      const after = lstatSync(file);
+      if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) return false;
+      if (createHash("sha1").update(`blob ${bytes.length}\0`).update(bytes).digest("hex") !== oid) return false;
+    }
+    return deadline();
+  } catch { return false; }
+}

package/src/hub/review-brief.ts

@@ -1,5 +1,7 @@
+import type { CodeFactResult, CodeSymbol } from "./code-facts.ts";
 import { childEnv } from "./child-process.ts";
 import { hubGitSync } from "./git.ts";
+import { symbolsOverlap } from "./symbol-normalizer.ts";
 
 /**
  * #520: the review brief ahub builds itself, in place of `ocr delegate preview` and `rule`. Every reviewer gets the same
@@ -10,6 +12,7 @@ import { hubGitSync } from "./git.ts";
 export interface BriefFile { path: string; status: string; oldPath?: string; insertions?: number; deletions?: number }
 export interface BriefExcluded { path: string; status: string; oldPath?: string; reason: string }
 export interface ReviewBrief {
+  symbols?: { state: "known" | "unknown"; complete?: boolean; files: {path:string; symbols:CodeSymbol[]}[]; planned: string[]; unplanned: string[]; unseen: string[] };
   head: string;
   /** The default branch the head is compared with: origin/HEAD, origin/main or origin/master. */
   base: string;
@@ -149,6 +152,38 @@ function attributes(cwd: string, source: string, paths: string[]): Map<string, {
   return out;
 }
 
+/** One plan name against one changed name: a qualified pair must be equal, otherwise the last segments are. Shared with the console's task detail (#684 2b). */
+export const planSymbolMatches = (left: string, right: string): boolean => symbolsOverlap(left, right);
+/** Project derived names through the host metadata screen before comparing or rendering them. */
+export function withCodeSymbols(brief:ReviewBrief,result:CodeFactResult<CodeSymbol[]>,plan:readonly string[]|undefined,publicMetadataText:(text:string)=>boolean):ReviewBrief {
+  const unknown={...brief,symbols:{state:"unknown" as const,files:[],planned:[],unplanned:[],unseen:[]}};
+  if(result.state!=="known")return unknown;
+  try {
+    const paths=new Set(brief.reviewable.map(file=>file.path));
+    const changed=result.value.filter(s=>!s.ambiguous && paths.has(s.path) && publicMetadataText(s.path) && publicMetadataText(s.name) && publicMetadataText(s.kind));
+    const planned=(plan??[]).filter(name=>publicMetadataText(name));
+    const matches=planSymbolMatches;
+    const names=[...new Set(changed.map(s=>s.name))];
+    return {...brief,symbols:{state:"known",complete:changed.length===result.value.length && brief.withheld===0,files:[...paths].map(path=>({path,symbols:changed.filter(s=>s.path===path)})),
+      planned:names.filter(name=>planned.some(p=>matches(p,name))),unplanned:names.filter(name=>!planned.some(p=>matches(p,name))),unseen:planned.filter(p=>!names.some(name=>matches(p,name)))}};
+  } catch { return unknown; }
+}
+
+function renderCodeSymbols(brief:ReviewBrief):string[] {
+  const symbols=brief.symbols;
+  if(!symbols)return [];
+  if(symbols.state === "unknown")return ["Changed symbols: unknown (optional code facts unavailable)."];
+  const lines=[
+    "Changed symbols (advisory; change: unknown):",
+    ...symbols.files.flatMap(file=>file.symbols.length ? file.symbols.map(symbol=>`- ${file.path}: ${symbol.name} (${symbol.kind}, lines ${symbol.line}${symbol.endLine === undefined ? "..unknown" : `..${symbol.endLine}`}; change: unknown)`) : [`- ${file.path}: no changed symbol observed`]),
+    `Changed and planned: ${symbols.planned.join(", ") || "none observed"}`,
+    `Changed, not planned: ${symbols.unplanned.join(", ") || "none observed"}`,
+    `Planned, not seen as changed: ${symbols.unseen.join(", ") || "none observed"}`,
+    "Ceiling: ripwire 0.6.7 does not report deleted symbols; these lists never establish plan conformance.",
+  ];
+  return Buffer.byteLength(lines.join("\n"))<=16000 ? lines : ["Changed symbols: unknown (advice exceeds 16000 bytes)."];
+}
+
 /** The brief as review text: what every reviewer reads and how it accounts for its coverage. */
 export function renderReviewBrief(brief: ReviewBrief): string {
   const file = (f: BriefFile) => `- ${f.oldPath ? `${f.oldPath} -> ` : ""}${f.path} (${f.status}${f.insertions !== undefined ? `, +${f.insertions} -${f.deletions}` : ""})`;
@@ -156,6 +191,7 @@ export function renderReviewBrief(brief: ReviewBrief): string {
     `Review brief: head ${brief.head} against ${brief.base} (merge base ${brief.mergeBase.slice(0, 12)}); ${brief.reviewable.length} reviewable, ${brief.excluded.length} excluded${brief.withheld ? `, ${brief.withheld} withheld by the privacy policy` : ""}.`,
     ...(brief.reviewable.length ? ["Reviewable:", ...brief.reviewable.map(file)] : ["Reviewable: none (record why in the note)."]),
     ...(brief.excluded.length ? ["Excluded (still read their diff when it matters):", ...brief.excluded.map(e => `- ${e.oldPath ? `${e.oldPath} -> ` : ""}${e.path} (${e.status}): ${e.reason}`)] : []),
+    ...renderCodeSymbols(brief),
     ...(brief.unlisted.length ? ["Not in the brief's list, read directly:", ...brief.unlisted.map(path => `- ${path}`)] : []),
     ...brief.ruleGroups.filter(g => g.sources.length).map(g => `Rules ${g.sources.join(" + ")} apply to: ${brief.ruleGroups.length === 1 ? "every reviewable file" : g.paths.join(", ")}`),
     ...(brief.rulesMissing.length ? ["Configured rules not loaded (read them in the repository):", ...brief.rulesMissing.map(m => `- ${m.source}: ${m.reason}`)] : []),