@staix/agent-hub 0.23.1 → 0.25.0

package/src/hub/envelope.ts

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

package/src/hub/events.ts

@@ -22,7 +22,10 @@ export type HubEvent =
   | { type: "config_edit"; file: "config.local.json" | "sdlc.toml"; paths: { path: string; before: string | null; after: string | null }[]; fileBefore: string; fileAfter: string; tier: 2 | 3; by: "person"; source: "dashboard" | "terminal"; backup?: string; reason?: string }
   /** #445 C2: an invocation's ids, class and outcome. Never an argument, a result or a description. */
   | { type: "invocation"; id: string; caller: string; target: string; capability: string; class: string; outcome: string; task?: number; bytes?: number }
-  | { type: "envelope"; id: string; from: string; to?: string[]; priority: string; hop: number; kind?: string; task?: string; bytes?: number; private?: boolean; dropped?: string }
+  /** `origin` (#604 PR B): the sending connection's role, peer and launch or instance id. Never a path or text; absent for an envelope the hub itself wrote. */
+  | { type: "envelope"; id: string; from: string; to?: string[]; priority: string; hop: number; kind?: string; task?: string; bytes?: number; private?: boolean; dropped?: string; origin?: import("./provenance.ts").Origin }
+  /** #604 PR B: one per peer-role or tools-role hello, with the same fields an envelope's `origin` carries. No cwd, root or token. */
+  | ({ type: "attach" } & import("./provenance.ts").Origin)
   | { type: "overflow" | "undeliverable"; id: string; from: string; peer: string }
   | { type: "stale"; id: string; from: string; peer: string; task?: string }
   | { type: "quiet"; id: string; from: string; peers: string[] }

package/src/hub/execution-budget.ts

@@ -91,6 +91,18 @@ export class ExecutionBudget {
     return this.scopes(taskIds, peer).length > 0;
   }
 
