@staix/agent-hub 0.12.42 → 0.12.44

package/src/hub/hub-tools.ts

@@ -97,7 +97,7 @@ export const TASK_TOOL_NAMES = new Set(TASK_TOOLS.map((t) => t.name));
 export const CONDUCTOR_TOOLS: HubTool[] = [
   tool("hub_status", "Inspect public team state, holds, quota windows, task counts and pending approval peer/tool/age. Only the configured conductor may use this tool.", {}),
   tool("hub_task_show", "Read a task's public view and history, its done summary and check result included. PII tasks remain stubs. Only the conductor and the task's current owner and reviewer may use this tool.", { id }, ["id"]),
-  tool("hub_task_assign", "Name an owner (default role) or reviewer. Only the conductor may name a reviewer through this tool. A proposer may redirect an unaccepted proposed task's owner; a task that still waits reserves that owner. Pull-only peers receive work when named or when they claim it. With an explicit capabilities list, the conductor needs assign capability for either role, the proposer only to give ownership to another peer.", { id, peer: str, role: { type: "string", enum: ["owner", "reviewer"] } }, ["id", "peer"]),
+  tool("hub_task_assign", "Name an owner (default role) or reviewer. Only the conductor may name a reviewer through this tool. A proposer may redirect an unaccepted proposed task's owner; a task that still waits reserves that owner. Pull-only peers receive work when named while attached or when they claim it; a peer that cannot take the task is refused with the reason, and the task is unchanged. With an explicit capabilities list, the conductor needs assign capability for either role, the proposer only to give ownership to another peer.", { id, peer: str, role: { type: "string", enum: ["owner", "reviewer"] } }, ["id", "peer"]),
   tool("hub_task_escalate", "Escalate a task through the normal task flow, as the conductor. Requires assign capability when explicitly listed.", { id }, ["id"]),
   tool("hub_peer_start", "Start local, kimi, qwen, jcode, pi, claude or codex in the start mode a person set for it; you cannot choose the mode. A headless peer starts at once. A TUI peer (claude, and pi and codex by default) opens in a terminal with a fixed command; when the hub cannot open a terminal the call fails with the command for the person to run.", { peer: { type: "string", enum: CONDUCTOR_START_PEERS } }, ["peer"]),
   tool("hub_peer_hold", "Hold a peer's deliveries as the conductor. This hold is separate from the person's hold and budget pauses.", { peer: str }, ["peer"]),
@@ -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/main-checkout.ts

@@ -27,8 +27,8 @@ export function mainCheckoutBranch(cwd: string): { branch: string; defaultBranch
  * whole public-text screen (`Tasks.publicMetadataText`: the configured PII patterns, secret shapes and private paths). A name it refuses, or any text
  * that is not a plain ref name, is replaced by a generic sentence that carries no part of it (#572 review I2).
  */
-export function mainCheckoutWarning(cwd: string, nameable: (text: string) => boolean = () => false): string | undefined {
-  const found = mainCheckoutBranch(cwd);
+export function mainCheckoutWarning(cwd: string, nameable: (text: string) => boolean = () => false, read: typeof mainCheckoutBranch = mainCheckoutBranch): string | undefined {
+  const found = read(cwd);
   if (!found) return undefined;
   const plain = /^[A-Za-z0-9][A-Za-z0-9._\/-]{0,99}$/.test(found.branch) && nameable(found.branch);
   return plain ? `the main checkout is on \`${found.branch}\`; move the work to a worktree under .worktrees/`

package/src/hub/manager.ts

@@ -241,8 +241,9 @@ export async function openManager(options: ManagerOptions = {}): Promise<string>
   const f = files(home);
   mkdirSync(f.dir, { recursive: true, mode: 0o700 });
   const log = openSync(join(f.dir, "manager.log"), "a");
+  let proc: ReturnType<typeof spawn>;
   try {
-    const proc = spawn(process.execPath, [options.cli ?? join(import.meta.dir, "../cli/main.ts"), "manager"], {
+    proc = spawn(process.execPath, [options.cli ?? join(import.meta.dir, "../cli/main.ts"), "manager"], {
       cwd: home, detached: true, stdio: ["ignore", log, log], env: { ...scrubEnv(process.env), AGENTHUB_HOME: home },
     });
     proc.on("error", () => {}); proc.unref();
@@ -250,7 +251,14 @@ export async function openManager(options: ManagerOptions = {}): Promise<string>
   const deadline = Date.now() + 8000;
   let error: unknown;
   while (Date.now() < deadline) {
-    try { return (await managerRequest(home, "/open", options.liveTest)).body.url; }
+    try {
+      const answered = await managerRequest(home, "/open", options.liveTest);
+      // #584: concurrent opens each spawn a manager and one wins the owner claim. A spawn that lost, or is still booting when
+      // another manager answers, would claim the owner row once that manager is stopped and then run with nobody to stop it.
+      // Only the manager that answered is wanted; stop the process this open started if it is a different one.
+      if (answered.status.pid !== proc.pid) proc.kill("SIGTERM");
+      return answered.body.url;
+    }
     catch (caught) { error = caught; await Bun.sleep(100); }
   }
   throw new Error(`manager readiness not confirmed: ${safeError(error)}; see ${join(f.dir, "manager.log")}`);

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);