@staix/agent-hub 0.12.39 → 0.12.40

package/src/hub/events.ts

@@ -78,7 +78,7 @@ function cutShort(file: string): boolean {
 }
 
 /** An appender that never throws: the state dir can vanish under a running hub, and telemetry must not take it down. */
-export function eventLog(file: string, onFailure?: (e: HubEvent) => void): (e: HubEvent) => void {
+export function eventLog(file: string, onFailure?: (e: HubEvent) => void): (e: HubEvent) => boolean {
   let first = true;
   return (e) => {
     try {
@@ -86,9 +86,12 @@ export function eventLog(file: string, onFailure?: (e: HubEvent) => void): (e: H
       const lead = first && cutShort(file) ? "\n" : "";
       first = false;
       appendFileSync(file, `${lead}${JSON.stringify({ v: EVENTS_SCHEMA, at: new Date().toISOString(), ...e })}\n`);
+      return true;
     } catch {
+      first = true; // A failed append may have left a partial row; recheck its newline before the next event.
       try { onFailure?.(e); } catch { /* telemetry failure reporting is optional too */ }
       // the state dir is gone; the watchdog is stopping the hub
+      return false;
     }
   };
 }

package/src/hub/hub-tools.ts

@@ -13,7 +13,7 @@ const id = { type: "integer", description: "task id" } as const;
 const refs = {
   type: "object",
   description: "where the work lives",
-  properties: { branch: str, commit: str, paths: { type: "array", items: str } },
+  properties: { repo: { type: "string", description: "owner/name repository slug or checkout path; set for work in another repository" }, branch: str, commit: str, paths: { type: "array", items: str } },
   additionalProperties: false,
 } as const;
 const list = (description: string) => ({ type: "array", items: str, description }) as const;
@@ -68,10 +68,10 @@ export const TASK_TOOLS: HubTool[] = [
   tool("hub_release_cut", "Freeze an active release's approved scope after host resource admission and fresh peer quota checks. Unknown evidence defers; no publish, tag, upgrade or authorization.", { id, revision: { type: "integer", minimum: 0 } }, ["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_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, set refs.repo for work in another repository, 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. Set refs.repo for work in another repository; acceptance may correct only that repository metadata.", { id, plan: acceptPlan, refs: { ...refs, properties: { repo: refs.properties.repo } } }, ["id"]),
   tool("hub_task_cancel", "Cancel unaccepted proposed/backlog work you proposed as its configured planner; accepted work is person-only. Keeps history and does not stop a native turn or delete files.", { id, reason: str, superseded_by: str, revision: { type: "integer", minimum: 0 } }, ["id", "reason"]),
-  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_decline", "Pass on a task assigned to you; the hub offers it to the next peer. A plain decline is a lasting refusal: you are never offered this task again. Pass capacity: true when you only have no room right now: you are skipped for this move only, and a later reroute or planner pull may offer it to you again.", { id, reason: str, capacity: { type: "boolean" } }, ["id"]),
   tool("hub_task_done", "Mark your task finished. It goes to its reviewer with your summary and refs; no duplicate hub_send chat is needed. When the project configures a check for its class, the hub runs it first and the result comes as a task message: a failed check keeps the task with you.", { id, summary: { type: "string", description: "what changed, why, and the check you ran with its result" }, refs }, ["id", "summary"]),
   tool("hub_sdlc_record", "Record artifact ids or claimed local checks on your task. This grants no authority or external-check evidence. Only its owner/reviewer or the person may record; only its reviewer/person may name a reviewed head or phase checklist. Phase evidence refs are content hashes, not external verification.", { id, receipt: { type: "object", properties: { stage: { type: "string", enum: ["spec", "plan", "implement", "review", "verify", "merge", "release"] }, repo: str, issue: id, pr: id, localHead: str, localResult: { type: "string", enum: ["passed", "failed", "unknown"] }, reviewedHead: str, phase: { type: "object", properties: { id: str, head: str, tasks: { type: "array", maxItems: 64, items: { type: "object", properties: { id, after: { type: "array", maxItems: 16, items: id } }, required: ["id", "after"], additionalProperties: false } }, criteria: { type: "array", maxItems: 32, items: { type: "object", properties: { id: str, required: { type: "boolean" }, result: { type: "string", enum: ["verified", "failed", "unverified"] }, refs: { type: "array", maxItems: 8, items: str } }, required: ["id", "required", "result", "refs"], additionalProperties: false } } }, required: ["id", "tasks", "criteria"], additionalProperties: false } }, additionalProperties: false } }, ["id", "receipt"]),
   tool("hub_task_list", "The task board. PII tasks show as [pii].", { state: { type: "string", enum: ["proposed", "in_progress", "in_review", "approved", "changes_requested", "cancelled"] }, ready: { type: "boolean", description: "only proposed tasks with nothing left to wait for" } }),

package/src/hub/inference.ts

@@ -1,6 +1,5 @@
 import type { MlxHandle } from "../models/mlx.ts";
 import type { ChatMessage, OmniRoute } from "../omniroute/client.ts";
-import type { Sidecar } from "../switchyard/sidecar.ts";
 import { CLASSES, type TaskClass } from "./board.ts";
 import { DIGEST, newEnvelope, type Envelope } from "./envelope.ts";
 import { buildEscalationJudgeRequest, parseEscalationVerdict, type EscalationVerdict } from "../models/route/escalation.ts";
@@ -25,15 +24,13 @@ const SUMMARY_CAP = 1500;
 
 export interface InferenceDeps {
   omni: OmniRoute;
-  sidecar: () => Sidecar | undefined;
-  route: string;
   fixedModel: () => string;
   log: (line: string) => void;
   timeoutMs?: number;
 }
 
 /**
- * The hub's own small model calls (route `sy/fast`, the usual fallback to a fixed model). Everything here is optional
+ * The hub's own small fixed-model calls. Everything here is optional
  * and fail-open: no gateway, a slow model or a useless answer means "no result", never a delayed or lost delivery.
  * The model reads text written by agents, so its input is data and its output is only ever used as capped text or as
  * a value checked against a closed list: never as a route, a peer id, a tool call or an instruction.
@@ -56,7 +53,7 @@ export class Inference {
     const limit = opts.timeoutMs ?? this.d.timeoutMs ?? TIMEOUT_MS;
     const quiet = !!opts.interactive;
     let timer: ReturnType<typeof setTimeout> | undefined;
-    // One clock over everything, the gateway probe and the sidecar start included, not only the model call.
+    // One clock over everything, the gateway probe included, not only the model call.
     const timeout = new Promise<"timeout">((resolve) => (timer = setTimeout(() => (abort.abort(), resolve("timeout")), limit)));
     const result = await Promise.race([this.run(system, user, maxTokens, abort.signal, quiet), timeout]);
     clearTimeout(timer);
@@ -77,9 +74,8 @@ export class Inference {
       // probe every time, so both back off.
       if (!(await this.d.omni.base())) return this.backOff("no gateway configured or reachable", quiet);
       const messages = [{ role: "system" as const, content: system }, { role: "user" as const, content: user }];
-      const via = await this.d.sidecar()?.endpoint();
-      const body = via ? { model: this.d.route, messages, max_tokens: maxTokens } : { model: this.d.fixedModel(), messages, max_tokens: maxTokens };
-      const res = await this.d.omni.chat(body, { signal, ...(via ? { via } : {}) });
+      const body = { model: this.d.fixedModel(), messages, max_tokens: maxTokens };
+      const res = await this.d.omni.chat(body, { signal });
       return res.message.content?.trim() || undefined;
     } catch (e) {
       return signal.aborted ? undefined : this.backOff((e as Error).message, quiet);

package/src/hub/lifecycle.ts

@@ -8,7 +8,7 @@ import { ControlClient, PROTOCOL, readControl } from "./control-client.ts";
 import { startDaemon } from "./daemon.ts";
 import { terminalOpener } from "./terminal-open.ts";
 import { Registry, type Project } from "./registry.ts";
-import { CODEX_APP, CODEX_PROXY, CONTROL, SWITCHYARD } from "./ports.ts";
+import { CODEX_APP, CODEX_PROXY, CONTROL } from "./ports.ts";
 import { assertLifecycleAvailable, recoveryLock } from "./recovery-store.ts";
 import { processLiveness, processSignature } from "../pi/process-signature.ts";
 
@@ -64,7 +64,7 @@ export async function inspectProject(project: Project, timeoutMs = 3000): Promis
 async function available(base: number): Promise<boolean> {
   const servers: Server[] = [];
   try {
-    for (const offset of [CONTROL, CODEX_APP, CODEX_PROXY, SWITCHYARD]) {
+    for (const offset of [CONTROL, CODEX_APP, CODEX_PROXY]) {
       const server = createServer();
       servers.push(server);
       await new Promise<void>((resolve, reject) => {
@@ -116,7 +116,7 @@ export async function runProjectDaemon(project: Project, unattended = false): Pr
         try {
           daemon = await startDaemon({ cwd: project.root, stateDir: project.stateDir, projectId: project.id, instanceId,
             controlPort: base + CONTROL, codexAppPort: base + CODEX_APP, codexProxyPort: base + CODEX_PROXY,
-            switchyardPort: base + SWITCHYARD, unattended, onShutdownStart,
+            unattended, onShutdownStart,
             // #269: the real terminal providers belong to the running product; a daemon built without them opens nothing.
             terminal: (template) => terminalOpener({ template, cwd: project.root, stateDir: project.stateDir }) });
           break;

package/src/hub/main-checkout.ts

@@ -0,0 +1,36 @@
+import { childEnv } from "./child-process.ts";
+import { hubGitSync } from "./git.ts";
+
+/**
+ * #572 AC3: the project root is the shared checkout every session reads. A task branch left checked out there changes
+ * what each other session sees, so a finished task says so. Advisory only: it is a line of text, never a refusal.
+ * Only git is read, bounded: HEAD's branch, and the default branch from `origin/HEAD`, falling back to `main`.
+ * A detached head, a missing directory, a directory that is not a repository and any git failure say nothing.
+ */
+const git = (cwd: string, args: string[]) => hubGitSync(["-C", cwd, ...args], { encoding: "utf8", env: childEnv(process.env), maxBuffer: 64 * 1024, timeout: 3000 });
+
+export function mainCheckoutBranch(cwd: string): { branch: string; defaultBranch: string } | undefined {
+  try {
+    const head = git(cwd, ["symbolic-ref", "--quiet", "--short", "HEAD"]);
+    if (head.status !== 0 || typeof head.stdout !== "string" || !head.stdout.trim()) return undefined;
+    const branch = head.stdout.trim();
+    const origin = git(cwd, ["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"]);
+    const named = origin.status === 0 && typeof origin.stdout === "string" ? origin.stdout.trim().replace(/^origin\//, "") : "";
+    const defaultBranch = named || "main";
+    return branch === defaultBranch ? undefined : { branch, defaultBranch };
+  } catch { return undefined; }
+}
+
+/**
+ * The one advisory sentence, or undefined while the checkout is on its default branch.
+ * A branch name is text a person or an agent chose, so it is not safe because git printed it: `nameable` is the hub's
+ * whole public-text screen (`Tasks.publicMetadataText`: the configured PII patterns, secret shapes and private paths). A name it refuses, or any text
+ * that is not a plain ref name, is replaced by a generic sentence that carries no part of it (#572 review I2).
+ */
+export function mainCheckoutWarning(cwd: string, nameable: (text: string) => boolean = () => false): string | undefined {
+  const found = mainCheckoutBranch(cwd);
+  if (!found) return undefined;
+  const plain = /^[A-Za-z0-9][A-Za-z0-9._\/-]{0,99}$/.test(found.branch) && nameable(found.branch);
+  return plain ? `the main checkout is on \`${found.branch}\`; move the work to a worktree under .worktrees/`
+    : "the main checkout is on a branch other than its default (its name is withheld); move the work to a worktree under .worktrees/";
+}

package/src/hub/memory-profile-check.ts

@@ -5,7 +5,7 @@ import { ControlClient, readControl, type ControlDescriptor } from "./control-cl
 import { canonicalPath, hubHome, realPath } from "./project.ts";
 import { processLiveness, type Liveness } from "../pi/process-signature.ts";
 import type { Project } from "./registry.ts";
-import type { UnboundMemoryProfileReceipt } from "./memory-profile.ts";
+import { MEMORY_SPLIT_INCOMPLETE, shardProfileForProject, type UnboundMemoryProfileReceipt } from "./memory-profile.ts";
 
 export interface ExpectedMemoryProfile {
   home: string;
@@ -94,7 +94,11 @@ export function evaluateMemoryProfileCheck(expected: ExpectedMemoryProfile, evid
       result.ready = true; result.quiesced = true; result.reason = `memory handle ${bound.state}; quiesced`; daemons.push(result); continue;
     }
     if (bound.state !== "ready") { reject("running memory binding is not ready"); continue; }
-    if (bound.profile !== expected.profile || bound.generation !== expected.generation || bound.selectorRevision !== expected.selectorRevision) { reject("running memory binding differs from the selected profile"); continue; }
+    // #536: on a split home each hub is bound to its own project's shard, so compare like with like.
+    let want: ExpectedMemoryProfile = expected;
+    try { want = shardProfileForProject(expected.home, project.root) ?? expected; }
+    catch (e) { reject((e as Error).message === MEMORY_SPLIT_INCOMPLETE ? MEMORY_SPLIT_INCOMPLETE : "running memory binding differs from the selected profile"); continue; }
+    if (bound.profile !== want.profile || bound.generation !== want.generation || bound.selectorRevision !== want.selectorRevision) { reject("running memory binding differs from the selected profile"); continue; }
     result.ready = true; daemons.push(result);
   }
   const relevant = daemons.filter(row => row.scope !== "different-home");

package/src/hub/memory-profile.ts

@@ -120,7 +120,24 @@ export function memoryProjectFor(cwd: string, opts: Pick<StoreOptions, "home"> =
 /** Inspect selection without constructing a store, index, or candidate sidecar. */
 export function selectedMemoryProfile(opts: StoreOptions = {}): MemoryProfileReceipt {
   assertLoadedAgentMem();
-  return receipt(resolveProfile(homeFor(opts)), "ready");
+  const home = homeFor(opts);
+  if (!splitMarked(home)) return receipt(resolveProfile(home), "ready");
+  // #536: a split home selects through shards.json, not the legacy selector. The user shard is sealed by every split,
+  // so it names the active generation and selector revision without opening a store; an inactive split throws the resume remedy.
+  assertActiveSplit(home);
+  return receipt(resolveShardProfile(home, { user: true }), "ready");
+}
+
+/**
+ * #536: the shard profile a hub bound to `projectRoot` reports on an active split home, without opening a store.
+ * Returns undefined on an unsplit home; throws MEMORY_SPLIT_INCOMPLETE on an inactive split, and whatever the
+ * shard resolution throws when this project's seal is missing or corrupt.
+ */
+export function shardProfileForProject(canonicalMemoryHome: string, projectRoot: string): MemoryProfileReceipt | undefined {
+  assertLoadedAgentMem();
+  if (!splitMarked(canonicalMemoryHome)) return undefined;
+  assertActiveSplit(canonicalMemoryHome);
+  return receipt(resolveShardProfile(canonicalMemoryHome, { project: resolveAlias(canonicalMemoryHome, memoryProjectKey(projectRoot)) }), "ready");
 }
 
 export class MemoryProfileBinding {

package/src/hub/peers.ts

@@ -31,6 +31,8 @@ export interface PeerAdapter {
   onDelivery?: (receipt: DeliveryReceipt) => void;
   /** Safe restart metadata only: ids and launch parameters, never prompt/message text. */
   recoveryMetadata?(): Record<string, unknown>;
+  /** Current native TUI ownership, correlated to one launcher. A start acknowledgement is never evidence. */
+  terminalOwner?(launchId: string): { generation: string; nativePid?: number } | undefined;
 }
 
 export const DEFAULT_WATCHDOG_MS = 300_000;

package/src/hub/ports.ts

@@ -9,6 +9,7 @@ export const STRIDE = 10;
 export const CONTROL = 0;
 export const CODEX_APP = 1;
 export const CODEX_PROXY = 2;
+/** Reserved after sidecar retirement (#553); never bind this offset or move later allocations. */
 export const SWITCHYARD = 3;
 
 /** SQLite-backed project allocation; an explicit JSON path retains the legacy utility API under a lock. */

package/src/hub/routing.ts

@@ -11,12 +11,10 @@ import type { PeerId, PeerState } from "./envelope.ts";
 import { parseHubRoutes, type HubRoute } from "../models/route/config.ts";
 import { DEFAULT_STAY_SWITCH, type StaySwitchMode } from "../models/route/stage.ts";
 
-type Table = Record<string, unknown>;
-
 export interface ClassPolicy {
   /** preference order among attached, unpaused peers */
   peers: PeerId[];
-  /** Switchyard route the local worker asks for on a task of this class */
+  /** In-process hub route, or a retired non-hub selection that uses fixed_model. */
   route?: string;
   fixed_model?: string;
   /** on `tasks.escalate_after` consecutive changes_requested (default 3) */
@@ -29,8 +27,8 @@ export interface ClassPolicy {
 
 export interface Routing {
   local: { route?: string; fixed_model: string };
-  targets: Record<string, Table & { id: string }>;
-  routes: Record<string, Table & { type: string }>;
+  /** Loader-owned diagnostics for ignored legacy routing tables. */
+  retired?: string[];
   hub_routes?: Record<string, HubRoute>;
   /** Session-aware stay/switch for `hub/auto` and hub stage routes (#197). */
   stay_switch: StaySwitchMode;
@@ -45,9 +43,14 @@ export interface Routing {
   sources?: Record<string, "routing.local.toml">;
 }
 
+/** A class fixed_model without its own route explicitly selects the gateway alias directly. */
+export function effectiveLocalRoute(defaultRoute: string | undefined, classRoute?: string, classFixedModel?: string): string | undefined {
+  return classRoute ?? (classFixedModel === undefined ? defaultRoute : undefined);
+}
+
 /**
  * What `.agenthub/routing.local.toml` may hold (#269): a person's machine-local override of these keys and nothing
- * else, so a settings write can never reach targets, routes, signals or the PII constraint.
+ * else, so a settings write can never reach hub routes, signals or the PII constraint.
  */
 export interface RoutingOverlay {
   stay_switch?: StaySwitchMode;
@@ -186,25 +189,33 @@ export function routingText(cwd: string): string {
 
 /** The policy of a routing.toml text with an overlay merged over it: what `loadRouting` reads, without the disk. */
 export function parseRouting(text: string, overlay?: RoutingOverlay): Routing {
-  const raw = Bun.TOML.parse(text) as Partial<Routing>;
+  const raw = Bun.TOML.parse(text) as Partial<Routing> & { targets?: unknown; routes?: unknown };
+  const retired: string[] = [];
+  if (Object.hasOwn(raw, "targets")) retired.push('[targets] is retired and ignored: name gateway aliases directly in hub_routes efficient/capable/judge or fixed_model');
+  if (Object.hasOwn(raw, "routes")) retired.push('[routes] is retired and ignored: replace stage_router with hub_routes type="stage" (efficient_target -> efficient, capable_target -> capable, same confidence_threshold), passthrough with fixed_model and no route, and llm_classifier escalation with hub_routes type="escalation"');
+  delete raw.targets;
+  delete raw.routes;
   const sources: NonNullable<Routing["sources"]> = {};
   if (overlay) {
     const checked = checkOverlay(overlay);
     if (checked.stay_switch) { (raw as Record<string, unknown>).stay_switch = checked.stay_switch; sources.stay_switch = OVERLAY_FILE; }
-    const known = new Set([...Object.keys(raw.routes ?? {}), ...Object.keys(raw.hub_routes ?? {})]);
+    const known = new Set(Object.keys(raw.hub_routes ?? {}));
     for (const [name, entry] of Object.entries(checked.classes ?? {})) {
-      if (entry.route && !known.has(entry.route)) throw new Error(`${OVERLAY_FILE}: [classes.${name}] route ${entry.route} names no route in routing.toml`);
+      if (entry.route && entry.route.startsWith("hub/") && !known.has(entry.route)) throw new Error(`${OVERLAY_FILE}: [classes.${name}] route ${entry.route} names no route in routing.toml`);
       const classes = (raw.classes ??= {}) as Record<string, ClassPolicy>;
       // A class the shared file does not have starts from an empty peer list: the overlay may add its own.
       classes[name] = { ...(classes[name] ?? { peers: [] }), ...entry };
       for (const field of Object.keys(entry)) sources[`classes.${name}.${field}`] = OVERLAY_FILE;
     }
   }
-  if (!raw.local?.fixed_model) throw new Error("routing.toml: [local] fixed_model is required (the path that works without Switchyard)");
+  if (!raw.local?.fixed_model) throw new Error("routing.toml: [local] fixed_model is required (the direct gateway fallback)");
   const signals = { pii_patterns: [], long_context_tokens: 120_000, pii_screen: "off" as const, ...raw.signals };
   for (const p of signals.pii_patterns) new RegExp(p); // a bad pattern fails here, at load, not in the middle of an assignment
   if (signals.pii_screen !== "off" && signals.pii_screen !== "local") throw new Error('routing.toml: [signals] pii_screen must be "off" or "local"');
   const classes = raw.classes ?? {};
+  if ([raw.local.route, ...Object.values(classes).map(policy => policy?.route)].some(route => route && !route.startsWith("hub/"))) {
+    retired.push('non-hub route selections are retired and ignored; using fixed_model (replace the selection with a hub/ route to enable in-process routing)');
+  }
   for (const [name, policy] of Object.entries(classes)) {
     if (policy?.pi_backend !== undefined && policy.pi_backend !== "dgx" && policy.pi_backend !== "mlx") throw new Error(`routing.toml: [classes.${name}] pi_backend must be "dgx" or "mlx"`);
   }
@@ -222,8 +233,7 @@ export function parseRouting(text: string, overlay?: RoutingOverlay): Routing {
   if (!(Number.isSafeInteger(max_switch_prefill_tokens) && max_switch_prefill_tokens > 0)) throw new Error("routing.toml: max_switch_prefill_tokens must be a positive integer");
   return {
     local: raw.local,
-    targets: raw.targets ?? {},
-    routes: raw.routes ?? {},
+    ...(retired.length ? { retired } : {}),
     hub_routes: parseHubRoutes(raw.hub_routes),
     stay_switch,
     max_switch_prefill_tokens,
@@ -298,7 +308,7 @@ export interface Assignment {
   refusals?: RoutingRefusal[];
   owner?: PeerId;
   reviewer?: PeerId;
-  /** what `local` should ask for on this task: a Switchyard route id and the model to fall back to */
+  /** What local should ask for on this task: a hub route or retired non-hub selection, with its fixed fallback. */
   route?: string;
   fixedModel?: string;
   piBackend?: "dgx" | "mlx";
@@ -542,7 +552,7 @@ export function assign(
       if (reviewerHold) trace.push(`  hold: ${reviewer}'s queue is held: ${reviewerHold} (it receives the review once the hold is resolved)`);
     }
   }
-  const route = policy?.route ?? routing.local.route;
+  const route = effectiveLocalRoute(routing.local.route, policy?.route, policy?.fixed_model);
   const fixedModel = policy?.fixed_model ?? routing.local.fixed_model;
   const piBackend = policy?.pi_backend;
   if (owner && definitionOf(owner, opts.instances)?.routing?.trace === "route") trace.push(`route: ${route ?? "(none)"}, fixed_model ${fixedModel}`);

package/src/hub/settings.ts

@@ -430,7 +430,7 @@ export function settingRows(input: {
   const raw = (name: string): unknown => { try { return JSON.parse(readFileSync(join(input.cwd, ".agenthub", name), "utf8")); } catch { return undefined; } };
   const local = raw(CONFIG_LOCAL), shared = raw("config.json");
   const projectRouting = existsSync(join(input.cwd, ".agenthub", "routing.toml"));
-  const routes = [...Object.keys(input.routing.routes), ...Object.keys(input.routing.hub_routes ?? {})];
+  const routes = Object.keys(input.routing.hub_routes ?? {});
   const scalar = (value: unknown): SettingValue => typeof value === "string" || typeof value === "boolean" || typeof value === "number" ? value : Array.isArray(value) ? value.map(String) : null;
   return projectSettings(input.instances).map((def): SettingRow => {
     const base = { key: def.key, group: def.group, label: def.label, type: def.type, ...(["integer", "number"].includes(def.type) ? { min: def.min, max: def.max } : {}), applies: def.applies, ...(def.restartReason ? { restartReason: def.restartReason } : {}), risk: def.risk, ...(def.floor === undefined ? {} : { floor: def.floor }),

package/src/hub/task-repository.ts

@@ -0,0 +1,136 @@
+import { statSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import type { TaskPlan, TaskRefs } from "./board.ts";
+import { hubGitSync } from "./git.ts";
+import { canonicalPath, realPath } from "./project.ts";
+import { isGitHubRepository } from "./spec-read.ts";
+
+export interface TaskRepository { key: string; root?: string; aliases: string[]; }
+const GIT_TIMEOUT_MS = 1000, GIT_MAX_BYTES = 16 * 1024, MAX_ANCESTORS = 64;
+const beneath = (root: string, path: string) => { const rel = relative(root, path); return !rel || rel !== ".." && !rel.startsWith("../") && !isAbsolute(rel); };
+const canonical = (path: string) => { try { return realPath(path); } catch { try { return canonicalPath(path); } catch { return resolve(path); } } };
+function slug(value: string): string | undefined {
+  const raw = value.trim().replace(/\/+$/, "").replace(/\.git$/i, "");
+  if (isGitHubRepository(raw)) return raw.toLowerCase();
+  const scp = /^(?:[^/@:]+@)?github\.com:(.+)$/i.exec(raw);
+  if (scp && isGitHubRepository(scp[1])) return scp[1].toLowerCase();
+  try {
+    const url = new URL(raw);
+    if (url.hostname.toLowerCase() !== "github.com" || !["https:", "http:", "ssh:"].includes(url.protocol) || url.port && !(url.protocol === "ssh:" && url.port === "22")) return undefined;
+    const name = url.pathname.replace(/^\//, "");
+    return isGitHubRepository(name) ? name.toLowerCase() : undefined;
+  } catch { return undefined; }
+}
+
+/** Repository metadata is advisory, never an execution root or a grant. Git reads are bounded, local and cached. */
+export class TaskRepositories {
+  readonly project: TaskRepository;
+  private readonly scopes = new Map<string, TaskRepository>();
+  private readonly directories = new Map<string, TaskRepository>();
+  private readonly roots = new Map<string, TaskRepository>();
+  private readonly paths = new Map<string, string>();
+  private projectNamed: boolean;
+  constructor(private readonly cwd: string, repository?: string) {
+    const root = canonical(cwd), named = repository && slug(repository);
+    this.projectNamed = !!named;
+    this.project = { key: named ? `repo:${named}` : `path:${root}`, root, aliases: [...new Set([resolve(cwd), root])] };
+    this.roots.set(root, this.project);
+  }
+  private git(dir: string, args: string[]): string | undefined {
+    try {
+      const found = hubGitSync(["-C", dir, ...args], { encoding: "utf8", timeout: GIT_TIMEOUT_MS, maxBuffer: GIT_MAX_BYTES });
+      return found.status === 0 && typeof found.stdout === "string" && found.stdout.trim() ? found.stdout.trim() : undefined;
+    } catch { return undefined; } // Unknown identity keeps a path key; never log remote URLs or stderr.
+  }
+  private directory(path: string): string {
+    let cursor = resolve(path);
+    for (let count = 0; count < MAX_ANCESTORS; count++) {
+      try { if (statSync(cursor).isDirectory()) return canonical(cursor); } catch { /* Try the next ancestor, never scan a directory. */ }
+      const parent = dirname(cursor); if (parent === cursor) break; cursor = parent;
+    }
+    return canonical(dirname(path));
+  }
+  private at(path: string): TaskRepository {
+    const directory = this.directory(path), cached = this.directories.get(directory);
+    if (cached) return cached;
+    const top = this.git(directory, ["rev-parse", "--show-toplevel"]);
+    const root = top ? canonical(top) : directory;
+    let scope = this.roots.get(root);
+    if (!scope) {
+      const remote = top && this.git(root, ["config", "--get", "remote.origin.url"]);
+      const named = remote && slug(remote);
+      scope = { key: named ? `repo:${named}` : `path:${root}`, root, aliases: [root] };
+      this.roots.set(root, scope);
+    }
+    this.directories.set(directory, scope);
+    return scope;
+  }
+  private common(paths: string[]): TaskRepository {
+    let root = this.directory(paths[0]!);
+    for (const path of paths.slice(1)) {
+      const dir = this.directory(path);
+      while (!beneath(root, dir)) { const parent = dirname(root); if (parent === root) break; root = parent; }
+    }
+    return this.roots.get(root) ?? { key: `path:${root}`, root, aliases: [root] };
+  }
+  /** Resolve only once per refs identity. Default project-only tasks never invoke Git. Negative probes are cached too. */
+  scope(refs: TaskRefs): TaskRepository {
+    const absolute = (refs.paths ?? []).filter(isAbsolute);
+    const fingerprint = JSON.stringify([refs.repo ?? null, absolute]);
+    const prior = this.scopes.get(fingerprint); if (prior) return prior;
+    const outside = absolute.length > 0 && absolute.every(path => !beneath(this.project.root!, canonical(path)));
+    let scope = this.project;
+    if (refs.repo) {
+      const named = slug(refs.repo);
+      if (named) {
+        // A retained project may not have a host-supplied slug. Probe only when an explicit slug needs that alias.
+        if (!this.projectNamed) {
+          const remote = this.git(this.project.root!, ["config", "--get", "remote.origin.url"]);
+          const projectSlug = remote && slug(remote);
+          if (projectSlug) this.project.key = `repo:${projectSlug}`;
+          this.projectNamed = true;
+        }
+        const key = `repo:${named}`;
+        for (const path of absolute) this.at(path);
+        const matching = [...this.roots.values()].filter(repo => repo.key === key);
+        scope = matching.length ? { key, root: matching[0]!.root, aliases: [...new Set(matching.flatMap(repo => repo.aliases))] } : { key, aliases: [] };
+      } else scope = this.at(resolve(this.cwd, refs.repo));
+    } else if (outside) {
+      const found = absolute.map(path => this.at(path));
+      scope = found.every(repo => repo.key === found[0]!.key)
+        ? { key: found[0]!.key, root: found[0]!.root, aliases: [...new Set(found.flatMap(repo => repo.aliases))] }
+        : this.common(absolute);
+    }
+    this.scopes.set(fingerprint, scope);
+    return scope;
+  }
+  /** External absolute spellings are normalized once, not by probing files on every overlap read. */
+  relativePath(scope: TaskRepository, path: string): string {
+    if (!isAbsolute(path)) return path;
+    const initialKey = JSON.stringify([scope.root, scope.aliases, path]);
+    const prior = this.paths.get(initialKey); if (prior !== undefined) return prior;
+    // Absolute plan evidence may be the first local checkout known for an explicit slug.
+    if (!scope.root || !scope.aliases.some(alias => beneath(alias, path))) {
+      const actual = this.at(path);
+      if (actual.key === scope.key) {
+        scope.root ??= actual.root;
+        scope.aliases = [...new Set([...scope.aliases, ...actual.aliases])];
+      }
+    }
+    if (!scope.root) { this.paths.set(initialKey, path); return path; }
+    const key = JSON.stringify([scope.root, scope.aliases, path]), cached = this.paths.get(key); if (cached !== undefined) return cached;
+    const physical = canonical(path);
+    const root = scope.aliases.find(alias => beneath(alias, path)) ?? (beneath(scope.root, physical) ? scope.root : undefined);
+    const value = root ? relative(root, beneath(root, path) ? path : physical) || "." : path;
+    this.paths.set(key, value);
+    this.paths.set(initialKey, value);
+    return value;
+  }
+  mismatch(refs: TaskRefs, plan?: TaskPlan): boolean {
+    const scope = this.scope(refs);
+    return [...(refs.paths ?? []), ...(plan?.paths ?? [])].filter(isAbsolute).some(path => {
+      const actual = beneath(this.project.root!, canonical(path)) ? this.project : this.at(path);
+      return actual.key !== scope.key;
+    });
+  }
+}