+  /** Capability comes from the resolved instance definition, never the peer's spelling. */
+  instrumented(peer: string): boolean { return definitionOf(peer, this.instances)?.budget?.instrumented === true; }
+
+  /** The named budget must cover this task and owner; another applicable budget proves nothing. */
+  covers(id: string, taskId: number, peer: string, resources: readonly ExecutionUnit[]): boolean {
+    if (!this.instrumented(peer) || !resources.every(unit => UNITS.has(unit) && unit !== "tokens")) return false;
+    const row = this.scopes([taskId], peer).find(row => row.id === id);
+    if (!row) return false;
+    const limits = fromRow(row).limits;
+    return resources.every(unit => limits[unit] !== undefined && !(unit === "model_calls" && limits.tokens !== undefined));
+  }
+
   private scopes(taskIds: number[], peer: string): BudgetRow[] {
     const ids = [...new Set(taskIds.filter((id) => Number.isSafeInteger(id) && id > 0))];
     const taskRows = ids.length

package/src/hub/handoff.ts

@@ -0,0 +1,126 @@
+// Cross-project task handoff (#604, agent-hub#1030). Pure: values in, values out, no clock, no file system, no socket. The daemon, the registry and the control client are
+// passed in as data or as small ports, so every refusal here is testable without a second daemon and the policy cannot drift from what the daemon enforces.
+import { CLASSES, type TaskClass } from "./board.ts";
+
+/**
+ * What crosses projects, and nothing else: no memory, evidence, turn content or task history (#1030 design 5). The per-field limits alone allow about 13 KB, so `bodyBytes` is the real
+ * ceiling on the whole request: a body that fills several fields is refused whole, and no partial task is built from it.
+ */
+export const HANDOFF_LIMITS = Object.freeze({ title: 300, detail: 4000, paths: 16, path: 512, issue: 2_000_000_000, bodyBytes: 8 * 1024 });
+export const HANDOFF_FIELDS = Object.freeze(["project", "title", "class", "detail", "paths", "issue", "task"] as const);
+
+export type HandoffRefusalCode =
+  | "invalid" | "too_large" | "unregistered" | "same_project" | "not_running" | "older_target" | "pii_turn" | "pii_task" | "no_authority";
+
+/** A refusal always names its reason, and for the person-fixable ones the action. The code is for tests and logs, the message for the caller. */
+export class HandoffRefusal extends Error {
+  constructor(readonly code: HandoffRefusalCode, message: string) { super(message); this.name = "HandoffRefusal"; }
+}
+
+/** `task` is the caller's OWN task this handoff comes from, so a `[pii]` one is refused and the target can name it in the follow-back. It never crosses as text. */
+export interface HandoffRequest { title: string; class: TaskClass; detail: string; paths: string[]; issue?: number; task?: number }
+
+const hasControl = (text: string): boolean => /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/.test(text);
+
+/**
+ * Callers are models, and MCP schemas are not enforced on the way in: parse closed. An unknown field, an accessor or a non-plain object is refused, never dropped,
+ * because a dropped field is a request the caller thinks it made. The result is sized, so an oversized body is refused whole and no partial task is built from it.
+ */
+export function parseHandoff(input: unknown): HandoffRequest & { project: string } {
+  if (!input || typeof input !== "object" || Array.isArray(input) || ![Object.prototype, null].includes(Object.getPrototypeOf(input)) || Object.getOwnPropertySymbols(input).length)
+    throw new HandoffRefusal("invalid", "handoff must be a plain data object");
+  const descriptors = Object.getOwnPropertyDescriptors(input);
+  for (const [key, descriptor] of Object.entries(descriptors)) {
+    if (!(HANDOFF_FIELDS as readonly string[]).includes(key)) throw new HandoffRefusal("invalid", `handoff has an unknown field: ${key.slice(0, 40)}`);
+    if (!Object.hasOwn(descriptor, "value")) throw new HandoffRefusal("invalid", `handoff field ${key} is an accessor`);
+  }
+  const field = (name: (typeof HANDOFF_FIELDS)[number]): unknown => descriptors[name]?.value;
+  const text = (value: unknown, name: string, max: number, required: boolean): string => {
+    if (value === undefined || value === null || value === "") { if (required) throw new HandoffRefusal("invalid", `handoff ${name} is required`); return ""; }
+    if (typeof value !== "string") throw new HandoffRefusal("invalid", `handoff ${name} must be text`);
+    if (hasControl(value)) throw new HandoffRefusal("invalid", `handoff ${name} has control characters`);
+    if (Buffer.byteLength(value, "utf8") > max * 4) throw new HandoffRefusal("too_large", `handoff ${name} is over ${max} characters`);
+    if ([...value].length > max) throw new HandoffRefusal("too_large", `handoff ${name} is over ${max} characters`);
+    return value;
+  };
+  const project = text(field("project"), "project", HANDOFF_LIMITS.path, true).trim();
+  if (!project) throw new HandoffRefusal("invalid", "handoff project is required");
+  const title = text(field("title"), "title", HANDOFF_LIMITS.title, true).replace(/\s+/g, " ").trim();
+  if (!title) throw new HandoffRefusal("invalid", "handoff title is required");
+  const detail = text(field("detail"), "detail", HANDOFF_LIMITS.detail, false);
+  const cls = field("class") === undefined || field("class") === null || field("class") === "" ? "implement" : field("class");
+  if (typeof cls !== "string" || !(CLASSES as readonly string[]).includes(cls)) throw new HandoffRefusal("invalid", `handoff class must be one of ${CLASSES.join(", ")}`);
+  const rawPaths = field("paths");
+  if (rawPaths !== undefined && rawPaths !== null && (!Array.isArray(rawPaths) || Object.keys(rawPaths).length !== rawPaths.length)) throw new HandoffRefusal("invalid", "handoff paths must be a dense list of text");
+  if (Array.isArray(rawPaths) && rawPaths.length > HANDOFF_LIMITS.paths) throw new HandoffRefusal("too_large", `handoff has more than ${HANDOFF_LIMITS.paths} paths`);
+  const paths = (Array.isArray(rawPaths) ? rawPaths : []).map(path => {
+    const value = text(path, "path", HANDOFF_LIMITS.path, true).trim();
+    // Paths are the target's, repository-relative: an absolute path or a parent step names a place on this machine, not a file in the target's tree.
+    if (!value || value.startsWith("/") || value.startsWith("~") || /^[A-Za-z]:[\\/]/.test(value) || value.split(/[\\/]/).includes("..")) throw new HandoffRefusal("invalid", "handoff paths are repository-relative: no absolute path, ~ or ..");
+    return value;
+  });
+  const rawIssue = field("issue");
+  let issue: number | undefined;
+  if (rawIssue !== undefined && rawIssue !== null && rawIssue !== "") {
+    issue = typeof rawIssue === "string" && /^[1-9]\d{0,9}$/.test(rawIssue) ? Number(rawIssue) : rawIssue as number;
+    if (typeof issue !== "number" || !Number.isSafeInteger(issue) || issue < 1 || issue > HANDOFF_LIMITS.issue) throw new HandoffRefusal("invalid", "handoff issue must be a positive issue number in the target's repository");
+  }
+  const rawTask = field("task");
+  let task: number | undefined;
+  if (rawTask !== undefined && rawTask !== null && rawTask !== "") {
+    task = typeof rawTask === "string" && /^[1-9]\d{0,9}$/.test(rawTask) ? Number(rawTask) : rawTask as number;
+    if (typeof task !== "number" || !Number.isSafeInteger(task) || task < 1 || task > HANDOFF_LIMITS.issue) throw new HandoffRefusal("invalid", "handoff task must be a positive task id of this project");
+  }
+  const request = { project, title, class: cls as TaskClass, detail, paths, ...(issue === undefined ? {} : { issue }), ...(task === undefined ? {} : { task }) };
+  if (Buffer.byteLength(JSON.stringify(request), "utf8") > HANDOFF_LIMITS.bodyBytes) throw new HandoffRefusal("too_large", `handoff is over ${HANDOFF_LIMITS.bodyBytes} bytes`);
+  return request;
+}
+
+export interface RegisteredProject { id: string; root: string; stateDir: string }
+export interface TargetDescriptor { features?: readonly string[]; instanceId?: string; projectId?: string; cwd?: string }
+
+/**
+ * The target is named by canonical root or id and must be registered. The caller's own project and an unregistered name are refused here, before anything is read from a
+ * state directory. `canonical` resolves a typed path the way the registry does (`realPath`, never `realpathSync`), so a symlinked temporary root matches its registration.
+ */
+export function resolveTarget(name: string, projects: readonly RegisteredProject[], self: { id: string; root: string }, canonical: (path: string) => string): RegisteredProject {
+  const typed = name.trim();
+  let resolved: string | undefined;
+  try { resolved = typed.startsWith("/") || typed.startsWith("~") || typed.startsWith(".") ? canonical(typed) : undefined; } catch { resolved = undefined; }
+  const match = projects.find(project => project.id === typed || (resolved !== undefined && project.root === resolved));
+  if (!match) throw new HandoffRefusal("unregistered", "that project is not in this machine's agent-hub registry; run `ahub projects` to see the registered ones, or `ahub up` in that project once");
+  if (match.id === self.id || match.root === self.root) throw new HandoffRefusal("same_project", "that is this project: a task for this project goes through hub_task_propose");
+  return match;
+}
+
+/** What the target's own status descriptor says. A daemon that is not running, or does not know the handoff, is refused with the person's action. */
+export function checkTarget(project: RegisteredProject, descriptor: TargetDescriptor | undefined): void {
+  if (!descriptor) throw new HandoffRefusal("not_running", `the hub of ${project.id} is not running; run \`ahub up\` in ${project.root}, then hand the task off again (handoffs are not queued)`);
+  if (descriptor.projectId !== undefined && descriptor.projectId !== project.id) throw new HandoffRefusal("not_running", `the hub answering for ${project.root} belongs to another project; run \`ahub up\` in ${project.root}`);
+  if (!descriptor.features?.includes("task_handoff")) throw new HandoffRefusal("older_target", `the hub of ${project.id} is too old to take a handoff (no task_handoff feature): upgrade the target hub with \`ahub upgrade\` in ${project.root}`);
+}
+
+/** The states a target reports back, in the order a task can reach them. `declined` is the owner passing; the task then returns to the target's routing, so it is information, not an end. */
+export const HANDOFF_EVENTS = Object.freeze(["accepted", "in_review", "approved", "declined", "cancelled"] as const);
+export type HandoffEvent = (typeof HANDOFF_EVENTS)[number];
+
+/** Map a target's task history entry to the event the origin is told about, or undefined for every other entry. Reads only the event name and the task state, never a note. */
+export function handoffEventFor(entryEvent: string, state: string): HandoffEvent | undefined {
+  // The names are what `Tasks` writes (observed: accept writes "accepted", a done leaves the task in_review, the verdict writes "approved", a decline "declined", a cancel "cancelled").
+  if (entryEvent === "accepted" && state === "in_progress") return "accepted";
+  if (entryEvent === "declined") return "declined";
+  if (entryEvent === "cancelled" && state === "cancelled") return "cancelled";
+  if (entryEvent === "done" && state === "in_review") return "in_review";
+  if (entryEvent === "approved" && state === "approved") return "approved";
+  // A class with no reviewer: the done itself approves (`in_progress -> approved`), so the origin hears "approved" for that entry, not "in review".
+  if (entryEvent === "done" && state === "approved") return "approved";
+  return undefined;
+}
+
+const SHA = /^[0-9a-f]{40}$/;
+/** One line, no free text from the target beyond a PR number and a head: `agent-hub task 123 approved: PR #7 at <sha>`. */
+export function followBackLine(remoteTask: number, event: HandoffEvent, evidence: { pr?: unknown; head?: unknown } = {}): string {
+  const pr = typeof evidence.pr === "number" && Number.isSafeInteger(evidence.pr) && evidence.pr > 0 ? ` PR #${evidence.pr}` : "";
+  const head = typeof evidence.head === "string" && SHA.test(evidence.head) ? ` at ${evidence.head}` : "";
+  return `agent-hub task ${remoteTask} ${event.replace("_", " ")}${pr || head ? `:${pr}${head}` : ""}`;
+}

package/src/hub/hub-tools.ts

@@ -8,7 +8,7 @@ import { NOTE_KINDS } from "./envelope.ts";
 
 /** Restricted to the fixed current-child tools server, never an ordinary peer tool. */
 /** The fixed MCP surface of a current owned implementer child; independent of broader project roles. */
-export const IMPLEMENTER_HUB_TOOL_NAMES: readonly string[] = Object.freeze(["hub_task_accept", "hub_task_decline", "hub_task_done", "hub_checkpoint", "hub_send", "hub_task_show", "hub_task_propose", "hub_remember", "hub_inbox", "hub_permission_request"]);
+export const IMPLEMENTER_HUB_TOOL_NAMES: readonly string[] = Object.freeze(["hub_task_accept", "hub_task_decline", "hub_task_done", "hub_checkpoint", "hub_send", "hub_task_show", "hub_task_propose", "hub_remember", "hub_inbox", "hub_permission_request", "hub_study_show", "hub_study_handoff"]);
 
 export const IMPLEMENTER_PERMISSION_TOOL = {
   name: "hub_permission_request",
@@ -81,6 +81,10 @@ const tool = (name: string, description: string, properties: Record<string, unkn
   inputSchema: { type: "object", properties, required, additionalProperties: false },
 });
 
+/** #601: a campaign's contract and handoff are model-written text about its sources. The write tools' arguments and every study result stay out of memory capture. */
+export const STUDY_TOOLS = new Set(["hub_study_draft", "hub_study_revise", "hub_study_show", "hub_study_handoff"]);
+/** #604: a handoff's arguments cross to another project, so neither tool's arguments nor result are captured to memory. */
+export const HANDOFF_TOOLS = new Set(["hub_task_handoff", "hub_task_handoffs"]);
 export const BOUNDED_TASK_TOOLS = new Set(["hub_task_spec", "hub_check_start", "hub_check_result", "hub_check_cancel"]);
 /** #445 C1: what a peer lists and publishes. Their text is another agent's words, so neither call is captured to memory. */
 export const CAPABILITY_TOOLS = new Set(["hub_capabilities", "hub_capabilities_publish", "hub_invoke"]);
@@ -96,6 +100,12 @@ export const TASK_TOOLS: HubTool[] = [
   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_study_draft", "Store a research campaign contract as a DRAFT revision 1 on an approved parent task. Configured planners only; it creates no task, dispatches nothing and never approves (only the person approves, with ahub study approve). The contract is data: question, scope, exclusions, sourceIds, units, deliverableSections, stopPolicy and an optional budget.", { parentTaskId: id, contract: { type: "object" } }, ["parentTaskId", "contract"]),
+  tool("hub_study_revise", "Store the next DRAFT revision of a research campaign with the revision you read. Configured planners only; a stale revision refuses, and a draft holds older bound work until the person approves it. Never approves.", { id: str, revision: { type: "integer", minimum: 1 }, contract: { type: "object" } }, ["id", "revision", "contract"]),
+  tool("hub_study_show", "Read a research campaign's coverage and stop projection: per unit round, state, handoff completeness and budget support, and why dispatch is held. Read-only. A private campaign, task or source shows ids, counts and states only, never its question, scope, path or excerpt. Give no id to list this project's campaigns, at most 50 per call: when the reply carries `next`, pass it as `after` for the following page.", { id: str, after: str }),
+  tool("hub_task_handoff", "Hand work that belongs to ANOTHER project that runs agent-hub to that project's board. Use it instead of implementing it from this session: a feature or behavior change first needs a spec issue in that project (pass its number as issue); a mechanical chore (an exact version pin, a regenerated file) goes straight to a task. The target is a registered project (its root or id) whose hub is running; it is not queued. Planner, conductor or person only. Never for a [pii] task or during a private turn. You learn the task's state changes as kind task messages.", { project: str, title: str, class: { type: "string", description: "task class, default implement" }, detail: str, paths: { type: "array", items: str, description: "repository-relative paths in the TARGET project" }, issue: { type: "integer", minimum: 1, description: "the target repository's issue number" }, task: { type: "integer", minimum: 1, description: "your own task in THIS project that this work comes from; a [pii] task is refused" } }, ["project", "title"]),
+  tool("hub_task_handoffs", "List what this project handed to other projects, with the last state each target reported. Read-only.", {}),
+  tool("hub_study_handoff", "Record the handoff for the research unit you currently own and have in progress: evidence per source, unresolved questions, contradictions and limitations, or insufficientEvidence. Only the bound owner; every required field must be present. Not a task completion.", { handoff: { type: "object" } }, ["handoff"]),
   tool("hub_release_new", "Create a future release planning row. Planner/person only; no activation, publish or release authorization.", { name: { type: "string", minLength: 1, maxLength: 64 }, goal: { type: "string", minLength: 1, maxLength: 1000 }, order: { type: "integer", minimum: 0 } }, ["name", "goal", "order"]),
   tool("hub_release_report", "Read a planned release's task readiness and recorded metrics. Planner/person only. A due date never waives unfinished scope.", { id }, ["id"]),
   tool("hub_release_assign", "Assign or move only a task's release, retaining its execution state and owner. Planner/person only; requires a reason and current planning revision. Frozen scope refuses.", { id, revision: { type: "integer", minimum: 0 }, release: { type: ["integer", "null"], minimum: 1 }, reason: { type: "string", minLength: 1, maxLength: 1000 } }, ["id", "revision", "release", "reason"]),
@@ -184,7 +194,7 @@ export function configuredToolContext(status: unknown, peer: string): ProjectToo
   return { startPeers, readOnly: readOnlyPeers.includes(peer) };
 }
 
-const READ_ONLY_PROJECT_TOOLS = Object.freeze(["hub_capabilities", "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_source_read", "hub_status"]);
+const READ_ONLY_PROJECT_TOOLS = Object.freeze(["hub_capabilities", "hub_send", "hub_inbox", "hub_delivery_done", "hub_review", "hub_task_show", "hub_task_list", "hub_study_show", "hub_memory_search", "hub_memory_show", "hub_memory_graph", "hub_source_read", "hub_status"]);
 /** Publication restricts exposure only; server-side authority remains mandatory for every call. */
 export function projectToolList<T extends { name: string }>(tools: T[], readOnly = false): T[] {
   return readOnly ? tools.filter(tool => READ_ONLY_PROJECT_TOOLS.includes(tool.name)) : tools;

package/src/hub/manager.ts

@@ -79,6 +79,69 @@ function removeManifest(home: string, instanceId: string) {
   rmSync(files(home).token, { force: true });
 }
 
+/** The manager's project listing and forwarding (#935): shared by `ahub ui --all` and the acon plugin, never widened for either. */
+export function projectConsole(options: { registry: Registry; lifecycle: Lifecycle; home: string; stopping?: () => boolean; forwardTimeoutMs?: ManagerOptions["forwardTimeoutMs"] }) {
+  const { registry, lifecycle, home } = options;
+  const aliases = new Map<string, { at: number; names: string[] }>();
+  const list = async () => {
+    const projects = registry.list();
+    for (const p of projects) if (!aliases.has(p.id) || Date.now() - aliases.get(p.id)!.at > 60_000) {
+      aliases.set(p.id, { at: Date.now(), names: existsSync(p.root) ? projectChain(p.root) : [] });
+    }
+    const rows = await Promise.all(projects.map(async (project) => {
+      let result: ProjectInspection;
+      try { result = await bounded(lifecycle.inspectProject(project), 7000); }
+      catch (error) { result = { state: "unavailable", error: safeError(error) }; }
+      const names = aliases.get(project.id)!.names;
+      const shared = projects.some((other) => other.id !== project.id && aliases.get(other.id)!.names.some((name) => names.includes(name)));
+      return { id: project.id, root: project.root, state: result.state,
+        instanceId: result.state === "running" ? result.status?.instanceId ?? null : null,
+        peers: result.status?.peers ?? {}, tasks: result.status?.tasks ?? {},
+        ...(shared ? { warning: "Native memory aliases are shared with another registered project." } : {}),
+        ...(result.error ? { error: result.error } : {}) };
+    }));
+    return { ok: true, mode: "all", projects: rows };
+  };
+  const act = async (input: Record<string, unknown>) => {
+    if (options.stopping?.()) return { ok: false, error: "manager is stopping" };
+    const project = typeof input.projectId === "string" ? registry.get(input.projectId) : undefined;
+    if (!project) return { ok: false, error: "unknown project" };
+    let client: ControlClient | undefined;
+    try {
+      if (input.action === "start") {
+        const status = await bounded(lifecycle.startProject(project, { unattended: false, env: { ...scrubEnv(process.env), AGENTHUB_HOME: home } }), 20_000);
+        return { ok: true, projectId: project.id, instanceId: status.instanceId };
+      }
+      if (typeof input.instanceId !== "string" || !input.instanceId) return { ok: false, error: "expected daemon instance is required" };
+      if (input.action === "stop") {
+        await bounded(lifecycle.stopProject(project, input.instanceId), 20_000);
+        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", "backlog_pull", "backlog_return", "planning", "planning_undo", "planner_pull", "backlog_split", "release_new", "release_change", "setting", "setting_undo", "setting_preview", "setting_reload", "config_edit_preview", "config_edit_apply", "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 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, ...(input.memory !== undefined ? { memory: input.memory } : {}), ...(dashboardView(input.view) ? { view: input.view } : {}) }
+        : { 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 (["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(); }
+  };
+  return { list, act };
+}
+
 export async function startManager(options: ManagerOptions = {}): Promise<ManagerHandle> {
   const home = options.home ?? hubHome();
   const existing = active.get(home);
@@ -119,63 +182,7 @@ export async function startManager(options: ManagerOptions = {}): Promise<Manage
   };
   try {
     owner = claimOwner(f.owner, instanceId, pidSignature);
-    const aliases = new Map<string, { at: number; names: string[] }>();
-    const list = async () => {
-      const projects = registry.list();
-      for (const p of projects) if (!aliases.has(p.id) || Date.now() - aliases.get(p.id)!.at > 60_000) {
-        aliases.set(p.id, { at: Date.now(), names: existsSync(p.root) ? projectChain(p.root) : [] });
-      }
-      const rows = await Promise.all(projects.map(async (project) => {
-        let result: ProjectInspection;
-        try { result = await bounded(lifecycle.inspectProject(project), 7000); }
-        catch (error) { result = { state: "unavailable", error: safeError(error) }; }
-        const names = aliases.get(project.id)!.names;
-        const shared = projects.some((other) => other.id !== project.id && aliases.get(other.id)!.names.some((name) => names.includes(name)));
-        return { id: project.id, root: project.root, state: result.state,
-          instanceId: result.state === "running" ? result.status?.instanceId ?? null : null,
-          peers: result.status?.peers ?? {}, tasks: result.status?.tasks ?? {},
-          ...(shared ? { warning: "Native memory aliases are shared with another registered project." } : {}),
-          ...(result.error ? { error: result.error } : {}) };
-      }));
-      return { ok: true, mode: "all", projects: rows };
-    };
-    const act = async (input: Record<string, unknown>) => {
-      if (stopping) return { ok: false, error: "manager is stopping" };
-      const project = typeof input.projectId === "string" ? registry.get(input.projectId) : undefined;
-      if (!project) return { ok: false, error: "unknown project" };
-      let client: ControlClient | undefined;
-      try {
-        if (input.action === "start") {
-          const status = await bounded(lifecycle.startProject(project, { unattended: false, env: { ...scrubEnv(process.env), AGENTHUB_HOME: home } }), 20_000);
-          return { ok: true, projectId: project.id, instanceId: status.instanceId };
-        }
-        if (typeof input.instanceId !== "string" || !input.instanceId) return { ok: false, error: "expected daemon instance is required" };
-        if (input.action === "stop") {
-          await bounded(lifecycle.stopProject(project, input.instanceId), 20_000);
-          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", "backlog_pull", "backlog_return", "planning", "planning_undo", "planner_pull", "backlog_split", "release_new", "release_change", "setting", "setting_undo", "setting_preview", "setting_reload", "config_edit_preview", "config_edit_apply", "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 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, ...(input.memory !== undefined ? { memory: input.memory } : {}), ...(dashboardView(input.view) ? { view: input.view } : {}) }
-          : { 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 (["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(); }
-    };
+    const { list, act } = projectConsole({ registry, lifecycle, home, stopping: () => stopping, forwardTimeoutMs: options.forwardTimeoutMs });
     dashboard = startDashboard({ projects: list, snapshot: (after, input = {}) => act({ ...input, action: "snapshot", after }), action: act });
     server = Bun.serve({ hostname: "127.0.0.1", port: 0, maxRequestBodySize: 1024,
       async fetch(req) {

package/src/hub/no-writes.ts

@@ -37,7 +37,7 @@ export class NoWriteTurns {
 }
 
 
-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"]);
+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", "hub_study_handoff"]);
 /** 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;

package/src/hub/path-policy.ts

@@ -32,7 +32,11 @@ 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)]; }))];
 }
-type DiscoveryBudget = { entries: number };
+type DiscoveryBudget = { entries: number; failClosedOnDiscoveryLimit?: boolean };
+function discoveryLimit(budget: DiscoveryBudget): false {
+  if (budget.failClosedOnDiscoveryLimit) throw new Error("policy alias discovery incomplete");
+  return false;
+}
 /** A dangling direct child names a future lexical target; an ELOOP child opens no file. */
 function directAliasTarget(path: string): string | undefined {
   let target = path;
@@ -55,16 +59,16 @@ function directAliasTarget(path: string): string | undefined {
   }
   return undefined;
 }
-/** Only a completed bounded scan contributes aliases; a truncated root contributes none. */
+/** Only completed bounded scans contribute aliases; opt-in strict callers treat an incomplete scan as protected. */
 function aliasScope(dir: string, lexical: string, actual: string, includeParents: boolean, budget: DiscoveryBudget): boolean {
   // Readability must not depend on reaching readSync after an exhausted-budget return.
   accessSync(dir, constants.R_OK);
   const handle = opendirSync(dir);
   let matched = false;
   try {
-    if (budget.entries >= 4096) return false;
+    if (budget.entries >= 4096) return discoveryLimit(budget);
     for (let entry = handle.readSync(); entry; entry = handle.readSync()) {
-      if (budget.entries >= 4096) return false;
+      if (budget.entries >= 4096) return discoveryLimit(budget);
       budget.entries++;
       if (!entry.isSymbolicLink()) continue;
       const target = directAliasTarget(join(dir, entry.name));
@@ -138,13 +142,13 @@ function globScope(root: string, lexical: string, actual: string, path: string,
     if (!lowerBeneath(real, root)) throw new Error("policy glob discovery outside project");
     const info = statSync(dir);
     if (!info.isDirectory()) return false;
-    if (aliasDiscovery && budget.entries >= 4096) return false;
+    if (aliasDiscovery && budget.entries >= 4096) return discoveryLimit(budget);
     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 (aliasDiscovery && budget.entries >= 4096) return false;
+        if (aliasDiscovery && budget.entries >= 4096) return discoveryLimit(budget);
         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;
@@ -163,13 +167,13 @@ export function matchesPolicyLexically(cwd: string, path: string, paths: string[
 }
 
 /** Compare declared spelling, real targets and bounded aliases; legacy discovery errors fail closed. */
-export function matchesPolicy(cwd: string, path: string, paths: string[], includeParents = false): boolean {
+export function matchesPolicy(cwd: string, path: string, paths: string[], includeParents = false, options: { failClosedOnDiscoveryLimit?: boolean } = {}): 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 }, roots = new Set<string>(), exact: string[] = [];
+    const budget: DiscoveryBudget = { entries: 0, failClosedOnDiscoveryLimit: options.failClosedOnDiscoveryLimit }, roots = new Set<string>(), exact: string[] = [];
     if (paths.some(entry => {
       if (/[?*]/.test(entry)) return globScope(root, lexical, actual, entry, includeParents, budget, roots);
       const targets = policyTargets(root, [entry]);

package/src/hub/project.ts

@@ -66,15 +66,24 @@ export function projectContext(cwd: string, env: NodeJS.ProcessEnv = process.env
   const root = projectRoot(cwd);
   const override = env.AGENTHUB_STATE_DIR?.trim();
   if (!override) return { root, stateDir: canonical(join(root, ".agenthub", "state")) };
+  const inherited = inheritedStateDir(root, env);
+  return { root, stateDir: inherited ?? canonical(join(root, ".agenthub", "state")) };
+}
 
+/**
+ * The ownership proof for an inherited state directory, on its own so the channel plugin applies the same rule as the CLI (#604 PR B, item 10). The directory is accepted only when the root
+ * recorded in it equals `root`, or when it records none (a freshly initialized state) and the inherited `AGENTHUB_PROJECT_DIR` names `root`. A marker for another project is authoritative:
+ * an inherited pair from the main checkout must not pull a process started in a linked worktree into the main repository's hub.
+ */
+export function inheritedStateDir(root: string, env: NodeJS.ProcessEnv = process.env): string | undefined {
+  const override = env.AGENTHUB_STATE_DIR?.trim();
+  if (!override) return undefined;
   const declared = env.AGENTHUB_PROJECT_DIR?.trim();
   const stateDir = canonical(override);
   const recorded = stateMarker(stateDir);
-  if (recorded === root) return { root, stateDir };
-  // A marker for another project is authoritative; an inherited mismatch must not
-  // redirect this cwd. The explicit pair is only for a freshly initialized state.
-  if (!recorded && declared && canonical(declared) === root) return { root, stateDir };
-  return { root, stateDir: canonical(join(root, ".agenthub", "state")) };
+  if (recorded === root) return stateDir;
+  if (!recorded && declared && canonical(declared) === root) return stateDir;
+  return undefined;
 }
 
 export function hubHome(env: NodeJS.ProcessEnv = process.env): string {

package/src/hub/provenance.ts

@@ -0,0 +1,30 @@
+// Sender provenance (#604 PR B, agent-hub#1030 item 11). Pure: a connection's identity fields in, a bounded record out. The record names the sending connection by role, bound peer
+// and launch or instance id, and nothing else: never a path, a cwd, a project root, a message body or a token. Two sessions that both claim `claude` stay distinguishable in
+// events.jsonl because their launch ids differ, and an envelope can be traced to the connection that sent it.
+/** `instanceId` is a declared extra instance's id when the connection is one. It is never the hub run's own id, which is the same for every connection and so distinguishes none. */
+export interface ConnectionIdentity { role?: "peer" | "console" | "tools"; peer?: string; launchId?: string; instanceId?: string; session?: boolean }
+/** `session: true` marks a distinct session: its `peer` is the daemon-minted `<peer>~<origin>` id (agent-hub#1036). */
+export type Origin = { role: "peer" | "console" | "tools" | "hub"; peer?: string; launch?: string; instance?: string; session?: true };
+
+/** An id the hub itself minted (a UUID or a short token). Anything else, or anything long, is dropped rather than copied: the field is evidence, not a channel for caller text. */
+const ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const idOf = (value: unknown): string | undefined => typeof value === "string" && ID.test(value) ? value : undefined;
+const PEER = /^[a-z][a-z0-9_~-]{0,63}$/;
+
+/** `undefined` identity is the hub's own writer (a task flow, a notice): it is `hub`, not a connection. */
+export function originOf(identity: ConnectionIdentity | undefined): Origin {
+  if (!identity?.role) return { role: "hub" };
+  const peer = typeof identity.peer === "string" && PEER.test(identity.peer) ? identity.peer : undefined;
+  const launch = idOf(identity.launchId), instance = idOf(identity.instanceId);
+  return { role: identity.role, ...(peer ? { peer } : {}), ...(launch ? { launch } : {}), ...(instance ? { instance } : {}), ...(identity.session === true && peer ? { session: true as const } : {}) };
+}
+
+/** The one `attach` event a peer or tools hello writes, and the shape an envelope event embeds as `origin`. */
+export function attachEvent(identity: ConnectionIdentity): { type: "attach" } & Origin {
+  return { type: "attach", ...originOf(identity) };
+}
+
+/** Whether two origins name the same connection identity: the same role, peer and launch. A connection with no launch id never equals one that has it. */
+export function sameOrigin(a: Origin, b: Origin): boolean {
+  return a.role === b.role && a.peer === b.peer && a.launch === b.launch && a.instance === b.instance && a.session === b.session;
+}