@staix/agent-hub 0.12.43 → 0.12.44

package/src/hub/hub-tools.ts

@@ -105,6 +105,42 @@ export const CONDUCTOR_TOOLS: HubTool[] = [
 ];
 export const CONDUCTOR_TOOL_NAMES = new Set(CONDUCTOR_TOOLS.map((t) => t.name));
 
+/** Authenticated status metadata only; malformed values never add a tool target. */
+function projectPeerIds(value: unknown): string[] | undefined {
+  if (!Array.isArray(value) || value.length > 256 || value.some(id => typeof id !== "string" || !/^[a-z][a-z0-9-]{0,31}$/.test(id) || ["user", "hub", "digest"].includes(id)) || new Set(value).size !== value.length) return undefined;
+  return [...value] as string[];
+}
+
+/** A project-local schema projection; released builtin arrays and all other tools keep their identity. */
+export function projectConductorTools(startPeers?: unknown): HubTool[] {
+  const peers = startPeers === undefined ? undefined : projectPeerIds(startPeers);
+  if (peers === undefined) return CONDUCTOR_TOOLS;
+  return CONDUCTOR_TOOLS.map(tool => tool.name !== "hub_peer_start" ? tool : {
+    ...tool, inputSchema: { ...tool.inputSchema, properties: { ...tool.inputSchema.properties,
+      peer: { ...(tool.inputSchema.properties.peer as Record<string, unknown>), enum: [...new Set([...CONDUCTOR_START_PEERS, ...peers])] },
+    } },
+  });
+}
+
+export interface ProjectToolContext { startPeers?: string[]; readOnly?: boolean }
+/** Ordinary projects retain their exact prior publication context; configured metadata is body-free and bounded. */
+export function configuredToolContext(status: unknown, peer: string): ProjectToolContext {
+  if (!status || typeof status !== "object" || Array.isArray(status)) return {};
+  const raw = status as Record<string, unknown>, configured = projectPeerIds(raw.configuredAdapters);
+  if (!configured?.length) return {};
+  const startPeers = projectPeerIds(raw.startablePeers), readOnlyPeers = projectPeerIds(raw.readOnlyPeers);
+  // With an incomplete configured-project reading, publish only R2 reads until authenticated status is complete.
+  if (!startPeers || !readOnlyPeers) return { readOnly: true };
+  return { startPeers, readOnly: readOnlyPeers.includes(peer) };
+}
+
+const READ_ONLY_PROJECT_TOOLS = Object.freeze(["hub_send", "hub_inbox", "hub_delivery_done", "hub_review", "hub_task_show", "hub_task_list", "hub_memory_search", "hub_memory_show", "hub_memory_graph", "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;
+}
+
+
 /** Role contracts, by role name. Shown to each peer for the roles `.agenthub/config.json` gives it. */
 export const ROLE_TEXT: Record<string, string> = {
   conductor: "conductor: plan and split work into tasks with owners, watch the team with hub_status, move stalled work, and ensure every task is reviewed (review it yourself only if you also hold reviewer). Report results and open decisions to the person. Do not implement tasks you handed out. Never ask a peer to answer an approval; ask the person for human-only actions. You may release only holds you placed, never human holds or budget pauses.",

package/src/hub/instance-config.ts

@@ -1,6 +1,6 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import { defaultPeerRoles } from "../adapters/registry.ts";
+import { createProjectAdapterCatalog, defaultPeerRoles, definitionOf, type ProjectAdapterCatalog } from "../adapters/registry.ts";
 import { conductorPeer } from "./conductor.ts";
 import { configRefusal } from "./config-trust.ts";
 import { validateInstances, type InstancesConfig } from "./instances.ts";
@@ -17,24 +17,33 @@ export function readInstanceConfigLayers(cwd: string): InstanceConfigLayer[] {
 }
 
 /** Declaration authority is file provenance, never a suffix or a claim made by a native child. */
-export function readInstanceConfig(cwd: string, layers: readonly InstanceConfigLayer[] = readInstanceConfigLayers(cwd)): { instances?: InstancesConfig; ignored: string[] } {
+export interface InstanceRoleConfig {
+  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[] = [];
-  let instances: InstancesConfig | undefined;
+  let adapters: Readonly<Record<string, import("../adapters/configured-acp.ts").ConfiguredAcpAdapterConfig>> | undefined, rawInstances: unknown;
   for (const { name, raw } of layers) {
-    const checked = validateInstances(raw.instances);
-    if (!Object.keys(checked).length) continue;
-    if (name !== "config.local.json") { ignored.push(`instances in .agenthub/${name} ignored: instances are machine-local config.local.json declarations`); continue; }
-    const refusal = configRefusal(cwd, name);
-    if (refusal) ignored.push(`instances in .agenthub/${name} ignored: ${refusal}`);
-    else instances = checked;
+    const keys = ["adapters", "instances"].filter(key => raw[key] !== undefined);
+    if (!keys.length) continue;
+    const refusal = name !== "config.local.json" ? "declarations are machine-local config.local.json values" : configRefusal(cwd, name);
+    if (refusal) { ignored.push(`${keys.join(", ")} in .agenthub/${name} ignored: ${refusal}`); continue; }
+    if (raw.adapters !== undefined) adapters = raw.adapters as Readonly<Record<string, import("../adapters/configured-acp.ts").ConfiguredAcpAdapterConfig>>;
+    if (raw.instances !== undefined) rawInstances = raw.instances;
   }
-  return { ...(instances ? { instances } : {}), ignored };
+  const catalog = createProjectAdapterCatalog(adapters);
+  const instances = validateInstances(rawInstances, catalog);
+  return { ...(adapters !== undefined ? { adapters } : {}), ...(Object.keys(instances).length ? { instances } : {}), catalog, ignored };
 }
 
 /** Capture ordinary role policy and trusted instance declarations together, without loading daemon configuration. */
-export function readInstanceRoleConfig(cwd: string, layers: readonly InstanceConfigLayer[] = readInstanceConfigLayers(cwd)): { instances?: InstancesConfig; roles: Record<string, string[]>; ignored: string[] } {
+export function readInstanceRoleConfig(cwd: string, layers: readonly InstanceConfigLayer[] = readInstanceConfigLayers(cwd)): InstanceRoleConfig & { roles: Record<string, string[]> } {
   const declarationConfig = readInstanceConfig(cwd, layers);
   const roles = defaultPeerRoles(false);
+  for (const definition of declarationConfig.catalog.definitions) if (!definitionOf(definition.kind)) roles[definition.kind] = [...definition.roles];
   for (const name of INSTANCE_CONFIG_FILES) {
     const raw = layers.find(layer => layer.name === name)?.raw;
     if (raw?.roles !== undefined) {

package/src/hub/instance-execution.ts

@@ -1,6 +1,6 @@
 import { lstatSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { definitionOf } from "../adapters/registry.ts";
+import type { ProjectAdapterCatalog } from "../adapters/registry.ts";
 import { hubGitSync } from "./git.ts";
 import { realPath } from "./project.ts";
 import { validateInstances, type InstancesConfig } from "./instances.ts";
@@ -15,9 +15,9 @@ function git(cwd: string, args: string[]): string {
 const commonDirectory = (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[]): string {
-  if (definitionOf(id)) return projectRoot;
-  const declaration = validateInstances(declarations)[id];
+export function resolveInstanceExecutionCwd(projectRoot: string, id: string, declarations: InstancesConfig | undefined, roles: readonly string[], adapterCatalog: ProjectAdapterCatalog): string {
+  if (adapterCatalog.definitionOf(id)) return projectRoot;
+  const declaration = validateInstances(declarations, adapterCatalog)[id];
   if (!declaration) return refuse("extra instance is not declared");
   const implementer = roles.includes("implementer");
   if (!declaration.worktree) {

package/src/hub/instances.ts

@@ -1,5 +1,5 @@
 import { types } from "node:util";
-import { ADAPTERS, defaultPeerRoles, definitionOf, type AdapterDefinition, type StartForm } from "../adapters/registry.ts";
+import { defaultPeerRoles, definitionOf, type AdapterDefinition, type StartForm, type ProjectAdapterCatalog } from "../adapters/registry.ts";
 import { isPermissionMode, type PermissionMode } from "./permission-mode.ts";
 
 export interface InstanceConfig {
@@ -9,6 +9,7 @@ export interface InstanceConfig {
   permission_mode?: PermissionMode;
   review_mode?: "fresh";
   worktree?: string;
+  readOnly?: boolean;
 }
 export type InstancesConfig = Readonly<Record<string, InstanceConfig>>;
 export interface InstanceCatalogEntry { id: string; kind: string; definition: AdapterDefinition; config?: InstanceConfig }
@@ -40,19 +41,30 @@ function roles(value: unknown, field: string): string[] {
   return out;
 }
 
-/** Pure I2 declaration validation. Physical worktree and startup authority checks belong to the bound host. */
-export function validateInstances(raw: unknown): InstancesConfig {
+/** 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");
+}
+
+/** Resolve project declarations only through their captured, explicit catalog. */
+export function instanceDefinitionOf(id: string, declarations: InstancesConfig | undefined, catalog: ProjectAdapterCatalog): AdapterDefinition | undefined {
+  return catalog.definitionOf(id, declarations);
+}
+
+/** Pure I2 validation; physical worktree and startup authority stay host-bound. */
+export function validateInstances(raw: unknown, catalog: ProjectAdapterCatalog): InstancesConfig {
+  const resolve = catalog.definitionOf;
   const result: Record<string, InstanceConfig> = Object.create(null);
   if (raw === undefined) return Object.freeze(result);
   const declarations = fields(raw, "instances");
   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) || definitionOf(id)) return fail("instances", "ids must be nonreserved extra instance ids, not builtin ids");
+    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"].includes(key))) return fail(path, "unsupported field");
+    if (Object.keys(entry).some(key => !["kind", "roles", "start_mode", "permission_mode", "worktree", "review_mode", "readOnly"].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 = definitionOf(kind), prefix = `${kind}-`;
+    const definition = resolve(kind), prefix = `${kind}-`;
     if (!definition) return fail(`${path}.kind`, "unknown native kind");
     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`) : [];
@@ -63,11 +75,12 @@ export function validateInstances(raw: unknown): InstancesConfig {
     if (definition.routing?.reviewOnly && !freshReviewer) return fail(path, "a review-only kind requires headless roles exactly [\"reviewer\"]");
     if (freshReviewer && entry.worktree) return fail(`${path}.worktree`, "a fresh reviewer reads the project checkout: worktree is not supported");
     if (freshReviewer && entry.permission_mode) return fail(`${path}.permission_mode`, "a fresh reviewer has a fixed read-only policy");
-    // #450 I3: a channel-plugin kind (Claude) runs only in the person's terminal, so it reviews or plans and never owns writes.
-    const channel = definition.identity.mcp === "channel-plugin";
+    // An external instance runs only in the person's terminal; its definition bounds the declared roles.
+    const external = definition.instances?.mode === "external";
+    const runtime = freshReviewer ? definition.reviewerVariant ?? definition : definition;
     const unavailableReviewer = freshReviewer && !!(definition.reviewerVariant ?? definition).reviewer?.unavailable;
-    if (!channel && !unavailableReviewer && (!definition.start.create || !definition.start.forms.includes("headless") || !["env", "acp-session"].includes(definition.identity.mcp))) return fail(`${path}.kind`, "unsupported; a headless factory with env or ACP-session identity, or a channel-plugin kind, is required, not project-file identity");
-    if (channel) {
+    if (!unavailableReviewer && runtime.instances?.mode !== "external" && !supportsHeadlessInstances(runtime)) return fail(`${path}.kind`, definition.reviewerVariant ? 'unsupported; this kind only declares headless reviewer instances with roles exactly ["reviewer"]' : "unsupported; explicit external instance policy or a headless instance policy with a headless factory is required");
+    if (external) {
       const declared = entry.roles ? roles(entry.roles.value, `${path}.roles`) : [];
       // #223: a headless one is the kind's reviewer variant, one fresh hub-run session per review request.
       if (entry.start_mode && definition.reviewerVariant) {
@@ -75,10 +88,20 @@ export function validateInstances(raw: unknown): InstancesConfig {
         if (declared.length !== 1 || declared[0] !== "reviewer") return fail(`${path}.roles`, "a headless channel-kind instance is a reviewer: roles must be exactly [\"reviewer\"]");
       } else {
         if (entry.start_mode || entry.worktree) return fail(path, "a channel instance starts only from the person's terminal (ahub <kind> --as <id>): start_mode and worktree are not supported; a headless reviewer declares roles [\"reviewer\"] and start_mode \"headless\"");
-        if (!declared.length || declared.some(role => role !== "reviewer" && role !== "planner")) return fail(`${path}.roles`, "a channel instance must declare its roles: reviewer and/or planner");
+        const allowed = definition.instances?.roles ?? definition.roles;
+        if (!declared.length || declared.some(role => !allowed.includes(role))) return fail(`${path}.roles`, "a channel instance must declare its roles: reviewer and/or planner");
       }
+    } else {
+      const allowed = runtime.instances?.roles;
+      if (allowed && (declaredRoles.length ? declaredRoles : runtime.roles).some(role => !allowed.includes(role))) return fail(`${path}.roles`, "roles must fit the definition's instance policy");
+    }
+    if (entry.readOnly) {
+      if (typeof entry.readOnly.value !== "boolean") return fail(`${path}.readOnly`, "must be a boolean");
+      if (!runtime.permission.genericAcp?.readOnly) return fail(`${path}.readOnly`, "native adapter has no verified read-only mode");
+      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 (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) {
       if (entry.start_mode.value !== "headless") return fail(`${path}.start_mode`, "I2 extra instances require headless mode");
@@ -99,24 +122,25 @@ export function validateInstances(raw: unknown): InstancesConfig {
 }
 
 /** Each call derives a fresh project-local projection, without registration or suffix discovery. */
-export function instanceCatalog(declarations?: InstancesConfig): readonly InstanceCatalogEntry[] {
-  const instances = validateInstances(declarations);
+export function instanceCatalog(declarations: InstancesConfig | undefined, catalog: ProjectAdapterCatalog): readonly InstanceCatalogEntry[] {
+  const instances = validateInstances(declarations, catalog);
   return Object.freeze([
-    ...ADAPTERS.map(definition => Object.freeze({ id: definition.kind, kind: definition.kind, definition })),
-    ...Object.entries(instances).map(([id, config]) => Object.freeze({ id, kind: config.kind, definition: definitionOf(id, instances)!, config })),
+    ...catalog.definitions.map(definition => Object.freeze({ id: definition.kind, kind: definition.kind, definition })),
+    ...Object.entries(instances).map(([id, config]) => Object.freeze({ id, kind: config.kind, definition: catalog.definitionOf(id, instances)!, config })),
   ]);
 }
-export function instancePeerIds(declarations?: InstancesConfig): string[] { return instanceCatalog(declarations).map(entry => entry.id); }
-export function instanceDefaultRoles(declarations?: InstancesConfig, includeOptional = true): Record<string, string[]> {
+export function instancePeerIds(declarations: InstancesConfig | undefined, catalog: ProjectAdapterCatalog): string[] { return instanceCatalog(declarations, catalog).map(entry => entry.id); }
+export function instanceDefaultRoles(declarations: InstancesConfig | undefined, includeOptional: boolean, catalog: ProjectAdapterCatalog): Record<string, string[]> {
   const result = defaultPeerRoles(includeOptional);
-  const instances = validateInstances(declarations);
-  for (const [id, config] of Object.entries(instances)) result[id] = [...(config.roles ?? definitionOf(id, instances)!.roles)];
+  for (const definition of catalog.definitions) if (!definitionOf(definition.kind) && (includeOptional || !definition.optional)) result[definition.kind] = [...definition.roles];
+  const instances = validateInstances(declarations, catalog);
+  for (const [id, config] of Object.entries(instances)) result[id] = [...(config.roles ?? catalog.definitionOf(id, instances)!.roles)];
   return result;
 }
 
 /** One precedence rule for startup, native launch and recovery; ordinary roles may use the instance id or its kind. */
-export function effectiveInstanceRoles(id: string, declarations: InstancesConfig | undefined, policyRoles: Readonly<Record<string, readonly string[]>>): string[] {
-  const definition = definitionOf(id, declarations);
+export function effectiveInstanceRoles(id: string, declarations: InstancesConfig | undefined, policyRoles: Readonly<Record<string, readonly string[]>>, catalog: ProjectAdapterCatalog): string[] {
+  const definition = catalog.definitionOf(id, declarations);
   if (!definition) throw new Error(`${id}: no declared native instance`);
   const declaration = declarations && Object.hasOwn(declarations, id) ? declarations[id] : undefined;
   const ownRoles = (key: string): readonly string[] | undefined => Object.hasOwn(policyRoles, key) ? policyRoles[key] : undefined;

package/src/hub/lifecycle-schema.ts

@@ -1,18 +1,20 @@
 import { ControlClient } from "./control-client.ts";
+import { configuredToolContext, type ProjectToolContext } from "./hub-tools.ts";
 import { SDLC_STAGES } from "./sdlc.ts";
 /** The daemon owns the active definition. Unavailable reads never invent a project-file stage set. */
 /** The active stage ids and whether the lifecycle is enabled (`criteria`, #481 S8); an older daemon never says so. */
-export async function activeLifecycle(stateDir: string, peer: string, projectRoot: string, active?: ControlClient): Promise<{ stages: string[]; criteria: boolean } | undefined> {
+export async function activeLifecycle(stateDir: string, peer: string, projectRoot: string, active?: ControlClient): Promise<({ stages: string[]; criteria: boolean } & ProjectToolContext) | undefined> {
   let client: ControlClient | undefined;
   try {
     client = active ?? await ControlClient.connect(stateDir, { role: "tools", peer, projectRoot }, 1000);
     const reply = await client.request({ t: "status" }, 1000);
     if (reply.t !== "status" || !reply.status || typeof reply.status !== "object" || Array.isArray(reply.status)) return undefined;
+    const projectTools = configuredToolContext(reply.status, peer);
     // A live older daemon has the fixed seven-stage contract and no optional metadata field.
-    if (!Object.hasOwn(reply.status, "lifecycleStages")) return { stages: [...SDLC_STAGES], criteria: false };
+    if (!Object.hasOwn(reply.status, "lifecycleStages")) return { stages: [...SDLC_STAGES], criteria: false, ...projectTools };
     const stages: unknown = reply.status.lifecycleStages;
     if (!Array.isArray(stages) || !stages.length || stages.length > 32 || stages.some(s => typeof s !== "string" || !/^[a-z][a-z0-9_-]{0,47}$/.test(s)) || new Set(stages).size !== stages.length) return undefined;
-    return { stages: [...stages] as string[], criteria: reply.status.lifecycleCriteria === true };
+    return { stages: [...stages] as string[], criteria: reply.status.lifecycleCriteria === true, ...projectTools };
   } catch { return undefined; }
   finally { if (client !== active) client?.close(); }
 }

package/src/hub/memory-profile.ts

@@ -117,6 +117,14 @@ export function memoryProjectFor(cwd: string, opts: Pick<StoreOptions, "home"> =
   return resolveAlias(homeFor(opts), memoryProjectKey(cwd));
 }
 
+/**
+ * #240: the project key for a caller-injected store. Its alias log is the one in its own bound home (`profile.home`),
+ * never the ambient memory home's: a different alias log could hide that store's rows or refuse its writes.
+ */
+export function memoryProjectForStore(store: MemoryStore, cwd: string): string {
+  return resolveAlias(canonicalHome(store.profile.home), memoryProjectKey(cwd));
+}
+
 /** Inspect selection without constructing a store, index, or candidate sidecar. */
 export function selectedMemoryProfile(opts: StoreOptions = {}): MemoryProfileReceipt {
   assertLoadedAgentMem();
@@ -241,11 +249,16 @@ export function openProfileMemory(opts: ProfileMemoryOptions = {}, onUnavailable
   }
 }
 
-/** Bind a caller-owned store only when it exactly matches the current person selection. */
-export function bindProfileMemory(store: MemoryStore, onUnavailable?: (neutralReason: string) => void): {
+/**
+ * Bind a caller-owned store only when it exactly matches the current person selection. `projectKey` is the raw key
+ * the caller resolves its project from (#240): a sharded store whose home now aliases that key to another project is
+ * refused, and a later remap latches the binding unavailable, so a command never runs as B through A's shard.
+ */
+export function bindProfileMemory(store: MemoryStore, onUnavailable?: (neutralReason: string) => void, projectKey?: string): {
   store: MemoryStore; binding: MemoryProfileBinding;
 } {
-  const binding = new MemoryProfileBinding({ project: store.profile.shardKey }, onUnavailable, store.profile.home);
+  const sharded = store.profile.shardKey !== undefined;
+  const binding = new MemoryProfileBinding({ project: store.profile.shardKey, ...(sharded && projectKey !== undefined ? { projectKey } : {}) }, onUnavailable, store.profile.home);
   binding.assertCurrent();
   if (!sameProfile(store.profile, binding.profile)) throw new Error(UNAVAILABLE);
   return { store, binding };

package/src/hub/no-writes.ts

@@ -0,0 +1,50 @@
+import type { Task } from "./board.ts";
+
+export interface NoWriteObservation {
+  task: number;
+  /** Opaque binding to the current owner and its latest acceptance. */
+  generation: string;
+  limit: number;
+  changed: boolean | undefined;
+  effect: boolean;
+}
+
+/** Pure per-task streaks; callers own evidence, privacy and warning delivery. */
+export class NoWriteTurns {
+  private readonly streaks = new Map<number, { generation: string; count: number; emitted: boolean }>();
+
+  observe({ task, generation, limit, changed, effect }: NoWriteObservation): number | undefined {
+    if (!Number.isSafeInteger(limit) || limit <= 0 || changed !== false || effect !== false) {
+      this.reset(task);
+      return undefined;
+    }
+    const previous = this.streaks.get(task);
+    const streak = previous?.generation === generation ? previous : { generation, count: 0, emitted: false };
+    if (streak !== previous) this.streaks.set(task, streak);
+    if (streak.emitted) return undefined;
+    if (streak.count < Number.MAX_SAFE_INTEGER) streak.count++;
+    if (streak.count < limit) return undefined;
+    streak.emitted = true;
+    return streak.count;
+  }
+
+  reset(task: number): void { this.streaks.delete(task); }
+
+  retain(activeTaskIds: readonly number[]): void {
+    const active = new Set(activeTaskIds);
+    for (const task of this.streaks.keys()) if (!active.has(task)) this.reset(task);
+  }
+}
+
+
+const OWNER_TOOL_EFFECTS = new Set(["hub_task_propose", "hub_task_decline", "hub_task_done", "hub_task_cancel", "hub_task_assign", "hub_task_escalate", "hub_review", "hub_checkpoint", "hub_remember", "hub_memory_correct", "hub_check_start", "hub_check_cancel", "hub_sdlc_record", "hub_plan_review", "hub_backlog_plan", "hub_backlog_pull", "hub_backlog_undo", "hub_backlog_split", "hub_backlog_return_untouched", "hub_release_new", "hub_release_configure", "hub_release_assign", "hub_release_cut"]);
+/** A read does not prove progress; failed/pending mutations are handled conservatively by the host. */
+export function ownerToolEffect(op: string, input: Record<string, unknown> | undefined): boolean {
+  return OWNER_TOOL_EFFECTS.has(op) || op === "hub_task_accept" && !!input?.plan && typeof input.plan === "object" && Object.keys(input.plan).length > 0;
+}
+
+/** Canonical snapshots cannot disprove work in the owner's separately recorded checkout/PR. */
+export function canonicalWriteUnknown(task: Pick<Task, "refs" | "plan" | "sdlc">): boolean {
+  return !!(task.refs.branch || task.refs.commit || task.sdlc?.head || task.sdlc?.localHead || task.sdlc?.pr)
+    || [...(task.refs.paths ?? []), ...(task.plan?.paths ?? [])].some(path => /(?:^|[\\/])\.worktrees(?:[\\/]|$)/i.test(path));
+}

package/src/hub/permission-mode.ts

@@ -1,4 +1,4 @@
-import { definitionOf, type KindMap } from "../adapters/registry.ts";
+import { definitionOf, type ProjectAdapterCatalog, type KindMap } from "../adapters/registry.ts";
 import { lstatSync } from "node:fs";
 import { isAbsolute, relative, resolve, sep } from "node:path";
 
@@ -8,13 +8,15 @@ export type PermissionMode = typeof PERMISSION_MODES[number];
 export { KIMI_MODE_IDS } from "../adapters/definitions/kimi-native.ts";
 export { QWEN_MODE_IDS } from "../adapters/definitions/qwen-native.ts";
 export const isPermissionMode = (value: unknown): value is PermissionMode => typeof value === "string" && (PERMISSION_MODES as readonly string[]).includes(value);
-export function permissionDefaults(value: unknown, instances?: KindMap): Record<string, PermissionMode> {
+export function permissionDefaults(value: unknown, instances?: KindMap, catalog?: ProjectAdapterCatalog): Record<string, PermissionMode> {
   if (value === undefined) return {};
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("permission_modes must be an object with ask, ask-when-needed or never-ask values");
   const result: Record<string, PermissionMode> = {};
   for (const [peer, mode] of Object.entries(value)) {
-    const definition = typeof peer === "string" ? definitionOf(peer, instances) : undefined;
+    const definition = typeof peer === "string" ? (catalog?.definitionOf ?? definitionOf)(peer, instances) : undefined;
     if (!definition) throw new Error(`permission_modes.${peer}: unsupported peer`);
+    if (instances && Object.hasOwn(instances, peer) && (instances[peer] as { readOnly?: boolean })?.readOnly) throw new Error(`permission_modes.${peer}: read-only ceiling is locked`);
+    if (definition.permission.genericAcp && (!definition.permission.genericAcp.modes || typeof mode !== "string" || !Object.hasOwn(definition.permission.genericAcp.modes, mode))) throw new Error(`permission_modes.${peer}: native mode mapping is unavailable`);
     if (definition.permission.unmanaged) throw new Error(`${definition.displayName} native policy is unmanaged; no hub permission_modes.${peer} mapping exists`);
     if (!isPermissionMode(mode)) throw new Error(`permission_modes.${peer} must be ask, ask-when-needed or never-ask`);
     result[peer] = mode;
@@ -22,16 +24,16 @@ export function permissionDefaults(value: unknown, instances?: KindMap): Record<
   return result;
 }
 /** Approval frequency does not create a common sandbox across native peers. */
-export function permissionBoundary(peer: string, instances?: KindMap): string {
-  const definition = definitionOf(peer, instances);
+export function permissionBoundary(peer: string, instances: KindMap | undefined, catalog: ProjectAdapterCatalog): string {
+  const definition = catalog.definitionOf(peer, instances);
   if (definition?.permission.unmanaged) return `${peer}: native policy unmanaged; NO hub sandbox; approvals belong to its native tools`;
   if (definition?.trust.hubSandboxed) return `${peer}: inside hub sandbox, path guard and denylist`;
   if (definition?.transport === "claude-channel" || definition?.transport === "codex-appserver") return `${peer}: native vendor bounds; no hub sandbox`;
   return `${peer}: runs its own tools; NO hub sandbox`;
 }
 /** What a mode lets a peer do without asking, in one line a person reads before choosing it (#269). */
-export function permissionGrant(peer: string, mode: PermissionMode, instances?: KindMap): string {
-  const grant = definitionOf(peer, instances)?.permission.grants?.[mode];
+export function permissionGrant(peer: string, mode: PermissionMode, instances?: KindMap, catalog?: ProjectAdapterCatalog): string {
+  const grant = (catalog?.definitionOf ?? definitionOf)(peer, instances)?.permission.grants?.[mode];
   if (grant !== undefined) return grant;
   if (mode === "ask") return "every write, edit and shell command asks";
   return mode === "never-ask" ? "every tool runs without asking, inside the hub sandbox and path guard" : "write and edit inside the project run without asking; shell and git writes still ask";

package/src/hub/roster.ts

@@ -1,9 +1,10 @@
-import { definitionOf, type KindMap } from "../adapters/registry.ts";
-import { defaultRosterEnabled } from "../adapters/registry.ts";
+import { definitionOf as builtinDefinitionOf, type ProjectAdapterCatalog, type KindMap } from "../adapters/registry.ts";
+import { defaultRosterEnabled as builtinDefaultRosterEnabled } from "../adapters/registry.ts";
 
 export type PeerRoster = Partial<Record<string, boolean>>;
 
-export function peerRosterConfig(value: unknown, instances?: KindMap): PeerRoster {
+export function peerRosterConfig(value: unknown, instances?: KindMap, catalog?: ProjectAdapterCatalog): PeerRoster {
+  const definitionOf = catalog?.definitionOf ?? builtinDefinitionOf;
   if (value === undefined) return {};
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("roster must be an object of boolean peer values");
   const roster: PeerRoster = {};
@@ -16,7 +17,9 @@ export function peerRosterConfig(value: unknown, instances?: KindMap): PeerRoste
 }
 
 /** External ids keep their existing admission rules; Pi's legacy switch is only its default. */
-export function rosterAllows(roster: PeerRoster, peer: string, piEnabled: boolean, instances?: KindMap): boolean {
+export function rosterAllows(roster: PeerRoster, peer: string, piEnabled: boolean, instances: KindMap | undefined, catalog: ProjectAdapterCatalog): boolean {
+  const definitionOf = catalog.definitionOf;
+  const defaultRosterEnabled = (id: string, enabled: boolean) => !builtinDefinitionOf(id) ? catalog.definitionOf(id)?.defaultOnRoster ?? false : builtinDefaultRosterEnabled(id, enabled);
   const definition = definitionOf(peer, instances);
   if (!definition) return true; // External clients do not acquire a native kind from a project declaration.
   return roster[peer] ?? (definition.kind === peer ? defaultRosterEnabled(peer, piEnabled) : true);

package/src/hub/routing.ts

@@ -1,5 +1,5 @@
 import { selectReviewerPool, type ReviewerPoolSelection } from "./reviewer-pool.ts";
-import { ADAPTERS, definitionOf, kindOf, familyOf } from "../adapters/registry.ts";
+import { ADAPTERS, definitionOf, kindOf, familyOf, type ProjectAdapterCatalog } from "../adapters/registry.ts";
 import { readFileSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { CLASSES, type Task, type TaskClass } from "./board.ts";
@@ -115,6 +115,7 @@ export const PI: PeerId = "pi";
 
 /** Startup-bound project data, never inferred from a suffix or read from configuration here. */
 export interface InstanceRoutingOptions {
+  adapterCatalog?: ProjectAdapterCatalog;
   instances?: Readonly<Record<string, { kind: string }>>;
   wip?: Record<string, number>;
   load?: Record<string, number>;
@@ -133,8 +134,8 @@ function siblingOrder(states: Readonly<Record<string, PeerState>>, opts: Instanc
 function expandClassPeers(peers: readonly PeerId[], states: Readonly<Record<string, PeerState>>, opts: InstanceRoutingOptions): PeerId[] {
   if (!hasInstances(opts)) return [...peers];
   return [...new Set(peers.flatMap(peer => {
-    const kind = kindOf(peer, opts.instances);
-    return kind && kind === peer ? [peer, ...Object.keys(opts.instances!).filter(id => kindOf(id, opts.instances) === kind)].sort(siblingOrder(states, opts)) : [peer];
+    const kind = (opts.adapterCatalog?.kindOf ?? kindOf)(peer, opts.instances);
+    return kind && kind === peer ? [peer, ...Object.keys(opts.instances!).filter(id => (opts.adapterCatalog?.kindOf ?? kindOf)(id, opts.instances) === kind)].sort(siblingOrder(states, opts)) : [peer];
   }))];
 }
 /** Quota/adaptive policy retains kind slots; sibling workload chooses only within that kind's slots. */
@@ -142,7 +143,7 @@ function orderSiblingSlots(peers: PeerId[], states: Readonly<Record<string, Peer
   if (!hasInstances(opts)) return peers;
   const groups = new Map<string, number[]>(), out = [...peers];
   for (const [index, peer] of peers.entries()) {
-    const kind = kindOf(peer, opts.instances);
+    const kind = (opts.adapterCatalog?.kindOf ?? kindOf)(peer, opts.instances);
     if (kind) { const slots = groups.get(kind) ?? []; slots.push(index); groups.set(kind, slots); }
   }
   for (const slots of groups.values()) {
@@ -154,11 +155,11 @@ function orderSiblingSlots(peers: PeerId[], states: Readonly<Record<string, Peer
 
 /** The quota/roster relay keeps its native preference order, then the class's original tail. */
 export function relayCandidates(classPeers: readonly PeerId[], pii: boolean, opts: InstanceRoutingOptions & { states?: Readonly<Record<string, PeerState>> } = {}): PeerId[] {
-  const preferred = ADAPTERS.filter(adapter => adapter.routing?.handoffPriority !== undefined)
+  const preferred = (opts.adapterCatalog?.definitions ?? ADAPTERS).filter(adapter => adapter.routing?.handoffPriority !== undefined)
     .sort((a, b) => a.routing!.handoffPriority! - b.routing!.handoffPriority!);
   const candidates = [
     ...preferred.filter(adapter => !pii || adapter.trust.onPrem).map(adapter => adapter.kind),
-    ...classPeers.filter(peer => definitionOf(peer, opts.instances)?.routing?.handoffPriority === undefined),
+    ...classPeers.filter(peer => (opts.adapterCatalog?.definitionOf ?? definitionOf)(peer, opts.instances)?.routing?.handoffPriority === undefined),
   ].filter((peer): peer is PeerId => !!peer);
   return expandClassPeers(candidates, opts.states ?? {}, opts);
 }
@@ -378,10 +379,10 @@ export function assign(
   const refusals = new Map<string, RoutingRefusal>();
   const blocked = (peer: PeerId, role: "owner" | "reviewer"): string | undefined => {
     const deny = (code: RoutingRefusalCode, reason: string): string => { refusals.set(`${role}:${peer}`, { peer, role, code, reason }); return reason; };
-    const ceiling = definitionOf(peer, opts.instances)?.routing?.allowedRoles;
+    const ceiling = (opts.adapterCatalog?.definitionOf ?? definitionOf)(peer, opts.instances)?.routing?.allowedRoles;
     const requiredRole = role === "reviewer" || task.class === "review" ? "reviewer" : task.class === "plan" ? "planner" : "implementer";
     if (ceiling && !ceiling.includes(requiredRole)) return deny("policy", "adapter role ceiling excludes this assignment");
-    const unavailable = role === "reviewer" ? definitionOf(peer, opts.instances)?.reviewer?.unavailable : undefined;
+    const unavailable = role === "reviewer" ? (opts.adapterCatalog?.definitionOf ?? definitionOf)(peer, opts.instances)?.reviewer?.unavailable : undefined;
     if (unavailable) return deny("policy", unavailable);
     if (role === "owner" && opts.capabilities && !pii) {
       const caps = peerEntry(opts.capabilities, peer);
@@ -394,7 +395,7 @@ export function assign(
     if (!Object.hasOwn(states, peer)) return deny("not-attached", "not attached");
     if (opts.exclude?.includes(peer)) return deny("excluded", "excluded (declined or replaced)");
     if (role === "owner" && opts.excludeOwners?.includes(peer)) return deny("owner-admission", "owner admission: WIP or delivery hold");
-    const adapter = definitionOf(peer, opts.instances);
+    const adapter = (opts.adapterCatalog?.definitionOf ?? definitionOf)(peer, opts.instances);
     if (role === "owner" && adapter?.routing?.reviewOnly) return deny("owner-admission", "owner admission: a review-only instance owns no task");
     if (role === "owner" && needsTests && adapter && adapter.kind !== peer) {
       if (!peerEntry(opts.roles, peer)?.includes("implementer")) return deny("owner-admission", "owner admission: declared write owner requires the current implementer role");
@@ -404,8 +405,8 @@ export function assign(
     if (states[peer] === "paused" && routing.constraints.budget_paused === "skip_peer") return deny("paused", "paused");
     const failing = peerEntry(opts.failing, peer);
     if (failing) return deny("failing", `failing: ${failing}`);
-    if (pii && definitionOf(peer, opts.instances)?.trust.onPrem !== true) return deny("pii", "pii: on-prem peers only");
-    const nativeRouting = definitionOf(peer, opts.instances)?.routing;
+    if (pii && (opts.adapterCatalog?.definitionOf ?? definitionOf)(peer, opts.instances)?.trust.onPrem !== true) return deny("pii", "pii: on-prem peers only");
+    const nativeRouting = (opts.adapterCatalog?.definitionOf ?? definitionOf)(peer, opts.instances)?.routing;
     if (nativeRouting?.localAllowedRefusal && policy?.local_allowed === false) return deny("policy", nativeRouting.localAllowedRefusal);
     if (nativeRouting?.longContext === "backend-limit" && task.signals.includes("long_context")) {
       const backend = policy?.pi_backend ?? "dgx";
@@ -462,7 +463,7 @@ export function assign(
     }
     const ranked = sortSiblings ? orderSiblingSlots(rank(ok, role, not), states, opts) : rank(ok, role, not);
     // Demotion applies to local and Pi too: a demoted one loses its place ahead of the cloud peers.
-    const localTier = ranked.filter((p) => definitionOf(p, opts.instances)?.routing?.preferredTier === true && !(role === "owner" && peerEntry(opts.demoted, p)));
+    const localTier = ranked.filter((p) => (opts.adapterCatalog?.definitionOf ?? definitionOf)(p, opts.instances)?.routing?.preferredTier === true && !(role === "owner" && peerEntry(opts.demoted, p)));
     if (localTier.length) return localTier.find((p) => states[p] === "idle") ?? localTier[0]; // local/Pi stays ahead of an idle cloud peer
     return ranked.find((p) => states[p] === "idle") ?? ranked[0];
   };
@@ -492,13 +493,13 @@ export function assign(
       trace.push(opts.namedReviewer === undefined ? `  reviewer candidates: [classes.review] peers ${classPeers.join(", ") || "none"}${rolePeers.length ? `; reviewer role ${rolePeers.join(", ")}` : ""}` : `  reviewer candidate explicitly named: ${opts.namedReviewer}`);
       const reviewOwner = owner ?? opts.notReviewer;
       const automatic = [...new Set([...expandClassPeers(classPeers, states, opts), ...rolePeers])];
-      const ownerFamily = instanceMode && reviewOwner ? familyOf(reviewOwner, opts.instances) : undefined;
-      const sameFamily = (peer: PeerId) => ownerFamily !== undefined && familyOf(peer, opts.instances) === ownerFamily;
+      const ownerFamily = instanceMode && reviewOwner ? (opts.adapterCatalog?.familyOf ?? familyOf)(reviewOwner, opts.instances) : undefined;
+      const sameFamily = (peer: PeerId) => ownerFamily !== undefined && (opts.adapterCatalog?.familyOf ?? familyOf)(peer, opts.instances) === ownerFamily;
       const independent = ownerFamily === undefined ? [] : automatic.filter(peer => peer !== reviewOwner && !blocked(peer, "reviewer") && !sameFamily(peer));
       const named = opts.namedReviewer;
       const declaredPool = opts.reviewPool && named === undefined ? Object.keys(opts.instances ?? {}).flatMap(id => {
-        const roles = peerEntry(opts.roles, id), definition = definitionOf(id, opts.instances);
-        const kind = kindOf(id, opts.instances), family = familyOf(id, opts.instances);
+        const roles = peerEntry(opts.roles, id), definition = (opts.adapterCatalog?.definitionOf ?? definitionOf)(id, opts.instances);
+        const kind = (opts.adapterCatalog?.kindOf ?? kindOf)(id, opts.instances), family = (opts.adapterCatalog?.familyOf ?? familyOf)(id, opts.instances);
         if (roles?.length !== 1 || roles[0] !== "reviewer" || !definition?.routing?.reviewOnly || !kind || !family) return [];
         const reason = id === reviewOwner ? "is the owner" : definition.reviewer?.unavailable ?? blocked(id, "reviewer")
           ?? (states[id] === "paused" ? "paused" : undefined)
@@ -509,7 +510,7 @@ export function assign(
       if (declaredPool.length || opts.reviewPool?.required && named === undefined) {
         for (const candidate of declaredPool) if (!opts.reviewPool!.pool.includes(candidate.kind)) trace.push(`  reviewer pool candidate ${candidate.id} (${candidate.family}): unavailable skip: ${candidate.blocked ?? "kind outside configured pool"}`);
         const last = task.history?.findLast(entry => entry.event === "changes_requested");
-        const continuityFamily = last && "reviewerFamily" in last && typeof last.reviewerFamily === "string" ? last.reviewerFamily : last ? familyOf(last.by, opts.instances) : undefined;
+        const continuityFamily = last && "reviewerFamily" in last && typeof last.reviewerFamily === "string" ? last.reviewerFamily : last ? (opts.adapterCatalog?.familyOf ?? familyOf)(last.by, opts.instances) : undefined;
         const pr = task.sdlc?.pr;
         const seed = typeof pr === "number" && Number.isSafeInteger(pr) && pr > 0 ? pr : task.id ?? 0;
         reviewSelection = selectReviewerPool({ pool: opts.reviewPool!.pool, candidates: declaredPool, seed, implementerFamily: ownerFamily, continuityFamily, rerotate: opts.reviewPool!.rerotate, failed: opts.reviewPool!.failed });
@@ -518,7 +519,7 @@ export function assign(
         if (reviewSelection.blocked) {
           trace.push("blocked: no reviewer can run");
           // Optional defaults retain the legacy planner escape when no fresh reviewer can run.
-          const planners = opts.reviewPool?.required ? [] : automatic.filter(peer => peer !== reviewOwner && peerEntry(opts.roles, peer)?.includes("planner") && !definitionOf(peer, opts.instances)?.routing?.reviewOnly && !blocked(peer, "reviewer"));
+          const planners = opts.reviewPool?.required ? [] : automatic.filter(peer => peer !== reviewOwner && peerEntry(opts.roles, peer)?.includes("planner") && !(opts.adapterCatalog?.definitionOf ?? definitionOf)(peer, opts.instances)?.routing?.reviewOnly && !blocked(peer, "reviewer"));
           const otherFamily = planners.filter(peer => !sameFamily(peer));
           const planner = pick(otherFamily.length ? otherFamily : planners, "reviewer", reviewOwner);
           if (planner) {
@@ -555,8 +556,8 @@ export function assign(
   const route = effectiveLocalRoute(routing.local.route, policy?.route, policy?.fixed_model);
   const fixedModel = policy?.fixed_model ?? routing.local.fixed_model;
   const piBackend = policy?.pi_backend;
-  if (owner && definitionOf(owner, opts.instances)?.routing?.trace === "route") trace.push(`route: ${route ?? "(none)"}, fixed_model ${fixedModel}`);
-  if (owner && definitionOf(owner, opts.instances)?.routing?.trace === "backend") trace.push(`${definitionOf(owner, opts.instances)!.routing!.backendLabel} decision: backend ${piBackend ?? "dgx"}${task.signals.includes("long_context") ? `, context limit ${piBackend === "mlx" ? routing.pi.mlx_max_context_tokens : routing.pi.dgx_max_context_tokens}` : ""}`);
+  if (owner && (opts.adapterCatalog?.definitionOf ?? definitionOf)(owner, opts.instances)?.routing?.trace === "route") trace.push(`route: ${route ?? "(none)"}, fixed_model ${fixedModel}`);
+  if (owner && (opts.adapterCatalog?.definitionOf ?? definitionOf)(owner, opts.instances)?.routing?.trace === "backend") trace.push(`${(opts.adapterCatalog?.definitionOf ?? definitionOf)(owner, opts.instances)!.routing!.backendLabel} decision: backend ${piBackend ?? "dgx"}${task.signals.includes("long_context") ? `, context limit ${piBackend === "mlx" ? routing.pi.mlx_max_context_tokens : routing.pi.dgx_max_context_tokens}` : ""}`);
   return { ...(reviewSelection ? { reviewSelection } : {}), ...(reviewBlocked ? { reviewBlocked: true as const } : {}), ...(sameFamilyFallback ? { sameFamilyFallback: true as const } : {}), ...(plannerFallback ? { plannerFallback: true as const } : {}), ...(owner ? { owner } : {}), ...(pii ? { reviewer: "user" } : reviewer ? { reviewer } : {}), ...(route ? { route } : {}), fixedModel, ...(piBackend ? { piBackend } : {}), ...(unreserved ? { unreserved } : {}), ...(refusals.size ? { refusals: [...refusals.values()] } : {}), trace };
 }