@staix/agent-hub 0.13.0 → 0.15.0

package/src/hub/peers.ts

@@ -9,8 +9,15 @@ export interface DeliveryReceipt {
   quota?: true;
 }
 
+/** Host-owned print child authority, revoked before stop/turn settlement. No terminal ownership. */
+export interface OwnedToolsLaunch {
+  launchId: string; generation: string; sessionId: string; signal: AbortSignal; task?: number; permissionHook: true;
+}
+
 export interface PeerAdapter {
   readonly id: PeerId;
+  ownedTools?(launchId: unknown): OwnedToolsLaunch | undefined;
+  keepApprovalAlive?(): void;
   readonly state: PeerState;
   /** Host-observed native session identity. An absent port permits owner-token fallback; undefined means unknown. */
   readonly sessionGeneration?: string | number;

package/src/hub/permission-payload.ts

@@ -0,0 +1,15 @@
+import { sanitize } from "./envelope.ts";
+
+/** Public approval rendering, never the arguments eventually executed by the native child.
+ * Withhold the complete value if any private/secret/path policy matches, before truncation. */
+export function permissionPayload(tool: unknown, input: unknown, publicText: (text: string) => boolean): { tool: string; title: string } {
+  const name = typeof tool === "string" && /^[A-Za-z][A-Za-z0-9_.:/-]{0,127}$/.test(tool) && publicText(tool) ? tool : "[withheld]";
+  let rendered = "[withheld]";
+  try {
+    const text = JSON.stringify(input);
+    if (typeof text === "string" && Buffer.byteLength(text) <= 64 * 1024 && publicText(text)) rendered = sanitize(text);
+  } catch { /* Unknown or unserializable arguments are never partially shown. */ }
+  const full = Array.from(`${name} ${rendered}`);
+  const marker = ` [cut, ${full.length} chars]`;
+  return { tool: name, title: full.length > 600 ? full.slice(0, 600 - marker.length).join("") + marker : full.join("") };
+}

package/src/hub/routing.ts

@@ -309,6 +309,9 @@ export interface Assignment {
   refusals?: RoutingRefusal[];
   owner?: PeerId;
   reviewer?: PeerId;
+  /** #525-3: the task's planner, from the planner walk. Read-only information until 525-2 records it; absent for a PII task or when nobody holds the role. */
+  planner?: PeerId;
+  plannerReason?: PlannerReason;
   /** What local should ask for on this task: a hub route or retired non-hub selection, with its fixed fallback. */
   route?: string;
   fixedModel?: string;
@@ -318,6 +321,79 @@ export interface Assignment {
   trace: string[];
 }
 
+/**
+ * The role a class's owner works in (#735): `plan` is the planner's, `review` the reviewer's, and every other class (implement, bulk_edit,
+ * test, summarize, triage, and a profile class that maps onto one) is done by an implementer, which needs write access. Derived, never a
+ * list of the write classes, so a class added later is a write class unless it says otherwise here.
+ */
+export function ownerRoleOfClass(cls: TaskClass): "planner" | "implementer" | "reviewer" {
+  return cls === "review" ? "reviewer" : cls === "plan" ? "planner" : "implementer";
+}
+
+/** Why a planner was chosen: the person named it, rotation reached it, the task's recorded planner is kept, or there is none (PII, no holder). */
+export type PlannerReason = "rotation" | "named" | "kept" | "none";
+
+/**
+ * I-2 (#525-3): the peers that implemented a task, read from its own history: any peer with an `accepted` or `done` entry. A reviewer is
+ * never one of them, so a multi-role holder (implementer and reviewer) never reviews a change it made, even after the task changed hands.
+ * Pure: history in, set out. A `done` by the person is not a peer's implementation and is left out.
+ */
+export function implementers(history: readonly { by: PeerId; event: string }[] | undefined): Set<PeerId> {
+  return new Set((history ?? []).filter(entry => (entry.event === "accepted" || entry.event === "done") && entry.by !== "user").map(entry => entry.by));
+}
+
+export interface PlannerWalkInput {
+  /** The settled planner holders, sorted by id. The walk sorts again, so an unsorted input cannot change the result. */
+  planners: readonly PeerId[];
+  /** The rotation seed: the task id. */
+  seed: number;
+  /** A person-named planner: exact, never replaced by rotation. */
+  named?: PeerId;
+  /** The planner already recorded on the task: kept while it is still a holder. */
+  kept?: PeerId;
+  /** Why a holder cannot take planning right now; undefined when it can. */
+  blocked(peer: PeerId): string | undefined;
+  /** A PII task has no planner: its planning stays with the person. */
+  pii: boolean;
+}
+export interface PlannerWalk { planner?: PeerId; reason: PlannerReason; walk: { peer: PeerId; note: string }[]; line: string }
+
+/**
+ * The planner walk (#525 R3, "Choice"): pure, so assignment and `ahub route explain` print the same lines.
+ * - a PII task has no planner;
+ * - a named planner is exact: a name that is not a holder or cannot plan is refused in the trace, never replaced by rotation;
+ * - otherwise the recorded planner is kept while it is still a holder;
+ * - otherwise rotation: holders sorted by id, starting at `seed mod n`, walking forward past unavailable holders. The denominator is every
+ *   holder, availability never renumbers it (the #519 seed rule). When all are skipped, the seed holder is taken, "rotation (none available)".
+ */
+export function plannerWalk(input: PlannerWalkInput): PlannerWalk {
+  const holders = [...new Set(input.planners)].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  const walk: { peer: PeerId; note: string }[] = [];
+  const finish = (reason: PlannerReason, planner: PeerId | undefined, detail: string): PlannerWalk => ({ ...(planner ? { planner } : {}), reason, walk, line: planner ? `planner: ${planner} (${detail})` : `planner: none (${detail})` });
+  if (input.pii) return finish("none", undefined, "pii: planning stays with the person");
+  if (!holders.length) return finish("none", undefined, "no planner holder");
+  if (input.named !== undefined) {
+    if (!holders.includes(input.named)) { walk.push({ peer: input.named, note: "skipped, not a planner holder" }); return finish("none", undefined, `named ${input.named} is not a planner holder`); }
+    const why = input.blocked(input.named);
+    walk.push({ peer: input.named, note: why ? `named, ${why}` : "named" });
+    return finish("named", input.named, why ? `named; ${why}` : "named");
+  }
+  if (input.kept !== undefined && holders.includes(input.kept)) {
+    walk.push({ peer: input.kept, note: "kept: already the task's planner" });
+    return finish("kept", input.kept, "kept");
+  }
+  const seed = Number.isSafeInteger(input.seed) ? input.seed : 0;
+  const start = ((seed % holders.length) + holders.length) % holders.length;
+  for (let step = 0; step < holders.length; step++) {
+    const peer = holders[(start + step) % holders.length]!;
+    const why = input.blocked(peer);
+    walk.push({ peer, note: why ? `skipped, ${why}` : "available" });
+    if (!why) return finish("rotation", peer, step === 0 ? "rotation" : "rotation, skipped unavailable holders");
+  }
+  const seeded = holders[start]!;
+  return finish("rotation", seeded, "rotation (none available)");
+}
+
 /**
  * L1. A pure function of policy, task and peer states, so `ahub route explain` runs exactly what assignment runs and
  * prints its trace. `states`: effective bus states of attached peers (a peer that is not in the map is not attached).
@@ -338,6 +414,11 @@ export function assign(
     pullOnly?: PeerId[];
     namedOwner?: PeerId;
     namedReviewer?: PeerId;
+    /** #525-3: the settled planner holders (sorted ids) and a person-named planner. Absent `planners`: no planner walk, as before. */
+    planners?: readonly PeerId[];
+    namedPlanner?: PeerId;
+    /** The planner already recorded on the task (525-2): kept while it is still a holder. */
+    keptPlanner?: PeerId;
     reviewPool?: { pool: readonly string[]; rerotate?: boolean; failed?: readonly string[]; required?: boolean };
     candidates?: PeerId[];
     notReviewer?: PeerId;
@@ -376,11 +457,14 @@ export function assign(
   if (!pii) try { needsSpec = specRefs({ title: task.title ?? "", detail: task.detail ?? "", refs: task.refs ?? {}, external: task.external }, opts.repository ?? "", { bareTitle: isGitHubRepository(opts.repository) }).length > 0; }
   catch { needsSpec = true; } // an invalid/foreign reference never grants a sandboxed peer spec access
   const needsTests = ["implement", "test", "bulk_edit"].includes(task.class);
+  // #735: the owner needs write access whenever its role for this class is the implementer's, not only for the three classes that need tests.
+  const ownerWrites = ownerRoleOfClass(task.class) === "implementer";
   const refusals = new Map<string, RoutingRefusal>();
+  const former = implementers(task.history);
   const blocked = (peer: PeerId, role: "owner" | "reviewer"): string | undefined => {
     const deny = (code: RoutingRefusalCode, reason: string): string => { refusals.set(`${role}:${peer}`, { peer, role, code, reason }); return reason; };
     const ceiling = (opts.adapterCatalog?.definitionOf ?? definitionOf)(peer, opts.instances)?.routing?.allowedRoles;
-    const requiredRole = role === "reviewer" || task.class === "review" ? "reviewer" : task.class === "plan" ? "planner" : "implementer";
+    const requiredRole = role === "reviewer" ? "reviewer" : ownerRoleOfClass(task.class);
     if (ceiling && !ceiling.includes(requiredRole)) return deny("policy", "adapter role ceiling excludes this assignment");
     const unavailable = role === "reviewer" ? (opts.adapterCatalog?.definitionOf ?? definitionOf)(peer, opts.instances)?.reviewer?.unavailable : undefined;
     if (unavailable) return deny("policy", unavailable);
@@ -397,7 +481,7 @@ export function assign(
     if (role === "owner" && opts.excludeOwners?.includes(peer)) return deny("owner-admission", "owner admission: WIP or delivery hold");
     const adapter = (opts.adapterCatalog?.definitionOf ?? definitionOf)(peer, opts.instances);
     if (role === "owner" && adapter?.routing?.reviewOnly) return deny("owner-admission", "owner admission: a review-only instance owns no task");
-    if (role === "owner" && needsTests && adapter && adapter.kind !== peer) {
+    if (role === "owner" && ownerWrites && adapter && adapter.kind !== peer) {
       if (!peerEntry(opts.roles, peer)?.includes("implementer")) return deny("owner-admission", "owner admission: declared write owner requires the current implementer role");
       if (peerEntry(opts.ownerIsolation, peer) !== true) return deny("owner-admission", "owner admission: declared write owner requires a verified isolated execution root");
     }
@@ -414,6 +498,10 @@ export function assign(
       if (routing.signals.long_context_tokens > limit) return deny("policy", `${nativeRouting.backendLabel} ${backend} capability limit ${limit} tokens`);
     }
     if (nativeRouting?.longContext === "skip-owner" && role === "owner" && task.signals.includes("long_context") && routing.constraints.long_context === "skip_local") return deny("policy", "long_context: skip local");
+    // I-2 (#525-3): a peer that implemented this task never reviews it, whoever holds it now, a named reviewer included. It is the LAST check,
+    // so it only ever removes a candidate that was otherwise eligible: a former implementer that is offline, paused, failing or off roster is
+    // refused for that real reason and leaves the outcome exactly as it was before I-2 (a task with no other reviewer still approves directly).
+    if (role === "reviewer" && former.has(peer)) return deny("policy", "implemented this task");
     return undefined;
   };
   /** Quota that resets soonest gets used first: headroom per hour left in the window, at least 15 min (a task assigned that close to a reset mostly runs after it). */
@@ -479,6 +567,27 @@ export function assign(
   const ownerHold = owner ? peerEntry(opts.held, owner) : undefined;
   if (ownerHold) trace.push(`  hold: ${owner}'s queue is held: ${ownerHold} (it receives the task once the hold is resolved)`);
 
+  // #525-3: the planner is chosen by its own walk over the settled planner holders, independent of the owner and the reviewer (planner and
+  // owner, or planner and reviewer, may be the same peer). Information only until 525-2 records it: nothing here moves the task.
+  let planner: PeerId | undefined, plannerReason: PlannerReason | undefined;
+  if (opts.planners !== undefined) {
+    const plannerBlocked = (peer: PeerId): string | undefined => {
+      if ((opts.adapterCatalog?.definitionOf ?? definitionOf)(peer, opts.instances)?.routing?.allowedRoles?.includes("planner") === false) return "adapter role ceiling excludes planning";
+      if (opts.offRoster?.includes(peer)) return "off roster";
+      if (!Object.hasOwn(states, peer)) return "not attached";
+      if (states[peer] === "offline") return "offline";
+      if (states[peer] === "paused" && routing.constraints.budget_paused === "skip_peer") return "paused";
+      const failing = peerEntry(opts.failing, peer);
+      return failing ? `failing: ${failing}` : undefined;
+    };
+    const walked = plannerWalk({ planners: opts.planners, seed: task.id ?? 0, ...(opts.namedPlanner !== undefined ? { named: opts.namedPlanner } : {}),
+      ...(opts.keptPlanner !== undefined ? { kept: opts.keptPlanner } : {}), blocked: plannerBlocked, pii });
+    for (const row of walked.walk) trace.push(`  planner candidate ${row.peer}: ${row.note}`);
+    trace.push(walked.line);
+    planner = walked.planner;
+    plannerReason = walked.reason;
+  }
+
   let reviewer: PeerId | undefined;
   let sameFamilyFallback = false;
   let plannerFallback = false;
@@ -548,6 +657,12 @@ export function assign(
         sameFamilyFallback = true;
         trace.push(`  same-family fallback: ${reviewer} and ${reviewOwner} share ${ownerFamily}; no eligible other family`);
       }
+      // I-2 (#525-3): when the peers that implemented this task were the only candidates left, the person reviews. Never a fallback to an implementer.
+      if (!reviewer && [...refusals.values()].some(row => row.role === "reviewer" && row.code === "policy" && row.reason === "implemented this task")) {
+        reviewer = "user";
+        reviewBlocked = true;
+        trace.push("  every eligible reviewer implemented this task: the person reviews");
+      }
       trace.push(reviewer ? `reviewer: ${reviewer}` : "reviewer: none, done will approve directly");
       const reviewerHold = reviewer ? peerEntry(opts.held, reviewer) : undefined;
       if (reviewerHold) trace.push(`  hold: ${reviewer}'s queue is held: ${reviewerHold} (it receives the review once the hold is resolved)`);
@@ -558,7 +673,7 @@ export function assign(
   const piBackend = policy?.pi_backend;
   if (owner && (opts.adapterCatalog?.definitionOf ?? definitionOf)(owner, opts.instances)?.routing?.trace === "route") trace.push(`route: ${route ?? "(none)"}, fixed_model ${fixedModel}`);
   if (owner && (opts.adapterCatalog?.definitionOf ?? definitionOf)(owner, opts.instances)?.routing?.trace === "backend") trace.push(`${(opts.adapterCatalog?.definitionOf ?? definitionOf)(owner, opts.instances)!.routing!.backendLabel} decision: backend ${piBackend ?? "dgx"}${task.signals.includes("long_context") ? `, context limit ${piBackend === "mlx" ? routing.pi.mlx_max_context_tokens : routing.pi.dgx_max_context_tokens}` : ""}`);
-  return { ...(reviewSelection ? { reviewSelection } : {}), ...(reviewBlocked ? { reviewBlocked: true as const } : {}), ...(sameFamilyFallback ? { sameFamilyFallback: true as const } : {}), ...(plannerFallback ? { plannerFallback: true as const } : {}), ...(owner ? { owner } : {}), ...(pii ? { reviewer: "user" } : reviewer ? { reviewer } : {}), ...(route ? { route } : {}), fixedModel, ...(piBackend ? { piBackend } : {}), ...(unreserved ? { unreserved } : {}), ...(refusals.size ? { refusals: [...refusals.values()] } : {}), trace };
+  return { ...(reviewSelection ? { reviewSelection } : {}), ...(reviewBlocked ? { reviewBlocked: true as const } : {}), ...(sameFamilyFallback ? { sameFamilyFallback: true as const } : {}), ...(plannerFallback ? { plannerFallback: true as const } : {}), ...(owner ? { owner } : {}), ...(planner ? { planner } : {}), ...(plannerReason ? { plannerReason } : {}), ...(pii ? { reviewer: "user" } : reviewer ? { reviewer } : {}), ...(route ? { route } : {}), fixedModel, ...(piBackend ? { piBackend } : {}), ...(unreserved ? { unreserved } : {}), ...(refusals.size ? { refusals: [...refusals.values()] } : {}), trace };
 }
 
 /**

package/src/hub/sdlc-metrics.ts

@@ -0,0 +1,260 @@
+// #481 S7: SDLC metrics and deterministic control bands. Pure: board history in, numbers out. No I/O, no clock, no model.
+// A metric that cannot be derived is `unknown` and counted as such, never 0.
+// `first_pass_check` reads the hub's own completion check (`check passed` / `check failed` at hub_task_done), not PR CI: it is unknown where completion checks are off.
+
+export const BAND_METRICS = ["acceptance_to_plan_ms", "acceptance_to_first_review_ms", "first_pass_approval", "rework_rounds", "first_pass_check", "stale_head_re_reviews"] as const;
+export type BandMetric = typeof BAND_METRICS[number];
+export const BAND_TIERS = ["ok", "log", "diagnose", "propose"] as const;
+export type BandTier = typeof BAND_TIERS[number];
+
+/** The slice of a board task the metrics read. History entries carry ids, times and event names only. */
+export interface MetricTask {
+  id: number;
+  private?: boolean;
+  /** `requestHead` is the head a `done` asked review for (reviewCost.head); `verdictHead` the head a verdict was bound to (reviewFindings.head). Compared for equality only, never printed. */
+  history: { at: number; event: string; requestHead?: string; verdictHead?: string }[];
+}
+
+/** Per-task values; `null` is unknown. */
+export interface TaskSample {
+  id: number;
+  /** When the sample counts: its first verdict, else its acceptance, else its first event. */
+  at: number;
+  /** When the task was approved, else null: `rework_rounds` and `stale_head_re_reviews` are final only then, and sit at this time in their series. */
+  approved_at: number | null;
+  acceptance_to_plan_ms: number | null;
+  acceptance_to_first_review_ms: number | null;
+  acceptance_to_merge_ms: number | null;
+  first_pass_approval: 0 | 1 | null;
+  rework_rounds: number | null;
+  first_pass_check: 0 | 1 | null;
+  same_head_ci_reruns: number | null;
+  stale_head_re_reviews: number | null;
+}
+
+export interface Summary { n: number; unknown: number; mean: number | null; median: number | null; p90: number | null; max: number | null }
+export interface StallCounts { open: number; byKind: Record<string, number>; doneWithoutWrites: number }
+export interface BandConfig { window: number; minSamples: number; logSigma: number; diagnoseSigma: number; proposeSigma: number; driftRun: number; minDelta: number }
+export type BandsConfig = Partial<Record<BandMetric, BandConfig>>;
+export interface BandResult {
+  metric: BandMetric;
+  tier: BandTier;
+  /** Why the tier is what it is, in fixed words and numbers only. */
+  reason: string;
+  baseline: number;
+  mean: number | null;
+  sd: number | null;
+  last: number | null;
+  z: number | null;
+  /** The task that produced the last value: the breach's evidence. */
+  lastTask: number | null;
+  /** The task whose value started the run of non-ok values this one belongs to, else null: one breach episode has one card. */
+  episode: number | null;
+}
+
+/** Which way is worse. A rate that falls and a time that grows are both breaches. */
+export const BAD_DIRECTION: Record<BandMetric, "up" | "down"> = {
+  acceptance_to_plan_ms: "up", acceptance_to_first_review_ms: "up", first_pass_approval: "down", rework_rounds: "up", first_pass_check: "down", stale_head_re_reviews: "up",
+};
+const HOUR = 3_600_000;
+/** Per-metric floor on the absolute deviation, so a flat baseline does not make every wobble a breach. */
+export const DEFAULT_MIN_DELTA: Record<BandMetric, number> = {
+  acceptance_to_plan_ms: HOUR, acceptance_to_first_review_ms: HOUR, first_pass_approval: 0.5, rework_rounds: 1, first_pass_check: 0.5, stale_head_re_reviews: 1,
+};
+/** Per-metric floor on the baseline deviation: a flat baseline (every value the same) must not turn one step into thousands of deviations. */
+export const SD_FLOOR: Record<BandMetric, number> = {
+  acceptance_to_plan_ms: HOUR / 2, acceptance_to_first_review_ms: HOUR / 2, first_pass_approval: 0.5, rework_rounds: 0.5, first_pass_check: 0.5, stale_head_re_reviews: 0.5,
+};
+export const DEFAULT_BAND: Omit<BandConfig, "minDelta"> = { window: 20, minSamples: 8, logSigma: 2, diagnoseSigma: 3, proposeSigma: 4, driftRun: 6 };
+
+const first = (task: MetricTask, events: readonly string[], after = -Infinity) => task.history.find(entry => entry.at >= after && events.includes(entry.event));
+const VERDICTS = ["approved", "changes_requested"];
+
+/**
+ * Review rounds whose verdict was bound to a different head than the review was requested for: the head moved while the review ran.
+ * Known only for a round with both heads recorded; a task with no such round is unknown, never 0. (A `done` after an `approved` is not
+ * evidence: the board cannot produce one.)
+ * ponytail: the request head is `reviewCost.head` (the commit the done named first) while a verdict's head prefers the lifecycle receipt's
+ * `head`/`localHead` over `refs.commit` (`findingHead`), so a receipt head that differs from the commit can read as stale. Ceiling: a
+ * spurious stale round for a task whose receipt head and commit disagree; the upgrade is one shared head rule for both sides.
+ */
+function staleHeadRounds(history: MetricTask["history"]): number | null {
+  let pending: string | undefined, known = false, stale = 0;
+  for (const entry of history) {
+    if (entry.event === "done") pending = entry.requestHead;
+    else if (VERDICTS.includes(entry.event)) {
+      if (pending !== undefined && entry.verdictHead !== undefined) { known = true; if (entry.verdictHead !== pending) stale++; }
+      pending = undefined;
+    }
+  }
+  return known ? stale : null;
+}
+
+/** One task's values from its own history. A private task never reaches here. */
+export function taskSample(task: MetricTask, extra: { mergedAt?: number; ciReruns?: number | null } = {}): TaskSample {
+  const history = [...task.history].filter(entry => Number.isFinite(entry.at) && entry.at >= 0).sort((a, b) => a.at - b.at);
+  const view: MetricTask = { id: task.id, history };
+  const accepted = first(view, ["accepted"]);
+  const spec = first(view, ["spec accepted"]);
+  const plan = spec ? first(view, ["plan reviewed"], spec.at) : undefined;
+  const verdict = accepted ? first(view, VERDICTS, accepted.at) : first(view, VERDICTS);
+  const dones = history.filter(entry => entry.event === "done");
+  const ci = first(view, ["check passed", "check failed"]);
+  const approvedAt = history.find(entry => entry.event === "approved")?.at ?? null;
+  return {
+    id: task.id,
+    at: verdict?.at ?? accepted?.at ?? history[0]?.at ?? 0,
+    approved_at: approvedAt,
+    acceptance_to_plan_ms: spec && plan ? plan.at - spec.at : null,
+    acceptance_to_first_review_ms: accepted && verdict ? verdict.at - accepted.at : null,
+    acceptance_to_merge_ms: accepted && extra.mergedAt !== undefined && Number.isFinite(extra.mergedAt) && extra.mergedAt >= accepted.at ? extra.mergedAt - accepted.at : null,
+    first_pass_approval: verdict ? (verdict.event === "approved" ? 1 : 0) : null,
+    // Rework grows with every round, so it is a value only once the task is approved: a task still in flight has no final one, and a
+    // provisional point would move at each verdict and could start a second breach episode inside one shift.
+    rework_rounds: dones.length && approvedAt !== null ? history.filter(entry => entry.event === "changes_requested").length : null,
+    first_pass_check: ci ? (ci.event === "check passed" ? 1 : 0) : null,
+    same_head_ci_reruns: extra.ciReruns === undefined ? null : extra.ciReruns,
+    stale_head_re_reviews: approvedAt !== null ? staleHeadRounds(history) : null,
+  };
+}
+
+const percentile = (sorted: number[], p: number) => sorted[Math.min(sorted.length - 1, Math.max(0, Math.ceil(p * sorted.length) - 1))]!;
+export function summarize(values: readonly (number | null)[]): Summary {
+  const known = values.filter((value): value is number => value !== null && Number.isFinite(value)).sort((a, b) => a - b);
+  const unknown = values.length - known.length;
+  if (!known.length) return { n: 0, unknown, mean: null, median: null, p90: null, max: null };
+  const mean = known.reduce((sum, value) => sum + value, 0) / known.length;
+  return { n: known.length, unknown, mean: round(mean), median: round(percentile(known, 0.5)), p90: round(percentile(known, 0.9)), max: known.at(-1)! };
+}
+const round = (value: number) => Math.round(value * 1000) / 1000;
+
+/** The values of one metric in the order they happened, unknown ones left out. */
+export function series(samples: readonly TaskSample[], metric: BandMetric): { value: number; task: number }[] {
+  const final = metric === "rework_rounds" || metric === "stale_head_re_reviews";
+  const when = (sample: TaskSample) => final ? sample.approved_at ?? sample.at : sample.at;
+  return [...samples].sort((a, b) => when(a) - when(b) || a.id - b.id).flatMap(sample => sample[metric] === null ? [] : [{ value: sample[metric] as number, task: sample.id }]);
+}
+
+/**
+ * The newest value against the `window` values before it: mean, population standard deviation, and a tier from how many
+ * deviations the newest value sits on the bad side. A run of `driftRun` newest values all more than one deviation on the bad
+ * side is a drift and is at least `diagnose`. With fewer than `minSamples` before it, nothing fires.
+ */
+export function controlBands(points: readonly { value: number; task: number }[], metric: BandMetric, config: BandConfig): BandResult {
+  const baselineCount = Math.max(0, Math.min(config.window, points.length - 1));
+  const none = (reason: string, extra: Partial<BandResult> = {}): BandResult => ({ metric, tier: "ok", reason, baseline: baselineCount, mean: null, sd: null, last: points.at(-1)?.value ?? null, z: null, lastTask: points.at(-1)?.task ?? null, episode: null, ...extra });
+  if (points.length < 2 || baselineCount < config.minSamples) return none(`baseline of ${baselineCount} is below the ${config.minSamples} needed`);
+  const last = points.at(-1)!, base = points.slice(-1 - baselineCount, -1).map(point => point.value);
+  const mean = base.reduce((sum, value) => sum + value, 0) / base.length;
+  const sd = Math.sqrt(base.reduce((sum, value) => sum + (value - mean) ** 2, 0) / base.length);
+  const sign = BAD_DIRECTION[metric] === "up" ? 1 : -1;
+  const deviation = sign * (last.value - mean);
+  const z = deviation <= 0 ? 0 : deviation / Math.max(sd, SD_FLOOR[metric]);
+  const result = { metric, baseline: base.length, mean: round(mean), sd: round(sd), last: last.value, z: round(Math.min(z, 1e6)), lastTask: last.task, episode: null as number | null };
+  const drifting = deviation >= config.minDelta && deviation > 0 && points.length - 1 >= config.driftRun && points.slice(-config.driftRun).every(point => sign * (point.value - mean) > sd);
+  let tier: BandTier = "ok", reason = `${round(Math.min(z, 1e6))} deviations on the bad side`;
+  if (deviation >= config.minDelta && deviation > 0) {
+    if (z >= config.proposeSigma) { tier = "propose"; reason = `${round(Math.min(z, 1e6))} deviations beyond the baseline (propose at ${config.proposeSigma})`; }
+    else if (z >= config.diagnoseSigma) { tier = "diagnose"; reason = `${round(z)} deviations beyond the baseline (diagnose at ${config.diagnoseSigma})`; }
+    else if (z >= config.logSigma) { tier = "log"; reason = `${round(z)} deviations beyond the baseline (log at ${config.logSigma})`; }
+  }
+  if (drifting && BAND_TIERS.indexOf(tier) < BAND_TIERS.indexOf("diagnose")) { tier = "diagnose"; reason = `the last ${config.driftRun} values are all more than one deviation on the bad side`; }
+  return { ...result, tier, reason };
+}
+
+/** How far back an episode is searched. ponytail: a run longer than this restarts its key every sample, so the open-card rule in Tasks holds it to one card. */
+export const EPISODE_LOOKBACK = 200;
+/**
+ * `controlBands` for the newest value, plus the breach episode it belongs to: the trailing run of values whose own tier (computed from
+ * the values before each, with nothing after) was not `ok`. The episode is the task that started the run, so a sustained shift keeps one
+ * key for as long as it lasts, and it is derived from history alone, so it survives a restart.
+ */
+export function controlEpisode(points: readonly { value: number; task: number }[], metric: BandMetric, config: BandConfig): BandResult {
+  const now = controlBands(points, metric, config);
+  if (now.tier === "ok") return now;
+  let start = points.length - 1;
+  for (let end = points.length - 2; end >= 0 && points.length - 1 - end <= EPISODE_LOOKBACK; end--) {
+    if (controlBands(points.slice(0, end + 1), metric, config).tier === "ok") break;
+    start = end;
+  }
+  return { ...now, episode: points[start]!.task };
+}
+
+export interface MetricsReport {
+  since: number | null;
+  tasks: number;
+  withheldPrivate: number;
+  metrics: {
+    acceptance_to_plan_ms: Summary; acceptance_to_first_review_ms: Summary; acceptance_to_merge_ms: Summary;
+    first_pass_approval: { n: number; unknown: number; rate: number | null };
+    rework_rounds: Summary;
+    first_pass_check: { n: number; unknown: number; rate: number | null };
+    same_head_ci_reruns: Summary;
+    stale_head_re_reviews: Summary;
+  };
+  stalls: StallCounts;
+  bands: BandResult[] | "off";
+}
+
+const rate = (values: readonly (number | null)[]) => {
+  const known = values.filter((value): value is number => value !== null);
+  return { n: known.length, unknown: values.length - known.length, rate: known.length ? round(known.reduce((sum, value) => sum + value, 0) / known.length) : null };
+};
+
+/**
+ * The whole report from board tasks. `since` keeps samples that count at or after it; `mergedAt` and `ciReruns` come from bounded
+ * PR readbacks keyed by task id and are optional. Private tasks are counted as withheld and read for nothing else.
+ */
+export function sdlcMetrics(tasks: readonly MetricTask[], opts: { since?: number; bands?: BandsConfig; stalls?: StallCounts; mergedAt?: Readonly<Record<number, number>>; ciReruns?: Readonly<Record<number, number | null>> } = {}): MetricsReport {
+  const visible = tasks.filter(task => !task.private);
+  const all = visible.map(task => taskSample(task, { mergedAt: opts.mergedAt?.[task.id], ciReruns: opts.ciReruns?.[task.id] }));
+  const samples = opts.since === undefined ? all : all.filter(sample => sample.at >= opts.since!);
+  const bands: BandResult[] | "off" = opts.bands && Object.keys(opts.bands).length
+    ? BAND_METRICS.flatMap(metric => opts.bands![metric] ? [controlEpisode(series(samples, metric), metric, opts.bands![metric]!)] : [])
+    : "off";
+  return {
+    since: opts.since ?? null, tasks: samples.length, withheldPrivate: tasks.length - visible.length,
+    metrics: {
+      acceptance_to_plan_ms: summarize(samples.map(s => s.acceptance_to_plan_ms)), acceptance_to_first_review_ms: summarize(samples.map(s => s.acceptance_to_first_review_ms)),
+      acceptance_to_merge_ms: summarize(samples.map(s => s.acceptance_to_merge_ms)),
+      first_pass_approval: rate(samples.map(s => s.first_pass_approval)), rework_rounds: summarize(samples.map(s => s.rework_rounds)),
+      first_pass_check: rate(samples.map(s => s.first_pass_check)), same_head_ci_reruns: summarize(samples.map(s => s.same_head_ci_reruns)),
+      stale_head_re_reviews: summarize(samples.map(s => s.stale_head_re_reviews)),
+    },
+    stalls: opts.stalls ?? { open: 0, byKind: {}, doneWithoutWrites: 0 }, bands,
+  };
+}
+
+const BAND_KEYS = ["window", "min_samples", "log_sigma", "diagnose_sigma", "propose_sigma", "drift_run", "min_delta"] as const;
+/**
+ * `[bands.<metric>]` tables of sdlc.toml. Every field is optional and bounded; an unknown metric or field is refused with its
+ * path, and the tiers must be ordered log <= diagnose <= propose so a breach never skips a tier it is meant to pass through.
+ */
+export function bandsConfig(value: unknown): BandsConfig {
+  if (value === undefined) return {};
+  const fail = (path: string, why: string): never => { throw new Error(`sdlc.bands${path}: ${why}`); };
+  if (!value || typeof value !== "object" || Array.isArray(value)) return fail("", "expected a table");
+  const out: BandsConfig = {};
+  for (const [metric, raw] of Object.entries(value as Record<string, unknown>)) {
+    if (!(BAND_METRICS as readonly string[]).includes(metric)) fail(`.${metric}`, `unknown metric (use ${BAND_METRICS.join(", ")})`);
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) fail(`.${metric}`, "expected a table");
+    const row = raw as Record<string, unknown>;
+    for (const key of Object.keys(row)) if (!(BAND_KEYS as readonly string[]).includes(key)) fail(`.${metric}.${key}`, "unknown field");
+    const number = (key: typeof BAND_KEYS[number], fallback: number, min: number, max: number, integer: boolean) => {
+      const given = row[key] ?? fallback;
+      if (typeof given !== "number" || !Number.isFinite(given) || given < min || given > max || integer && !Number.isSafeInteger(given)) fail(`.${metric}.${key}`, `expected ${integer ? "an integer" : "a number"} from ${min} to ${max}`);
+      return given as number;
+    };
+    const m = metric as BandMetric;
+    const config: BandConfig = {
+      window: number("window", DEFAULT_BAND.window, 4, 200, true), minSamples: number("min_samples", DEFAULT_BAND.minSamples, 3, 200, true),
+      logSigma: number("log_sigma", DEFAULT_BAND.logSigma, 0.5, 20, false), diagnoseSigma: number("diagnose_sigma", DEFAULT_BAND.diagnoseSigma, 0.5, 20, false),
+      proposeSigma: number("propose_sigma", DEFAULT_BAND.proposeSigma, 0.5, 20, false), driftRun: number("drift_run", DEFAULT_BAND.driftRun, 3, 50, true),
+      minDelta: number("min_delta", DEFAULT_MIN_DELTA[m], 0, 1e12, false),
+    };
+    if (config.minSamples > config.window) fail(`.${metric}.min_samples`, "must not exceed window");
+    if (!(config.logSigma <= config.diagnoseSigma && config.diagnoseSigma <= config.proposeSigma)) fail(`.${metric}`, "tiers must be ordered log_sigma <= diagnose_sigma <= propose_sigma");
+    out[m] = config;
+  }
+  return out;
+}

package/src/hub/sdlc.ts

@@ -2,6 +2,7 @@ import { parseIssueLabels, parseRedFirst, testIntegrityBlockers, type RedFirstRe
 import { planConformanceBlockers, type PlanConformance } from "./plan-conformance.ts";
 import { DEFAULT_MAX_NITS, findingsForHead, findingHead, findingTally, type ReviewFindingSet, type ReviewFindingTally } from "./review-findings.ts";
 import type { CostPlan } from "./cost-governance.ts";
+import { bandsConfig, type BandsConfig } from "./sdlc-metrics.ts";
 import { criteriaReceipt, type CriteriaReceipt, type CriteriaView, type LegacyPhaseReceipt } from "./workflow.ts";
 import { constants, openSync, fstatSync, readSync, closeSync } from "node:fs";
 import { join } from "node:path";
@@ -32,7 +33,7 @@ export type StageGate = "issue" | "pr" | "local" | "review" | "checks" | "criter
 export interface StageDefinition { base: SdlcBaseStage; actor: string; entry_gates: StageGate[]; exit_gates: StageGate[]; after: string[]; }
 export type SdlcMode = "off" | "advise" | "enforce";
 /** `workflow: "gsd-lite"` marks the retired setting during its window (#481 S8): every task then needs a criteria checklist. */
-export interface SdlcConfig { workflow?: "gsd-lite"; maxNits?: number; mode: SdlcMode; requiredChecks: string[]; stages: SdlcStage[]; definitions?: Record<string, StageDefinition>; deprecations?: string[]; }
+export interface SdlcConfig { workflow?: "gsd-lite"; maxNits?: number; /** #481 S7: optional control bands per metric; absent means none. */ bands?: BandsConfig; mode: SdlcMode; requiredChecks: string[]; stages: SdlcStage[]; definitions?: Record<string, StageDefinition>; deprecations?: string[]; }
 export interface PlanReviewReceipt {
   planner: string;
   planningRevision: number;
@@ -133,10 +134,11 @@ export function sdlcConfig(value: unknown, version?: string): SdlcConfig {
   if (value === undefined) return { mode: "off", requiredChecks: [], stages: [...SDLC_STAGES] };
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("sdlc: expected a table");
   const raw = value as Record<string, unknown>;
-  for (const key of Object.keys(raw)) if (!["mode", "required_checks", "stages", "workflow", "definitions", "max_nits"].includes(key)) throw new Error(`sdlc.${key}: unknown field`);
+  for (const key of Object.keys(raw)) if (!["mode", "required_checks", "stages", "workflow", "definitions", "max_nits", "bands"].includes(key)) throw new Error(`sdlc.${key}: unknown field`);
   const maxNits = raw.max_nits === undefined ? DEFAULT_MAX_NITS : raw.max_nits;
   if (typeof maxNits !== "number" || !Number.isSafeInteger(maxNits) || maxNits < 0 || maxNits > 64) throw new Error("sdlc.max_nits: expected an integer from 0 to 64");
-  const findingConfig = raw.max_nits === undefined ? {} : { maxNits };
+  const bands = bandsConfig(raw.bands), bandConfig = Object.keys(bands).length ? { bands } : {};
+  const findingConfig = { ...(raw.max_nits === undefined ? {} : { maxNits }), ...bandConfig };
   const mode = raw.mode ?? "off";
   if (mode !== "off" && mode !== "advise" && mode !== "enforce") throw new Error("sdlc.mode: expected off, advise or enforce");
   // ponytail: the #481 S8 window is a fixed version; delete `workflow`, the phase aliases and their tests once it passes.

package/src/hub/settings.ts

@@ -473,7 +473,7 @@ export function settingRows(input: {
   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, input.adapterCatalog).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 }),
-      ...(def.key === "scoped_grants.protect_instructions" ? { hint: "AGENTS.md, CLAUDE.md and QWEN.md remain grantable by default; enabling this asks before scoped writes and edits" } : def.key.startsWith("action_policy.") ? { hint: "not enforced yet: adapter integration pending" } : def.group === "Permissions" ? { hint: permissionBoundary(def.path.at(-1)!, input.instances, input.adapterCatalog) } : {}) };
+      ...(def.key === "scoped_grants.protect_instructions" ? { hint: "AGENTS.md, CLAUDE.md and QWEN.md remain grantable by default; enabling this asks before scoped writes and edits" } : def.key.startsWith("action_policy.") ? { hint: "enforced for Claude (PreToolUse hook) and hub-owned ACP peers in ask mode; ahub status lists each peer that is not enforceable" } : def.group === "Permissions" ? { hint: permissionBoundary(def.path.at(-1)!, input.instances, input.adapterCatalog) } : {}) };
     if (def.locked) return { ...base, values: def.values, file: def.store === "runtime" ? "this hub run" : CONFIG_LOCAL,
       source: "instance declaration", value: "read-only", fileValue: "read-only", locked: def.locked, note: def.locked };
     if (def.store === "runtime") {

package/src/hub/spec-read.ts

@@ -48,6 +48,37 @@ export function specRefs(task: Pick<Task, "title" | "detail" | "refs"> & Partial
   return [...issues];
 }
 
+/**
+ * #723: issue numbers a title names as a sibling repository (`agent-mem#13`) when the task's `refs.repo` is that repository.
+ * The bare name must equal the repository part of `refs.repo`; nothing else is guessed, and nothing is read. A bare
+ * `#N` and an `owner/repo#N` form are specRefs' business, never this function's.
+ */
+export function siblingTitleRefs(title: string, repo: string | undefined): number[] {
+  if (!repo || !isGitHubRepository(repo)) return [];
+  const name = repo.split("/")[1]!.toLowerCase(), found = new Set<number>();
+  for (const match of title.matchAll(/(?<![A-Za-z0-9_./-])([A-Za-z0-9_.-]+)#([1-9][0-9]*)\b/g)) {
+    if (match[1]!.toLowerCase() === name) found.add(Number(match[2]));
+  }
+  return [...found].slice(0, 4);
+}
+
+/** Words that precede `#N` without naming a repository (`PR#12`); never worth a refs.repo suggestion. */
+const NOT_A_REPOSITORY = new Set(["pr", "pull", "issue", "issues", "task", "tasks", "bug", "fix", "phase", "step", "item", "ticket", "gh", "id", "no", "nr", "p", "s", "t", "u"]);
+/**
+ * #723: the qualified repository names a title carries (`owner/repo#N` as `owner/repo`, `agent-mem#13` as `agent-mem`), so
+ * propose can suggest `refs.repo`. Advice only: a hit is a hint, never an identity.
+ */
+export function qualifiedTitleRepos(title: string): string[] {
+  const found = new Set<string>();
+  for (const match of title.matchAll(/(?<![A-Za-z0-9_./-])(?:([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)|([A-Za-z0-9_.-]*[A-Za-z][A-Za-z0-9_.-]*))#[1-9][0-9]*\b/g)) {
+    const name = match[1] ?? match[2]!;
+    if (match[1] ? !isGitHubRepository(name) : NOT_A_REPOSITORY.has(name.toLowerCase())) continue;
+    found.add(name);
+    if (found.size >= 4) break;
+  }
+  return [...found];
+}
+
 interface GhResult { code: number; stdout: string; }
 /** One fixed-argv authenticated boundary, no shell, no retries and no retained stderr. */
 function gh(args: string[], opts: SpecOptions): Promise<GhResult> {

package/src/hub/task-code-group.ts

@@ -0,0 +1,52 @@
+import { symbolsOverlap } from "./symbol-normalizer.ts";
+
+// #684 2c: the dashboard task sheet's "Code" group, classified on the hub so the page never matches names itself. Pure data in, ids and
+// names out. The observation (`codeSymbols`) is the receipt `Tasks.publicView` already re-screened; the plan names are `plan.symbols`, the same
+// list the review brief reads as `planned`. Advisory only: ripwire does not report deleted symbols, so neither list proves a plan was followed.
+
+export interface CodeGroupSymbol { id: string; name: string; path: string; kind: string; mark: "matching" | "unplanned" }
+export interface CodeGroup {
+  state: "known" | "unknown";
+  complete: boolean;
+  head?: string;
+  symbols: CodeGroupSymbol[];
+  /** Plan names nothing changed under. */
+  untouched: string[];
+  /** How many more changed symbols exist than are listed, so a cap is never read as the whole. */
+  more: number;
+  /** Totals before the cap, so the sheet's counts are the whole and not the listed part. */
+  counts: { matching: number; unplanned: number; untouched: number };
+  /** Plan names the hub would not show (screened out or malformed). While any is withheld a symbol marked unplanned may be planned, and one marked untouched may not be. */
+  planWithheld: number;
+}
+
+export const CODE_GROUP_MAX = 40;
+/** The stored plan's own bounds (`cleanPlan`: 300 characters a name, 50 names), so no stored name is dropped for its length alone. */
+export const PLAN_NAME_MAX = 300, PLAN_NAMES_MAX = 50;
+interface Receipt { state?: unknown; complete?: unknown; head?: unknown; symbols?: unknown }
+const word = (value: unknown, max: number): value is string => typeof value === "string" && value.length > 0 && value.length <= max && !/[\p{Cc}\p{Cf}]/u.test(value);
+
+/**
+ * `receipt` is the public `codeSymbols` (never the stored one, which carries `repositoryKey`); `plan` the task's `plan.symbols`; `screen`
+ * the hub's `publicMetadataText`. Returns undefined for a private task: the sheet then shows no Code group at all.
+ */
+export function codeGroup(task: { id: number }, receipt: unknown, plan: unknown, screen: (text: string) => boolean, privateTask: boolean): CodeGroup | undefined {
+  if (privateTask) return undefined;
+  const r = (receipt && typeof receipt === "object" && !Array.isArray(receipt) ? receipt : undefined) as Receipt | undefined;
+  if (!r || r.state !== "known" || !Array.isArray(r.symbols) || Object.hasOwn(r, "repositoryKey")) return { state: "unknown", complete: false, symbols: [], untouched: [], more: 0, counts: { matching: 0, unplanned: 0, untouched: 0 }, planWithheld: 0 };
+  // Every stored plan name is read; one that is malformed or fails the screen is counted, never silently dropped, because dropping it would
+  // turn a symbol the plan names into an "unplanned" one and the sheet would show a departure that never happened.
+  const given = Array.isArray(plan) ? plan.slice(0, PLAN_NAMES_MAX + 1) : [];
+  const planned = given.slice(0, PLAN_NAMES_MAX).filter((name): name is string => word(name, PLAN_NAME_MAX)).filter(name => { try { return screen(name); } catch { return false; } });
+  const planWithheld = (given.length > PLAN_NAMES_MAX ? given.length - PLAN_NAMES_MAX : 0) + (Math.min(given.length, PLAN_NAMES_MAX) - planned.length);
+  const changed: CodeGroupSymbol[] = [];
+  for (const item of r.symbols as Record<string, unknown>[]) {
+    if (!item || !word(item.id, 512) || !word(item.name, 512) || !word(item.path, 512) || !word(item.kind, 64) || item.id !== `symbol:${item.name}@${item.path}`) continue;
+    changed.push({ id: item.id, name: item.name, path: item.path, kind: item.kind, mark: planned.some(name => symbolsOverlap(name, item.name as string)) ? "matching" : "unplanned" });
+  }
+  const untouched = planned.filter(name => !changed.some(symbol => symbolsOverlap(name, symbol.name)));
+  const shown = changed.slice(0, CODE_GROUP_MAX);
+  return { state: "known", complete: r.complete === true && changed.length === r.symbols.length && planWithheld === 0, ...(typeof r.head === "string" && /^[a-f0-9]{40}$/.test(r.head) ? { head: r.head.slice(0, 8) } : {}),
+    symbols: shown, untouched: untouched.slice(0, CODE_GROUP_MAX), more: Math.max(0, changed.length - shown.length) + Math.max(0, untouched.length - CODE_GROUP_MAX),
+    counts: { matching: changed.filter(s => s.mark === "matching").length, unplanned: changed.filter(s => s.mark === "unplanned").length, untouched: untouched.length }, planWithheld };
+}