@staix/agent-hub 0.12.23 → 0.12.24

package/src/hub/delivery-journal.ts

@@ -658,6 +658,11 @@ export class DeliveryJournal {
     ) as Record<string, unknown>[];
     return rows.map(parseDelivery);
   }
+  unresolved(peer: string): JournalDelivery[] {
+    this.ensureOpen();
+    const rows = this.db.query("SELECT * FROM deliveries WHERE project_id = ? AND peer = ? AND state IN ('queued', 'dispatching', 'accepted', 'needs_review') ORDER BY created_at, id").all(this.projectId, peer) as Record<string, unknown>[];
+    return rows.map(parseDelivery);
+  }
   resolve(
     id: string,
     revision: number,

package/src/hub/envelope.ts

@@ -14,7 +14,7 @@ export interface Envelope {
   kind: Kind;
   priority: Priority;
   body: string; // agent conclusions only, never tool noise
-  refs?: { repo?: string; branch?: string; commit?: string; paths?: string[]; task?: string; supervision?: boolean; supervisionKey?: string; budgetResume?: string; budgetResumeMoves?: { id: number; title: string; to: PeerId | null; role: "owner" | "reviewer" }[]; budgetResumeEarlier?: string[] };
+  refs?: { repo?: string; branch?: string; commit?: string; paths?: string[]; task?: string; backlog?: number[]; supervision?: boolean; supervisionKey?: string; budgetResume?: string; budgetResumeMoves?: { id: number; title: string; to: PeerId | null; role: "owner" | "reviewer" }[]; budgetResumeEarlier?: string[] };
   /** The body must not be shown outside its recipients: console tail and log print a stub instead (PII tasks). */
   private?: boolean;
   ts: number;

package/src/hub/events.ts

@@ -3,6 +3,8 @@ import type { TaskAttribution } from "./attribution.ts";
 import type { SwitchTrace } from "../models/route/stage.ts";
 import type { ScreenRecord } from "./inference.ts";
 
+export interface RoleIdentity { id: string; layer: "shipped" | "project"; hash: string }
+
 /** Bumped whenever a field changes meaning or goes away; new fields and new types do not bump it. */
 export const EVENTS_SCHEMA = 1;
 
@@ -13,6 +15,7 @@ export const EVENTS_SCHEMA = 1;
 export type HubEvent =
   | { type: "permission_mode"; peer: string; from: import("./permission-mode.ts").PermissionMode; to: import("./permission-mode.ts").PermissionMode }
   /** A settings change (#269): the registry key, the value in force before and after (closed words, ids or booleans, never free text) and where it came from. */
+  | { type: "role"; peer?: string; task?: number; actor: string; stage: "prepared" | "assigned"; roles: { id: string; layer: "shipped" | "project"; hash: string }[] }
   | { type: "settings"; key: string; from: import("./settings.ts").SettingValue; to: import("./settings.ts").SettingValue; source: "dashboard" | "terminal"; undo?: boolean }
   | { type: "envelope"; id: string; from: string; to?: string[]; priority: string; hop: number; kind?: string; task?: string; bytes?: number; private?: boolean; dropped?: string }
   | { type: "overflow" | "undeliverable"; id: string; from: string; peer: string }
@@ -27,11 +30,17 @@ export type HubEvent =
   | { type: "progress"; peer: string; task: number; severity: number; spinning: number; exploring: number; production: number }
   | { type: "stuck"; peer: string; task: number; category: "repetition" | "false_progress" | "drift" | "desperation" | "capability_gap"; streak: number; latched: boolean }
   | { type: "capability"; peer: string; state: "verified" | "lost"; via?: string }
+  /** A hub run began: every peer is detached until its next state event (#248: attachments never span a crash). */
+  | { type: "hub_start"; instance: string }
+  /** #248: the add-ons a peer works with, names and versions from a closed list, at each attach. */
+  | { type: "tooling"; peer: string; addons: import("./tooling.ts").Addon[] }
+  /** #258: a task brief handed to its owner: how many hub-memory items (and fails among them) and claude-mem items, never their text. */
+  | { type: "memory_brief"; peer: string; task: number; native: number; fails: number; claudeMem: number }
   | { type: "split"; task: number; where?: "routing" | "cohort"; verdict: "split" | "single" | "unknown"; single?: string; splitS?: number; singleS?: number; reason?: string; trace?: string[] }
   | { type: "state"; peer: string; state: string }
   | { type: "turn_start"; peer: string; turn: string }
   | { type: "native_thread"; peer: string; thread: string; fresh: boolean }
-  | ({ type: "turn_end"; peer: string; turn: string; ms: number; tokens?: number; files?: number; snapshotMs?: number } & Partial<TaskAttribution>)
+  | ({ type: "turn_end"; peer: string; turn: string; ms: number; tokens?: number; files?: number; snapshotMs?: number; preparedRoles?: RoleIdentity[] | null } & Partial<TaskAttribution>)
   | { type: "native_turn_end"; peer: string; id?: string }
   | { type: "conduct"; peer: string; action: string; task?: number; target?: string }
   | { type: "agent_cli"; peer: string; command: string; refused: boolean }
@@ -42,7 +51,8 @@ export type HubEvent =
   | { type: "cohort"; id: number; event: "formed" | "joined" | "lifted"; silent: boolean; tasks: number[]; owners: string[] }
   | ({ type: "tokens"; peer: string; n: number } & Partial<TaskAttribution>)
   | ({ type: "usage"; peer: string; source: "omniroute" | "claude_transcript"; id: string; measuredAt?: string; requestedModel?: string; servedModel?: string; provider?: string; inputTokens?: number; outputTokens?: number; cacheReadTokens?: number; cacheWriteTokens?: number; totalTokens?: number } & Partial<TaskAttribution>)
-  | { type: "task"; id: number; event: string; by: string; state: string; owner: string | null; reviewer: string | null; class: string; pii: boolean; reason?: string }
+  | { type: "planning"; by: string; task?: number; release?: number; fields: string[]; revision: number }
+  | { type: "task"; id: number; event: string; by: string; state: string; owner: string | null; reviewer: string | null; class: string; profile?: string; profileClass?: string; role?: string; roleIdentity?: { id: string; layer: "shipped" | "project"; hash: string }; pii: boolean; reason?: string; release?: number | null; priority?: number | null; plannedStart?: number | null; due?: number | null }
   | { type: "overlap"; task: number; owner: string; others: { task: number; owner: string; paths: string[]; symbols?: string[] }[] }
   /** A PII screen verdict (issue #198): what was screened and the closed label, source and category, never the text. */
   | ({ type: "pii_screen" } & ScreenRecord)

package/src/hub/facts.ts

@@ -1,3 +1,5 @@
+import { repoGitArgs, repoGitEnv, type Repo } from "./snapshots.ts";
+import { isHubWritePath } from "./permission-mode.ts";
 import { createHash, randomUUID } from "node:crypto";
 import { closeSync, constants, fstatSync, mkdirSync, openSync, readSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
@@ -54,6 +56,8 @@ export interface FactScope {
 export interface FactsOptions {
   /** The project root, a real absolute path. */
   root: string;
+  /** An explicitly discovered shadow repository; ordinary git retains its existing cwd semantics. */
+  repo?: Repo;
   /** A private directory for the two sides of a diff. */
   tmp: string;
   /** Names this hub run's offers, so an acknowledgement for another run's offer matches nothing. */
@@ -65,9 +69,14 @@ export interface FactsOptions {
   nameable: (s: string) => boolean;
   /** `local.deny` entries: with the one denylist (`src/local/deny.ts`), paths facts never read or show. */
   deny?: string[];
+  /** Configured private paths are never read or shown as automatic facts. */
+  privatePath?: (path: string) => boolean;
+  /** Bounded machine-local projection; absent retains raw/binary behavior. */
+  projection?: (file: string) => import("./text-projection.ts").ProjectedText | undefined;
 }
 
 interface Version {
+  projected?: true;
   hash: string;
   text?: string;
   /** Git's blob id of the same bytes: a file equal to HEAD's is no change, whatever its stat data says. */
@@ -171,11 +180,15 @@ export class Facts {
     this.root = root;
   }
 
+  private gitArgs(args: string[]): string[] { return hubGitArgv(this.o.repo?.shadow ? repoGitArgs(this.o.repo, args) : args); }
+  private gitEnv(): NodeJS.ProcessEnv { return hubGitEnv({ ...(this.o.repo?.shadow ? repoGitEnv(this.o.repo) : process.env), GIT_OPTIONAL_LOCKS: "0" }); }
+
   /**
    * A project-relative path, or undefined for one outside the project. Resolved as a real path (symlinks and `..` are
    * followed first), so neither a task's refs nor a tool's input can point the hub at a file outside the project.
    */
   rel(path: string): string | undefined {
+    if (this.o.privatePath?.(path)) return undefined;
     const abs = isAbsolute(path) ? path : resolve(this.root, path);
     let real = abs;
     try {
@@ -188,7 +201,11 @@ export class Facts {
       }
     }
     const r = relative(this.root, real);
-    if (!r || r.startsWith("..") || isAbsolute(r)) return undefined;
+    if (!r || r.startsWith("..") || isAbsolute(r) || this.o.repo?.shadow && isHubWritePath(r)) return undefined;
+    if (this.o.repo?.shadow) {
+      const ignored = Bun.spawnSync(this.gitArgs(["check-ignore", "--no-index", "--quiet", "--", r]), { cwd: this.root, stdout: "pipe", stderr: "pipe", env: this.gitEnv(), timeout: 3000 });
+      if (ignored.exitCode !== 1) return undefined; // ignored or unavailable policy is not readable fact evidence
+    }
     // Never git's own files, and never what the denylist keeps from every agent.
     return /(^|\/)\.git(\/|$)/i.test(r) || isDenied(r, this.o.deny ?? []) ? undefined : r;
   }
@@ -202,6 +219,8 @@ export class Facts {
    */
   private load(file: string): Omit<Version, "seq"> {
     if (this.rel(join(this.root, file)) !== file) return { hash: "missing" };
+    const projected = this.o.projection?.(join(this.root, file));
+    if (projected) return { hash: projected.rawHash, blob: projected.rawBlob, text: projected.text, projected: true };
     let fd: number | undefined;
     try {
       fd = openSync(join(this.root, file), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
@@ -276,7 +295,7 @@ export class Facts {
     // One path per line: a newline in a name would shift the answers, and git drops a final carriage return (another file).
     files = files.filter((f) => !/[\r\n]/.test(f));
     if (!files.length) return out;
-    const r = Bun.spawnSync(hubGitArgv(["cat-file", "--batch-check=%(objectname) %(objecttype)"]), { cwd: this.root, stdin: new TextEncoder().encode(files.map((f) => `HEAD:./${f}`).join("\n") + "\n"), stdout: "pipe", stderr: "pipe", env: hubGitEnv({ ...process.env, GIT_OPTIONAL_LOCKS: "0" }) });
+    const r = Bun.spawnSync(this.gitArgs(["cat-file", "--batch-check=%(objectname) %(objecttype)"]), { cwd: this.root, stdin: new TextEncoder().encode(files.map((f) => `HEAD:./${f}`).join("\n") + "\n"), stdout: "pipe", stderr: "pipe", env: this.gitEnv() });
     if (r.exitCode !== 0) return out;
     r.stdout.toString().split("\n").forEach((line, i) => {
       const [oid, type] = line.split(" ");
@@ -415,7 +434,7 @@ export class Facts {
       if (!files) {
         // Plumbing only, with optional locks off: an agent's own git commands must never meet a lock the hub holds.
         const git = (...args: string[]) => {
-          const r = Bun.spawnSync(hubGitArgv([...args, "--", p]), { cwd: this.root, stdout: "pipe", stderr: "pipe", env: hubGitEnv({ ...process.env, GIT_OPTIONAL_LOCKS: "0" }) });
+          const r = Bun.spawnSync(this.gitArgs([...args, "--", p]), { cwd: this.root, stdout: "pipe", stderr: "pipe", env: this.gitEnv() });
           return r.exitCode === 0 ? r.stdout.toString().split("\0").filter(Boolean) : undefined;
         };
         // Against HEAD, so a staged change counts (a staged move by both names); a repository without a commit yet has
@@ -497,7 +516,7 @@ export class Facts {
       this.touch(peer, file, pre.version);
       if (["Edit", "MultiEdit", "Write"].includes(tool)) {
         this.wrote(peer, file);
-        const expected = this.latest.get(file)?.hash === pre.version.hash ? applyEdit(pre.version.text, tool, input) : undefined;
+        const expected = !pre.version.projected && this.latest.get(file)?.hash === pre.version.hash ? applyEdit(pre.version.text, tool, input) : undefined;
         const version = this.observe(file, expected === undefined ? undefined : { peer, expected: sha1(expected) });
         const last = this.transitions.get(file)?.at(-1);
         if (last?.seq === version.seq && last.by === peer && this.view(peer).get(file)?.hash === pre.version.hash) this.view(peer).set(file, version);
@@ -506,7 +525,7 @@ export class Facts {
       if (tool === "Read") {
         const version = this.observe(file);
         // Only a whole read of an unchanged file says what the peer saw: no offset or limit, and nothing Read cuts.
-        if (version.hash === pre.version.hash && input.offset === undefined && input.limit === undefined && readWhole(pre.version.text)) this.view(peer).set(file, version);
+        if (!pre.version.projected && version.hash === pre.version.hash && input.offset === undefined && input.limit === undefined && readWhole(pre.version.text)) this.view(peer).set(file, version);
         return this.observeAll();
       }
     }
@@ -534,7 +553,7 @@ export class Facts {
         this.touch(peer, file, was);
         this.wrote(peer, file);
         const now = this.load(file);
-        const matches = was ? codexEffect(was.text, now, change, (a, b) => this.diff(a, b)) : false;
+        const matches = was && !was.projected && !now.projected ? codexEffect(was.text, now, change, (a, b) => this.diff(a, b)) : false;
         const version = this.observe(file, matches ? { peer, expected: now.hash } : undefined);
         const last = this.transitions.get(file)?.at(-1);
         if (was && last?.seq === version.seq && last.by === peer && this.view(peer).get(file)?.hash === was.hash) this.view(peer).set(file, version);
@@ -694,7 +713,7 @@ export class Facts {
   tree(paths: string[], windows: { peer: PeerId; since: number; until?: number }[] = []): string {
     this.boundary();
     const h = createHash("sha1");
-    const head = Bun.spawnSync(hubGitArgv(["rev-parse", "-q", "--verify", "HEAD"]), { cwd: this.root, stdout: "pipe", stderr: "pipe", env: hubGitEnv() });
+    const head = Bun.spawnSync(this.gitArgs(["rev-parse", "-q", "--verify", "HEAD"]), { cwd: this.root, stdout: "pipe", stderr: "pipe", env: this.gitEnv() });
     h.update(head.exitCode === 0 ? head.stdout.toString().trim() : "no-head").update("\0");
     // The files the members wrote while at work in the cohort count too: a symbol-only overlap names no path, and a
     // tool's write outside the named paths still moves the work the integration checked. What they only read never

package/src/hub/git.ts

@@ -18,9 +18,15 @@ import { spawnSync, type SpawnSyncOptionsWithStringEncoding, type SpawnSyncRetur
  * command. GIT_CONFIG_NOSYSTEM/global are left alone: those files are the user's own.
  */
 const SAFE_CONFIG = ["core.fsmonitor=false", "core.hooksPath=/dev/null", "diff.external=", "core.pager=cat", "credential.helper=", "core.askpass="];
+/** Hub memory sync (#258) pushes to the person's own remote: their global credential helper stays, the rest does not. */
+const CREDENTIAL_KEYS = new Set(["credential.helper=", "core.askpass="]);
 
-/** `["git", ...safe options, ...args]`: use instead of a literal "git" argv anywhere under src/. */
-export const hubGitArgv = (args: string[]): string[] => ["git", "--no-pager", ...SAFE_CONFIG.flatMap((c) => ["-c", c]), ...args];
+/**
+ * `["git", ...safe options, ...args]`: use instead of a literal "git" argv anywhere under src/. `credentials` keeps the
+ * person's credential helper, for a repository the hub created itself (the memory store), never a project's.
+ */
+export const hubGitArgv = (args: string[], opts: { credentials?: boolean } = {}): string[] =>
+  ["git", "--no-pager", ...SAFE_CONFIG.filter((c) => !opts.credentials || !CREDENTIAL_KEYS.has(c)).flatMap((c) => ["-c", c]), ...args];
 
 /** The caller's env plus the no-prompt switch; existing keys (childEnv, GIT_OPTIONAL_LOCKS=0) pass through. */
 export const hubGitEnv = (env: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv => ({ ...env, GIT_TERMINAL_PROMPT: "0" });

package/src/hub/github-import.ts

@@ -0,0 +1,28 @@
+import { sdlcGh, type SdlcGh } from "./sdlc.ts";
+export interface GitHubSource { provider: "github"; repo: string; issue: number; url: string; }
+export interface GitHubImportIssue { source: GitHubSource; title: string; detail: string; }
+export interface GitHubImportSelection { repo?: string; label: string; milestone?: string; }
+const REPO=/^[A-Za-z0-9][A-Za-z0-9-]{0,38}\/[A-Za-z0-9_.-]{1,100}$/;
+const selectionText=(value:unknown):value is string=>typeof value==="string"&&value.trim()===value&&value.length>0&&value.length<=100&&!value.startsWith("-")&&!/\p{Cc}/u.test(value);
+/** Read-only issue intake; the existing reader bounds process time, stdout and diagnostics. */
+export async function readGitHubImport(input: GitHubImportSelection, run: SdlcGh=sdlcGh): Promise<{ issues: GitHubImportIssue[]; partial: boolean; }> {
+  if(!selectionText(input.label)||input.label.includes(",")||input.label.includes('"')||input.milestone!==undefined&&!selectionText(input.milestone)||input.repo!==undefined&&!REPO.test(input.repo))throw new Error("invalid GitHub import selection");
+  const {label,milestone}=input;
+  const deadline=performance.now()+10_000;
+  const read=async(args:string[])=>{const left=deadline-performance.now();if(left<=0)throw new Error("GitHub import read deadline expired");const result=await run(args,Math.min(left,10_000),undefined,2*1024*1024);if(performance.now()>deadline)throw new Error("GitHub import read deadline expired");if(result.code!==0||new TextEncoder().encode(result.stdout).length>2*1024*1024)throw new Error("GitHub import read failed or exceeded its output bound");return JSON.parse(result.stdout) as unknown;};
+  let repo=input.repo;
+  if(repo===undefined){const raw=await read(["repo","view","--json","nameWithOwner"]);if(!raw||typeof raw!=="object"||typeof (raw as Record<string,unknown>).nameWithOwner!=="string")throw new Error("GitHub repository identity unavailable");repo=(raw as {nameWithOwner:string}).nameWithOwner;}
+  if(!REPO.test(repo))throw new Error("invalid GitHub repository identity");
+  // ponytail: one bounded page of32 issues; add paginated reads under the shared deadline for larger intake.
+  const args=["issue","list","--repo",repo,"--state","open","--label",label,...(milestone===undefined?[]:["--milestone",milestone]),"--limit","33","--json","number,title,body,url,state"];
+  const raw=await read(args);if(!Array.isArray(raw)||raw.length>33)throw new Error("invalid GitHub issue page");
+  const seen=new Set<number>();
+  const issues=raw.map(row=>{
+    if(!row||typeof row!=="object"||!Number.isSafeInteger(row.number)||row.number<=0||seen.has(row.number)||row.state!=="OPEN"||typeof row.title!=="string"||!row.title.trim()||row.title.length>300||typeof row.body!=="string"||row.body.length>8000||typeof row.url!=="string")throw new Error("invalid GitHub issue data");
+    seen.add(row.number);
+    const expected=`https://github.com/${repo}/issues/${row.number}`;
+    if(row.url.toLowerCase()!==expected.toLowerCase())throw new Error("GitHub issue identity mismatch");
+    return {source:{provider:"github" as const,repo:repo!.toLowerCase(),issue:row.number,url:expected},title:row.title,detail:row.body};
+  });
+  return {issues:issues.slice(0,32),partial:issues.length>32};
+}

package/src/hub/hub-tools.ts

@@ -1,3 +1,7 @@
+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";
+import { SUPPORTED_PEERS, defaultPeerRoles } from "./peer-catalog.ts";
 // The hub's task tools, defined once: the MCP server (Claude plugin, Kimi, Codex) and the local worker both read this.
 import { NOTE_KINDS } from "./envelope.ts";
 
@@ -22,6 +26,9 @@ const plan = {
   additionalProperties: false,
 } as const;
 
+// Accept may target a task from an older project profile; Tasks normalizes by the stored task profile.
+const acceptPlan = { ...plan, properties: { ...plan.properties, sections: list("document heading anchors, such as report.md#methods"), sources: list("citation ids, DOI or source URL ids"), claims: list("short claim ids to verify") } } as const;
+
 export interface HubTool {
   name: string;
   description: string;
@@ -35,14 +42,22 @@ const tool = (name: string, description: string, properties: Record<string, unkn
 });
 
 export const TASK_TOOLS: HubTool[] = [
-  tool("hub_task_propose", "Put a piece of work on the shared task board. The hub assigns an owner by class (routing.toml) unless you name one. Classes: plan, implement, bulk_edit, test, review, summarize, triage. Name the class when you know it; without one the hub tries to pick it. Name yourself as owner to claim work nobody assigned you: it starts in progress. Put the paths the work touches in refs, and when you claim work, a plan; the hub says when they overlap another open task.", { title: str, class: { type: "string", enum: ["plan", "implement", "bulk_edit", "test", "review", "summarize", "triage"] }, detail: str, refs, plan, owner: { type: "string", description: "peer id; yours to claim the work, omit to let the hub route it. With after, the owner is reserved: offered the task first once it is ready" }, after: { type: "array", items: { type: "integer" }, description: "ids of tasks that must be approved first; until then this one waits, offered to nobody, and cannot be claimed" }, urgent: { type: "boolean", description: "hand it over even when its owner is paused for quota only briefly" } }, ["title"]),
-  tool("hub_task_accept", "Take a task that was assigned to you, with your plan for it.", { id, plan }, ["id"]),
+  tool("hub_backlog_list", "Read public backlog cards with planning revisions. Configured planners only; PII remains a stub.", {}),
+  tool("hub_backlog_plan", "Plan an unpinned backlog item outside frozen releases with the revision you read and a bounded reason. A person's rank is retained. Actual dates cannot be set.", { id, revision: { type: "integer", minimum: 0 }, reason: { type: "string", maxLength: 1000 }, fields: { type: "object", properties: { rank: { type: ["integer", "null"], minimum: 0 }, priority: { type: ["integer", "null"], minimum: 0, maximum: 3 }, release: { type: ["integer", "null"], minimum: 1 }, plannedStart: { type: ["integer", "null"], minimum: 1 }, due: { type: ["integer", "null"], minimum: 1 }, deps: { type: "array", maxItems: 64, uniqueItems: true, items: { type: "integer", minimum: 1 } }, reserved: { type: ["string", "null"], minLength: 1, maxLength: 32 } }, additionalProperties: false } }, ["id", "revision", "reason", "fields"]),
+  tool("hub_backlog_pull", "Reserve a WIP slot and pull ready unpinned backlog work into To Do at its current revision. Preserves person order/reservations and frozen scope; pending unowned work can be undone with hub_backlog_undo.", { id, revision: { type: "integer", minimum: 0 }, reason: { type: "string", minLength: 1, maxLength: 1000 } }, ["id", "revision", "reason"]),
+  tool("hub_backlog_split", "Split unstarted backlog work into two to eight staged parts. The original card retains integration/acceptance and depends on the children. Use after for existing prerequisite ids and afterParts for earlier zero-based part indexes. Latest unused unchanged children can be undone with hub_backlog_undo.", { id, revision: { type: "integer", minimum: 0 }, reason: { type: "string", minLength: 1, maxLength: 1000 }, parts: { type: "array", minItems: 2, maxItems: 8, items: { type: "object", properties: { title: { type: "string", minLength: 1, maxLength: 300 }, detail: { type: "string", maxLength: 8000 }, class: str, refs, plan, after: { type: "array", maxItems: 64, uniqueItems: true, items: { type: "integer", minimum: 1 } }, afterParts: { type: "array", maxItems: 8, uniqueItems: true, items: { type: "integer", minimum: 0 } } }, required: ["title"], additionalProperties: false } } }, ["id", "revision", "reason", "parts"]),
+  tool("hub_backlog_undo", "Undo your latest planning change at its current revision. Refuses intervening changes and another actor's edit.", { id, revision: { type: "integer", minimum: 1 } }, ["id", "revision"]),
+  tool("hub_release_list", "Read public release scope and planned/actual dates for phased planning. Configured planners only.", {}),
+
+  tool("hub_task_propose", "Put a piece of work on the shared task board. The hub assigns an owner by class (routing.toml) unless you name one. Classes: plan, implement, bulk_edit, test, review, summarize, triage. Name the class when you know it; without one the hub tries to pick it. Name yourself as owner to claim work nobody assigned you: it starts in progress. Put the paths the work touches in refs, and when you claim work, a plan; the hub says when they overlap another open task.", { title: str, class: { type: "string", enum: ["plan", "implement", "bulk_edit", "test", "review", "summarize", "triage"] }, detail: str, role: { type: "string", description: "catalog role id for this task class; guidance only, no routing or authority change" }, refs, plan, owner: { type: "string", description: "peer id; yours to claim the work, omit to let the hub route it. With after, the owner is reserved: offered the task first once it is ready" }, after: { type: "array", items: { type: "integer" }, description: "ids of tasks that must be approved first; until then this one waits, offered to nobody, and cannot be claimed" }, backlog: { type: "boolean", description: "stage unoffered work; owner is only a reservation, even when naming yourself" }, urgent: { type: "boolean", description: "hand it over even when its owner is paused for quota only briefly" }, goal: { type: "string", description: "id of this project's long-term task (ahub goal list) the work is part of" } }, ["title"]),
+  tool("hub_task_accept", "Take a task that was assigned to you, with your plan for it.", { id, plan: acceptPlan }, ["id"]),
   tool("hub_task_decline", "Pass on a task assigned to you; the hub offers it to the next peer.", { id, reason: str }, ["id"]),
   tool("hub_task_done", "Mark your task finished. It goes to its reviewer with your summary and refs. 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"] }, 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. Two changes_requested in a row move the task to another peer.", { id, 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" } }, ["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. Two changes_requested in a row 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" } }, ["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_remember", "Save a decision, finding, contract or fail to the memory all agents share (claude-mem); the other agents also get it with their next message. A fail is an approach you tried that does not work, and why: the most useful note, it stops the others spending their quota on it. Do not retry what a fail note rules out without new evidence. Conclusions worth recalling, not chatter.", { text: str, title: str, kind: { type: "string", enum: [...NOTE_KINDS] }, task: id }, ["text"]),
+  tool("hub_remember", "Save a decision, finding, contract or fail to the memory all agents share (the hub's memory and claude-mem); the other agents also get it with their next message. A fail is an approach you tried that does not work, and why: the most useful note, it stops the others spending their quota on it. Do not retry what a fail note rules out without new evidence. Conclusions worth recalling, not chatter. A note on an open task is short-term until the task is approved, when its decisions, contracts and fails become long-term; horizon long keeps it now, scope shared lets the person's other projects find it.", { text: str, title: str, kind: { type: "string", enum: [...NOTE_KINDS] }, task: id, horizon: { type: "string", enum: ["short", "long"] }, scope: { type: "string", enum: ["project", "shared"] } }, ["text"]),
 ];
 
 export const TASK_TOOL_NAMES = new Set(TASK_TOOLS.map((t) => t.name));
@@ -51,9 +66,9 @@ 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", "Move a task to another peer, as the conductor, or redirect a task you proposed while it is proposed and nobody accepted it. A task that still waits gets the peer as its reserved owner. When you have an explicit capabilities list, the conductor needs assign capability for any assign, the proposer only to hand the task to another peer.", { id, peer: str }, ["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 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_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, 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: ["local", "kimi", "pi", "claude", "codex"] } }, ["peer"]),
+  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: ["local", "kimi", "pi", ...SUPPORTED_PEERS.filter(peer => !["local", "kimi", "pi"].includes(peer))] } }, ["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"]),
   tool("hub_peer_release", "Release only the conductor hold you placed. Never lifts a person's hold or a budget pause.", { peer: str }, ["peer"]),
 ];
@@ -68,10 +83,34 @@ export const ROLE_TEXT: Record<string, string> = {
   reviewer: "reviewer: when asked to review, read the change itself, then hub_review with approved or changes_requested and a note that says what to fix.",
 };
 
-export const DEFAULT_ROLES: Record<string, string[]> = { claude: ["planner", "reviewer"], codex: ["implementer"], kimi: ["implementer", "verifier"], local: ["implementer", "verifier"], pi: ["implementer", "verifier"] };
+export const DEFAULT_ROLES: Record<string, string[]> = defaultPeerRoles(true);
 
-export function roleContract(peer: string, roles: Record<string, string[]> = DEFAULT_ROLES): string {
-  const mine = (roles[peer] ?? []).map((r) => ROLE_TEXT[r]).filter(Boolean);
+export function roleContract(peer: string, roles: Record<string, string[]> = DEFAULT_ROLES, catalog: CatalogRole[] = [], profile: ProfileSelection = "dev"): string {
+  const data = profileData(profile);
+  const mine = (roles[peer] ?? []).map((r) => data.role_text[r] ?? ROLE_TEXT[r]).filter(Boolean);
   if (!mine.length) return "";
-  return [`Your roles in this project ("${peer}"):`, ...mine.map((t) => `- ${t}`), "The task board (hub_task_list) is the shared record of who does what."].join("\n");
+  return [`Your roles in this project ("${peer}"):`, ...mine.map((t) => `- ${t}`), ...(data !== projectProfile("dev") ? [`Project profile ${data.name}: classes ${Object.entries(data.classes).map(([name, base]) => `${name}=${base}`).join(", ")}. Profile guidance grants no authority.`] : []), ...(catalog.length ? [catalogSection(catalog)] : []), "The task board (hub_task_list) is the shared record of who does what."].join("\n");
+}
+
+/** Profile schemas are data over the existing tools; dev retains the exact existing definitions. */
+export function profileTaskTools(profile: ProfileSelection = "dev", stages?: readonly string[]): HubTool[] {
+  const customStages = stages && (stages.length !== SDLC_STAGES.length || stages.some((s, i) => s !== SDLC_STAGES[i]));
+  const customProfile = !(profile === "dev" || profileData(profile) === projectProfile("dev"));
+  if (!customStages && !customProfile) return TASK_TOOLS;
+  const data = profileData(profile);
+  return TASK_TOOLS.map(tool => {
+    const properties = { ...tool.inputSchema.properties };
+    if (customStages && tool.name === "hub_sdlc_record") {
+      const receipt = properties.receipt as { type: string; properties: Record<string, unknown>; additionalProperties: boolean };
+      properties.receipt = { ...receipt, properties: { ...receipt.properties, stage: { type: "string", enum: [...(stages ?? SDLC_STAGES)] } } };
+    }
+    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 && 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")])) };
+      properties.parts = { ...parts, items: { ...parts.items, properties: { ...parts.items.properties, plan: selectedPlan } } };
+    }
+    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 } };
+  });
 }

package/src/hub/inference.ts

@@ -168,7 +168,7 @@ export interface ScreenRecord {
   task?: number;
   item: ScreenItem;
   label: "pii" | "clear";
-  source: "regex" | "screen" | "unknown";
+  source: "regex" | "screen" | "unknown" | "inherited";
   category?: PiiCategory;
   miss?: ScreenMiss;
   ms?: number;

package/src/hub/lifecycle-schema.ts

@@ -0,0 +1,17 @@
+import { ControlClient } from "./control-client.ts";
+import { SDLC_STAGES } from "./sdlc.ts";
+/** The daemon owns the active definition. Unavailable reads never invent a project-file stage set. */
+export async function activeLifecycleStages(stateDir: string, peer: string, projectRoot: string, active?: ControlClient): Promise<string[] | 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;
+    // A live older daemon has the fixed seven-stage contract and no optional metadata field.
+    if (!Object.hasOwn(reply.status, "lifecycleStages")) return [...SDLC_STAGES];
+    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] as string[];
+  } catch { return undefined; }
+  finally { if (client !== active) client?.close(); }
+}

package/src/hub/listen.ts

@@ -0,0 +1,15 @@
+/** Keep rejected owned listeners bound until a replacement cannot reuse their ports. */
+export function listenWithoutPortCollision<T extends { port?: number; stop(closeActiveConnections?: boolean): void }>(listen: () => T, reservedPorts: readonly number[]): T {
+  const reserved = new Set(reservedPorts.filter(port => Number.isSafeInteger(port) && port > 0));
+  const temporary: T[] = [];
+  try {
+    for (let attempt = 0; attempt <= reserved.size; attempt++) {
+      const candidate = listen();
+      if (!reserved.has(candidate.port ?? -1)) return candidate;
+      temporary.push(candidate);
+    }
+    throw new Error("automatic control listener could not avoid requested peer ports");
+  } finally {
+    for (const listener of temporary) listener.stop(true);
+  }
+}

package/src/hub/manager.ts

@@ -1,3 +1,5 @@
+import { BACKLOG_SPLIT_SCREEN_TIMEOUT_MS } from "./planning.ts";
+import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
 import { Database } from "bun:sqlite";
 import { randomBytes, randomUUID } from "node:crypto";
 import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
@@ -153,18 +155,23 @@ export async function startManager(options: ManagerOptions = {}): Promise<Manage
           return { ok: true };
         }
         // The settings actions (#269) reach the project hub as an ordinary session's: this dashboard opens no settings session.
-        if (!["snapshot", "send", "pause", "resume", "permit", "propose", "assign", "setting", "setting_undo", "setting_preview", "start_peer"].includes(String(input.action))) return { ok: false, error: "invalid dashboard action" };
+        if (!["snapshot", "send", "pause", "resume", "permit", "propose", "assign", "backlog_pull", "backlog_return", "planning", "planning_undo", "planner_pull", "backlog_split", "release_new", "release_change", "setting", "setting_undo", "setting_preview", "start_peer", "sdlc_queue", "sdlc_release"].includes(String(input.action))) return { ok: false, error: "invalid dashboard action" };
         client = await ControlClient.connect(project.stateDir, { role: "console", projectId: project.id, projectRoot: project.root, instanceId: input.instanceId });
-        const nominalMs = input.action === "start_peer" ? MAX_COMMAND_MS + 5_000 : 10_000;
+        const deliveryRead = input.action === "sdlc_queue" || input.action === "sdlc_release";
+        let nominalMs = 10_000;
+        if (input.action === "start_peer") nominalMs = MAX_COMMAND_MS + 5_000;
+        else if (input.action === "backlog_split") nominalMs = BACKLOG_SPLIT_SCREEN_TIMEOUT_MS + HUB_DB_BUSY_TIMEOUT_MS + 5_000;
+        else if (deliveryRead) nominalMs = 30_000;
         const timeoutMs = options.forwardTimeoutMs?.(String(input.action), nominalMs) ?? nominalMs;
         const result = await client.request(input.action === "snapshot"
-          ? { t: "ui_snapshot", after: input.after ?? 0 }
+          ? { t: "ui_snapshot", after: input.after ?? 0, ...(input.memory !== undefined ? { memory: input.memory } : {}) }
           : { t: "ui_action", action: input, instanceId: input.instanceId }, timeoutMs);
         // ControlClient resolves its deadline as this exact sentinel; a hub refusal stays a known failure.
-        if (input.action === "start_peer" && result.ok === false && result.error === `no answer from the hub within ${Math.round(timeoutMs / 1000)} s`) {
-          const text = "Start result is unconfirmed. Check the Peers panel before retrying; the hub may still be starting the peer.";
+        if (["start_peer", "backlog_split"].includes(String(input.action)) && result.ok === false && result.error === `no answer from the hub within ${Math.round(timeoutMs / 1000)} s`) {
+          const text = input.action === "backlog_split" ? "Split result is unconfirmed. Reload the task before retrying; the hub may still commit its children." : "Start result is unconfirmed. Check the Peers panel before retrying; the hub may still be starting the peer.";
           return { ok: false, unconfirmed: true, text, error: text };
         }
+        if (deliveryRead) { const { rid: _transportId, ...report } = result; return report; }
         return result;
       } catch (error) { return { ok: false, error: safeError(error) }; }
       finally { client?.close(); }

package/src/hub/path-policy.ts

@@ -0,0 +1,96 @@
+import { lstatSync, opendirSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { realPath } from "./project.ts";
+/** Bounded project-relative exact paths/subtrees or *, ? and whole-segment ** globs. */
+export function policyPaths(raw: unknown, field: string): string[] {
+  if (raw === undefined) return [];
+  if (!Array.isArray(raw) || raw.length > 64 || raw.some(p => typeof p !== "string" || !p || p.length > 200 || isAbsolute(p) || /[\[\]{}!]/.test(p) || /[\x00-\x1f\x7f]/.test(p) || p.split(/[\\/]/).includes("..") ||
+    (/[?*]/.test(p) && (p.includes("\\") || (p.match(/[?*]/g)?.length ?? 0) > 16 || p.split("/").some(s => s.includes("**") && s !== "**"))))) throw new Error(`${field} takes up to 64 bounded project-relative paths or *, ? and whole-segment ** globs`);
+  return [...new Set(raw.map(p => p.replace(/\/+/g, "/").replace(/\/$/, "") || "."))];
+}
+function existing(path: string): boolean { try { lstatSync(path); return true; } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return false; throw error; } }
+/** Resolve the deepest existing ancestor, retaining dangling links as failures. */
+export function policyRealPath(path: string): string {
+  let ancestor = path;
+  while (!existing(ancestor)) { const parent = dirname(ancestor); if (parent === ancestor) throw new Error("path cannot be resolved"); ancestor = parent; }
+  return join(realPath(ancestor), relative(ancestor, path));
+}
+const beneath = (path: string, root: string) => { path = path.toLowerCase(); root = root.toLowerCase(); return path === root || path.startsWith(root.endsWith(sep) ? root : root + sep); };
+export function policyTargets(cwd: string, paths: string[]): string[] {
+  const root = realPath(cwd);
+  return [...new Set(paths.flatMap(path => { const lexical = resolve(root, path); return [lexical, policyRealPath(lexical)]; }))];
+}
+/** Linear-space wildcard DP, avoiding regex backtracking on untrusted paths. */
+function segmentMatches(pattern: string, name: string): boolean {
+  const chars = [...name.toLowerCase()];
+  let previous = new Array<boolean>(chars.length + 1).fill(false); previous[0] = true;
+  for (const char of pattern.toLowerCase()) {
+    const next = new Array<boolean>(chars.length + 1).fill(false);
+    next[0] = char === "*" && previous[0]!;
+    for (let i = 1; i <= chars.length; i++) next[i] = char === "*" ? previous[i]! || next[i - 1]! : previous[i - 1]! && (char === "?" || char === chars[i - 1]);
+    previous = next;
+  }
+  return previous[chars.length]!;
+}
+function closure(pattern: string[], states: Set<number>): Set<number> {
+  const out = new Set(states);
+  for (const i of out) if (pattern[i] === "**") out.add(i + 1);
+  return out;
+}
+function advance(pattern: string[], states: Set<number>, name: string): Set<number> {
+  const next = new Set<number>();
+  for (const i of closure(pattern, states)) {
+    if (pattern[i] === "**") next.add(i);
+    else if (pattern[i] !== undefined && segmentMatches(pattern[i]!, name)) next.add(i + 1);
+  }
+  return closure(pattern, next);
+}
+function patternScope(pattern: string[], states: Set<number>, path: string, includeParents: boolean): boolean {
+  if (isAbsolute(path) || path === ".." || path.startsWith("../")) return false;
+  states = closure(pattern, states);
+  if (states.has(pattern.length)) return true;
+  for (const name of path.split("/").filter(p => p && p !== ".")) {
+    states = advance(pattern, states, name);
+    if (states.has(pattern.length)) return true; // a matched directory protects its entire subtree
+    if (!states.size) return false;
+  }
+  return includeParents && states.size > 0; // this scope can contain a future protected descendant
+}
+/** Resolve wildcard directory aliases without trusting a cached expansion. Bound all filesystem discovery. */
+function globScope(root: string, lexical: string, actual: string, path: string, includeParents: boolean, budget: { entries: number }): boolean {
+  const pattern = path.split("/").filter(p => p && p !== ".");
+  const start = closure(pattern, new Set([0]));
+  if (patternScope(pattern, start, relative(root, lexical), includeParents) || patternScope(pattern, start, relative(root, actual), includeParents)) return true;
+  const visit = (dir: string, states: Set<number>, depth: number, ancestors: Set<string>): boolean => {
+    const real = policyRealPath(dir);
+    if (states.has(pattern.length)) return beneath(lexical, real) || beneath(actual, real) || includeParents && (beneath(real, lexical) || beneath(real, actual));
+    if (patternScope(pattern, states, relative(real, actual), includeParents)) return true;
+    if (!existing(dir)) return false;
+    if (!beneath(real, root)) throw new Error("policy glob discovery outside project");
+    const info = statSync(dir);
+    if (!info.isDirectory()) return false;
+    if (depth > 32 || ancestors.has(real) || budget.entries > 4096) throw new Error("policy glob discovery unavailable");
+    const chain = new Set(ancestors); chain.add(real);
+    const handle = opendirSync(dir);
+    try {
+      for (let entry = handle.readSync(); entry; entry = handle.readSync()) {
+        if (++budget.entries > 4096) throw new Error("policy glob discovery unavailable");
+        const next = advance(pattern, states, entry.name);
+        if (next.size && visit(join(dir, entry.name), next, depth + 1, chain)) return true;
+      }
+    } finally { handle.closeSync(); }
+    return false;
+  };
+  return visit(root, start, 0, new Set());
+}
+/** Compare declared spelling, real targets and wildcard aliases. Unknown discovery conservatively protects. */
+export function matchesPolicy(cwd: string, path: string, paths: string[], includeParents = false): boolean {
+  if (!paths.length) return false;
+  try {
+    if (path.length > 4096) return true;
+    const root = realPath(cwd), lexical = resolve(root, path), actual = policyRealPath(lexical);
+    includeParents &&= !existing(lexical) || statSync(lexical).isDirectory();
+    const budget = { entries: 0 };
+    return paths.some(entry => /[?*]/.test(entry) ? globScope(root, lexical, actual, entry, includeParents, budget) : policyTargets(root, [entry]).some(target => beneath(lexical, target) || beneath(actual, target) || (includeParents && (beneath(target, lexical) || beneath(target, actual)))));
+  } catch { return true; }
+}

package/src/hub/peer-catalog.ts

@@ -0,0 +1,28 @@
+/** Native peers the hub knows; membership checks share this list. */
+export const KNOWN_PEERS = ["claude", "codex", "kimi", "pi", "local"] as const;
+/** Optional production peers are added explicitly; legacy defaults remain stable. */
+export const OPTIONAL_PEERS = ["qwen", "jcode"] as const;
+export const SUPPORTED_PEERS = [...KNOWN_PEERS, ...OPTIONAL_PEERS] as const;
+export type KnownPeer = typeof SUPPORTED_PEERS[number];
+
+export const isKnownPeer = (value: unknown): value is KnownPeer =>
+  typeof value === "string" && (KNOWN_PEERS as readonly string[]).includes(value);
+
+export const isSupportedPeer = (value: unknown): value is KnownPeer =>
+  typeof value === "string" && (SUPPORTED_PEERS as readonly string[]).includes(value);
+
+// Policy metadata, not a membership list. Preserve DEFAULT_ROLES' existing key order.
+const PEER_ROLES: Record<KnownPeer, readonly string[]> = {
+  claude: ["planner", "reviewer"],
+  codex: ["implementer"],
+  kimi: ["implementer", "verifier"],
+  local: ["implementer", "verifier"],
+  pi: ["implementer", "verifier"],
+  qwen: ["implementer", "verifier"],
+  jcode: ["implementer", "verifier"],
+};
+
+/** Each caller owns its role arrays; changing a project's defaults cannot change another's. */
+export function defaultPeerRoles(includeOptional = false): Record<string, string[]> {
+  return Object.fromEntries(Object.entries(PEER_ROLES).filter(([peer]) => includeOptional || !(OPTIONAL_PEERS as readonly string[]).includes(peer)).map(([peer, roles]) => [peer, [...roles]]));
+}