@staix/agent-hub 0.12.44 → 0.13.0

package/src/hub/sdlc.ts

@@ -1,3 +1,6 @@
+import { parseIssueLabels, parseRedFirst, testIntegrityBlockers, type RedFirstReceipt, type TestIntegrity } from "./test-integrity.ts";
+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 { criteriaReceipt, type CriteriaReceipt, type CriteriaView, type LegacyPhaseReceipt } from "./workflow.ts";
 import { constants, openSync, fstatSync, readSync, closeSync } from "node:fs";
@@ -29,7 +32,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"; mode: SdlcMode; requiredChecks: string[]; stages: SdlcStage[]; definitions?: Record<string, StageDefinition>; deprecations?: string[]; }
+export interface SdlcConfig { workflow?: "gsd-lite"; maxNits?: number; mode: SdlcMode; requiredChecks: string[]; stages: SdlcStage[]; definitions?: Record<string, StageDefinition>; deprecations?: string[]; }
 export interface PlanReviewReceipt {
   planner: string;
   planningRevision: number;
@@ -53,6 +56,7 @@ export interface SdlcReceipt {
   localHead?: string;
   localResult?: "passed" | "failed" | "unknown";
   observed?: number;
+  redFirst?: RedFirstReceipt;
 }
 export interface PrEvidence {
   head: string;
@@ -62,7 +66,11 @@ export interface PrEvidence {
   unresolved: number | null;
   pendingReviews: number | null;
   paths: string[];
+  fileChanges?: { path: string; change: string }[];
+  issueLabels?: { issue: number; labels: string[] | null };
   pathsComplete?: boolean;
+  /** All affected path identities are represented; rename/copy destinations alone cannot certify S2. */
+  typesComplete?: boolean;
   draft?: boolean;
   base?: string;
   baseHead?: string;
@@ -125,7 +133,10 @@ 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"].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"].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 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.
@@ -140,7 +151,7 @@ export function sdlcConfig(value: unknown, version?: string): SdlcConfig {
   if (raw.definitions !== undefined) {
     const custom = definitions(raw.definitions, raw.stages, phaseAlias);
     if (phaseAlias.used) notes.push(`the sdlc phase gate is deprecated and stops loading in ${RETIRED_WORKFLOW_FROM} (#481): name it criteria`);
-    return { mode, requiredChecks: [...checks] as string[], ...custom, ...(workflow === "gsd-lite" ? { workflow } : {}), ...(notes.length ? { deprecations: notes } : {}) };
+    return { mode, ...findingConfig, requiredChecks: [...checks] as string[], ...custom, ...(workflow === "gsd-lite" ? { workflow } : {}), ...(notes.length ? { deprecations: notes } : {}) };
   }
   // Off keeps the #257 seven stages byte for byte; an enabled lifecycle defaults to the playbook (#481 S0).
   const given = raw.stages ?? (mode === "off" ? [...SDLC_STAGES] : [...PLAYBOOK_STAGES]);
@@ -148,7 +159,7 @@ export function sdlcConfig(value: unknown, version?: string): SdlcConfig {
   // An enabled #257 list keeps its order under canonical ids, so implement/verify stay read-only aliases there too.
   const stages = mode !== "off" && exactly(SDLC_STAGES) ? SDLC_STAGES.map(canonicalStage) : given;
   if (!exactly(SDLC_STAGES) && !exactly(PLAYBOOK_STAGES)) throw new Error(`sdlc.stages: use ${PLAYBOOK_STAGES.join(", ")} in that order (or the #257 list ${SDLC_STAGES.join(", ")}); other lists need definitions`);
-  return { mode, requiredChecks: [...checks] as string[], stages: [...stages as string[]], ...(workflow === "gsd-lite" ? { workflow } : {}), ...(notes.length ? { deprecations: notes } : {}) };
+  return { mode, ...findingConfig, requiredChecks: [...checks] as string[], stages: [...stages as string[]], ...(workflow === "gsd-lite" ? { workflow } : {}), ...(notes.length ? { deprecations: notes } : {}) };
 }
 
 export function loadSdlc(cwd: string, version?: string): SdlcConfig {
@@ -171,7 +182,7 @@ export function loadSdlc(cwd: string, version?: string): SdlcConfig {
 export function sdlcReceipt(value: unknown, previous: SdlcReceipt | undefined = undefined, config: SdlcConfig = sdlcConfig(undefined), version?: string): SdlcReceipt {
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("sdlc receipt: expected an object");
   const raw = value as Record<string, unknown>;
-  for (const key of Object.keys(raw)) if (!["stage", "repo", "issue", "pr", "reviewedHead", "localHead", "localResult", "criteria", "phase"].includes(key)) throw new Error(`sdlc receipt.${key}: unsupported or externally observed field`);
+  for (const key of Object.keys(raw)) if (!["stage", "repo", "issue", "pr", "reviewedHead", "localHead", "localResult", "criteria", "phase", ...(config.mode !== "off" ? ["redFirst"] : [])].includes(key)) throw new Error(`sdlc receipt.${key}: unsupported or externally observed field`);
   if (raw.criteria !== undefined && raw.phase !== undefined) throw new Error("sdlc receipt: give criteria only; phase is its retired name");
   if (raw.phase !== undefined && version !== undefined && !olderThan(version, RETIRED_WORKFLOW_FROM)) throw new Error(`sdlc receipt.phase: retired in ${RETIRED_WORKFLOW_FROM} (#481); use criteria`);
   previous ??= { stage: config.stages[0] ?? "spec" };
@@ -192,6 +203,9 @@ export function sdlcReceipt(value: unknown, previous: SdlcReceipt | undefined =
     if (!["passed", "failed", "unknown"].includes(String(raw.localResult))) throw new Error("sdlc receipt.localResult: expected passed, failed or unknown");
     next.localResult = raw.localResult as SdlcReceipt["localResult"];
   }
+  if (raw.redFirst !== undefined) next.redFirst = parseRedFirst(raw.redFirst);
+  // A test receipt never carries across a different linked issue or artifact.
+  if (raw.redFirst === undefined && (next.repo !== previous.repo || next.issue !== previous.issue || next.pr !== previous.pr)) delete next.redFirst;
   // An acceptance names one spec issue; relinking the receipt to another drops it (#481 S1).
   if (next.repo !== previous.repo || next.issue !== previous.issue) delete next.acceptance;
   // A new artifact cannot inherit another PR's review or local gate.
@@ -216,7 +230,9 @@ export function parsePrEvidence(value: unknown): PrEvidence {
     return { name, state } as PrEvidence["checks"][number];
   });
   const paths = p.files.map((f: Record<string, unknown>) => { if (typeof f.path !== "string" || !f.path || f.path.length > 1000) throw new Error("PR readback: invalid file identity"); return f.path; });
-  return { head: p.headRefOid, state: p.state, checks, paths, pathsComplete: Number.isSafeInteger(p.changedFiles) && p.changedFiles >= 0 && p.changedFiles === paths.length, ...(typeof p.isDraft === "boolean" ? { draft: p.isDraft } : {}), ...(typeof p.baseRefName === "string" && p.baseRefName && p.baseRefName.length <= 200 && !/[\x00-\x1f\x7f]/.test(p.baseRefName) ? { base: p.baseRefName } : {}), ...(sha(p.baseRefOid) ? { baseHead: p.baseRefOid } : {}),
+  const completeTypes = p.files.every((file: Record<string, unknown>) => typeof file.changeType === "string" && ["ADDED", "DELETED", "MODIFIED", "CHANGED"].includes(file.changeType));
+  // Rename/copy metadata exposes only its destination, never a complete inventory of affected identities.
+  return { head: p.headRefOid, state: p.state, checks, paths, fileChanges: p.files.map((file: Record<string, unknown>) => ({ path: file.path as string, change: typeof file.changeType === "string" ? file.changeType : "UNKNOWN" })), pathsComplete: Number.isSafeInteger(p.changedFiles) && p.changedFiles >= 0 && p.changedFiles === paths.length, typesComplete: completeTypes, ...(typeof p.isDraft === "boolean" ? { draft: p.isDraft } : {}), ...(typeof p.baseRefName === "string" && p.baseRefName && p.baseRefName.length <= 200 && !/[\x00-\x1f\x7f]/.test(p.baseRefName) ? { base: p.baseRefName } : {}), ...(sha(p.baseRefOid) ? { baseHead: p.baseRefOid } : {}),
     review: p.reviewDecision === "APPROVED" ? "approved" : p.reviewDecision === "CHANGES_REQUESTED" ? "changes_requested" : "unknown",
     pendingReviews: Array.isArray(p.reviewRequests) && p.reviewRequests.length <= 100 && p.reviewRequests.every((r: unknown) => !!r && typeof r === "object") ? p.reviewRequests.length : null,
     unresolved: Number.isSafeInteger(p.unresolvedThreads) && p.unresolvedThreads >= 0 ? p.unresolvedThreads : null,
@@ -239,12 +255,16 @@ export const SPEC_STATE_TEXT: Record<Exclude<SpecState, "current">, string> = {
   changed: "spec changed after acceptance: the person re-accepts with ahub sdlc accept <task> --issue <n>",
   unknown: "spec edit time unknown: the issue could not be read",
 };
-export interface SdlcStatus { spec?: { issue: number; state: SpecState }; playbook?: string; criteria?: CriteriaView; mode: SdlcMode; stage: SdlcStage; definition?: StageDefinition; entry?: string[]; exit?: string[]; blockers: string[]; ready: boolean; actor: string; next: string; }
+export interface SdlcStatus { testIntegrity?: TestIntegrity; planConformance?: PlanConformance & { accepted?: boolean; earlierPushes?: "unknown"; revisionsAfterFirstObservedPush?: number }; findings?: ReviewFindingTally; spec?: { issue: number; state: SpecState }; playbook?: string; criteria?: CriteriaView; mode: SdlcMode; stage: SdlcStage; definition?: StageDefinition; entry?: string[]; exit?: string[]; blockers: string[]; ready: boolean; actor: string; next: string; }
 /** The acceptance-criteria checklist (#481 S8, Compliance pass) counts once recorded, and on every task under the retired gsd-lite setting. Off keeps #257's output. */
 export const criteriaRequired = (config: SdlcConfig, receipt: SdlcReceipt | undefined): boolean => config.workflow === "gsd-lite" || (config.mode !== "off" && !!checklistOf(receipt));
-export function sdlcStatus(config: SdlcConfig, receipt: SdlcReceipt | undefined, evidence?: PrEvidence, criteria?: CriteriaView, specEdit?: SpecEdit): SdlcStatus {
+export function sdlcStatus(config: SdlcConfig, receipt: SdlcReceipt | undefined, evidence?: PrEvidence, criteria?: CriteriaView, specEdit?: SpecEdit, sets: readonly ReviewFindingSet[] = [], commit?: string, plan?: SdlcStatus["planConformance"], integrity?: TestIntegrity): SdlcStatus {
   const stage = receipt?.stage ?? config.stages[0] ?? "spec", blockers: string[] = [];
   const definition = stageDefinition(config, stage);
+  const items = findingsForHead(sets, findingHead(receipt, evidence, commit));
+  const findings = items.length ? findingTally(items) : undefined;
+  if (config.mode === "enforce" && findings?.openImportant) blockers.push("open important review findings: " + findings.openImportant);
+  if (config.mode === "enforce") blockers.push(...planConformanceBlockers(plan), ...testIntegrityBlockers(integrity));
   if (!definition) blockers.push("lifecycle stage definition unknown");
   if (!receipt?.repo || !receipt.issue) blockers.push("issue identity missing");
   if (!receipt?.pr) blockers.push("PR identity missing");
@@ -270,9 +290,10 @@ export function sdlcStatus(config: SdlcConfig, receipt: SdlcReceipt | undefined,
   const shown = criteria && (criteriaRequired(config, receipt) || definition && [...definition.entry_gates, ...definition.exit_gates].includes("criteria"));
   // Shown, not counted as a readiness blocker: the spec gate is build entry (#481 S1).
   const spec = config.mode !== "off" && receipt?.issue ? { spec: { issue: receipt.issue, state: specState(receipt, specEdit) } } : {};
-  return { ...spec, ...(config.mode !== "off" && definition && playbookStage(definition.base) ? { playbook: playbookStage(definition.base) } : {}), ...(shown ? { criteria } : {}), ...(custom ? { definition, ...custom } : {}), mode: config.mode, stage, blockers, ready: blockers.length === 0,
+  return { ...spec, ...(config.mode !== "off" && integrity ? { testIntegrity: integrity } : {}), ...(config.mode !== "off" && plan ? { planConformance: plan } : {}), ...(findings ? { findings } : {}), ...(config.mode !== "off" && definition && playbookStage(definition.base) ? { playbook: playbookStage(definition.base) } : {}), ...(shown ? { criteria } : {}), ...(custom ? { definition, ...custom } : {}), mode: config.mode, stage, blockers, ready: blockers.length === 0,
     actor: !definition ? "person" : shown && criteria.blockers.length ? "reviewer/person" : config.definitions ? definition.actor : baseActor(definition.base),
-    next: blockers[0] ?? "person may inspect merge readiness; no automatic merge" };
+    // #694: the identity blocker keeps its exact text for gate matching; the next step says how to supply it.
+    next: blockers[0] === "issue identity missing" ? "issue identity missing: name one issue (title #N, refs or hub_sdlc_record)" : blockers[0] ?? "person may inspect merge readiness; no automatic merge" };
 }
 
 function stageGates(def: StageDefinition, blockers: string[], checklist: string[]): { entry: string[]; exit: string[] } {
@@ -324,23 +345,53 @@ export async function readSpecEdit(repoName: string, issue: number, run: SdlcGh
   } catch { return undefined; }
 }
 
-export async function readSdlcPr(receipt: SdlcReceipt, run: SdlcGh = sdlcGh): Promise<PrEvidence | undefined> {
+/**
+ * #694: the one open PR whose head is `commit`, or, with no commit, whose branch is `branch`. Zero or several matches, a
+ * failed read or malformed output give undefined: the hub links only what it verified, never text an agent wrote.
+ */
+export async function openPrFor(repository: string, head: { commit?: string; branch?: string }, run: SdlcGh = sdlcGh): Promise<number | undefined> {
+  if (!repo(repository) || head.commit !== undefined && !sha(head.commit) || !head.commit && !head.branch) return undefined;
+  try {
+    const listed = await run(["pr", "list", "--repo", repository, "--state", "open", "--limit", "100", "--json", "number,headRefOid,headRefName"], 10_000, undefined, 256 * 1024);
+    if (listed.code !== 0) return undefined;
+    const rows: unknown = JSON.parse(listed.stdout);
+    // A full page may be truncated: uniqueness is unknown, so nothing is linked. Every row must be well formed.
+    if (!Array.isArray(rows) || rows.length >= 100) return undefined;
+    if (!rows.every((row: { number?: unknown; headRefOid?: unknown; headRefName?: unknown }) => id(row?.number) && sha(row.headRefOid) && typeof row.headRefName === "string")) return undefined;
+    const hits = rows.filter((row: { headRefOid: string; headRefName: string }) => head.commit ? row.headRefOid === head.commit : row.headRefName === head.branch);
+    return hits.length === 1 ? (hits[0] as { number: number }).number : undefined;
+  } catch { return undefined; }
+}
+/** #694: the first link of an issue or PR is not a relink: it keeps everything the receipt already holds. */
+export function linkedReceipt(previous: SdlcReceipt | undefined, link: { repo: string; issue?: number; pr?: number }, config: SdlcConfig): SdlcReceipt | undefined {
+  if (!repo(link.repo) || link.issue !== undefined && !id(link.issue) || link.pr !== undefined && !id(link.pr)) return undefined;
+  if (previous?.repo && previous.repo.toLowerCase() !== link.repo.toLowerCase()) return undefined;
+  if (link.issue !== undefined && previous?.issue !== undefined || link.pr !== undefined && previous?.pr !== undefined) return undefined;
+  return { ...(previous ?? { stage: config.stages[0] ?? "spec" }), repo: previous?.repo ?? link.repo, ...(link.issue !== undefined ? { issue: link.issue } : {}), ...(link.pr !== undefined ? { pr: link.pr } : {}) };
+}
+
+export async function readSdlcPr(receipt: SdlcReceipt, run: SdlcGh = sdlcGh, withIntegrity = false): Promise<PrEvidence | undefined> {
   if (!repo(receipt.repo) || !id(receipt.pr)) return undefined;
   try {
     const view = await run(["pr", "view", String(receipt.pr), "--repo", receipt.repo, "--json", "headRefOid,state,statusCheckRollup,reviewDecision,reviewRequests,files,changedFiles,mergeCommit,isDraft,baseRefName,baseRefOid"]);
     if (view.code !== 0) return undefined;
     const [owner, name] = receipt.repo.split("/");
-    const threads = await run(["api", "graphql", "-f", "query=query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){pullRequest(number:$number){headRefOid reviewThreads(first:100){nodes{isResolved} pageInfo{hasNextPage}}}}}", "-f", `owner=${owner}`, "-f", `name=${name}`, "-F", `number=${receipt.pr}`]);
+    // The enabled S4 label read shares the existing thread snapshot, never a second readback for a known non-bug.
+    const labels = withIntegrity && id(receipt.issue) ? { issue: receipt.issue, labels: null as string[] | null } : undefined;
+    const query = `query($owner:String!,$name:String!,$number:Int!${labels ? ",$issue:Int!" : ""}){repository(owner:$owner,name:$name){pullRequest(number:$number){headRefOid reviewThreads(first:100){nodes{isResolved} pageInfo{hasNextPage}}}${labels ? " issue(number:$issue){number labels(first:100){nodes{name} pageInfo{hasNextPage}}}" : ""}}}`;
+    const threads = await run(["api", "graphql", "-f", `query=${query}`, "-f", `owner=${owner}`, "-f", `name=${name}`, ...(labels ? ["-F", `issue=${labels.issue}`] : []), "-F", `number=${receipt.pr}`]);
     const p = JSON.parse(view.stdout);
     delete p.unresolvedThreads; // only the complete thread query can establish this fact
     if (threads.code === 0) {
-      const current = JSON.parse(threads.stdout)?.data?.repository?.pullRequest;
+      const response = JSON.parse(threads.stdout);
+      const current = response?.data?.repository?.pullRequest;
+      if (labels && response.errors === undefined) labels.labels = parseIssueLabels(response?.data?.repository?.issue, labels.issue) ?? null;
       const nodes = current?.reviewThreads?.nodes;
       // Paginated or malformed thread data is unknown, never a clean review.
       if (current?.headRefOid === p.headRefOid && current?.reviewThreads?.pageInfo?.hasNextPage === false && Array.isArray(nodes) && nodes.every(n => typeof n?.isResolved === "boolean")) p.unresolvedThreads = nodes.filter(n => !n.isResolved).length;
       else if (current?.headRefOid && current.headRefOid !== p.headRefOid) return undefined;
     }
-    return parsePrEvidence(p);
+    return { ...parsePrEvidence(p), ...(labels ? { issueLabels: labels } : {}) };
   } catch { return undefined; }
 }
 
@@ -434,13 +485,15 @@ export async function readReviewReadiness(receipt: SdlcReceipt, expected: string
       if (thread?.isResolved !== false) { blockers.push("bot review thread evidence unavailable"); continue; }
       const comments = thread?.comments;
       if (comments?.pageInfo?.hasNextPage !== false || !Array.isArray(comments.nodes) || comments.nodes.length > 100
-        || comments.nodes.some((comment: { author?: { __typename?: string }; createdAt?: string }) => !["Bot", "User"].includes(comment?.author?.__typename ?? "") || !Number.isFinite(Date.parse(comment.createdAt ?? "")))) {
+        || comments.nodes.some((comment: { createdAt?: string }) => !Number.isFinite(Date.parse(comment?.createdAt ?? "")))) {
         blockers.push("bot review thread evidence unavailable"); continue;
       }
+      // #230 item 3: only a `User` comment answers. Every other or missing author kind (Bot, null, Organization, Mannequin,
+      // EnterpriseUserAccount, a kind GitHub adds later) is a pending bot comment, so an unresolved thread settles by
+      // resolution or a later User comment. No weaker than before, and still no body or login is read.
       let unanswered = false;
-      for (const comment of comments.nodes) {
-        if (comment.author.__typename === "Bot") unanswered = true;
-        else if (comment.author.__typename === "User") unanswered = false;
+      for (const comment of comments.nodes as { author?: { __typename?: string | null } | null }[]) {
+        unanswered = comment?.author?.__typename !== "User";
       }
       if (unanswered) blockers.push("bot review threads unanswered");
     }

package/src/hub/settings.ts

@@ -1,3 +1,4 @@
+import { ACTION_CLASSES } from "./action-class.ts";
 import { definitionOf, type KindMap, type ProjectAdapterCatalog, ADAPTERS, PLANNER_PEERS, SUPPORTED_PEERS, START_MODE_PEERS } from "../adapters/registry.ts";
 import { createHash } from "node:crypto";
 import { types } from "node:util";
@@ -59,6 +60,8 @@ export const SETTINGS: readonly SettingDef[] = [
   ...SETTING_PEERS.map((peer): SettingDef => ({ key: `catalog_roles.${peer}`, group: "Roles", label: `${peer}: catalog guidance`, type: "roles", store: "config", applies: "next use", risk: "safe", path: ["catalog_roles", peer] })),
   { key: "scoped_grants.protect_instructions", group: "Permissions", label: "Ask before writing instruction files", type: "boolean", store: "config", applies: "live", risk: "raises", floor: true, path: ["protect_instruction_files"] },
   ...SETTING_PEERS.map((peer): SettingDef => ({ key: `roster.${peer}`, group: "Roster", label: `${peer}: participates`, type: "boolean", store: "config", applies: "live", risk: "raises", floor: false, path: ["roster", peer] })),
+  { key: "action_policy.enabled", group: "Permissions", label: "Always-ask action policy", type: "boolean", store: "config", applies: "live", risk: "raises", floor: true, path: ["action_policy", "enabled"] },
+  ...ACTION_CLASSES.map((kind): SettingDef => ({ key: `action_policy.budgets.${kind}`, group: "Permissions", label: `${kind}: approved session budget`, type: "integer", min: 0, max: 1000, store: "config", applies: "live", risk: "raises", floor: 0, path: ["action_policy", "budgets", kind] })),
   ...SETTING_PEERS.filter(peer => !definitionOf(peer)?.permission.unmanaged).map((peer): SettingDef => ({ key: `permission.${peer}`, group: "Permissions", label: `${peer}: mode now`, type: "enum", values: PERMISSION_MODES, store: "runtime", applies: "live", risk: "raises", floor: "ask", path: [peer] })),
   ...SETTING_PEERS.filter(peer => !definitionOf(peer)?.permission.unmanaged).map((peer): SettingDef => ({ key: `permission_modes.${peer}`, group: "Permissions", label: `${peer}: mode at next peer start`, type: "enum", values: PERMISSION_MODES, store: "config", applies: "next use", risk: "raises", floor: "ask", path: ["permission_modes", peer] })),
   ...START_MODE_PEERS.map((peer): SettingDef => ({ key: `peers.${peer}.start_mode`, group: "Start", label: `${peer}: start mode (tui unless set)`, type: "enum", values: START_MODES, store: "config", applies: "next use", risk: "raises", floor: "tui", path: ["peers", peer, "start_mode"] })),
@@ -75,7 +78,7 @@ export const SETTINGS: readonly SettingDef[] = [
  * Never editable from settings, whatever the session: these choose what the hub executes or where secrets and task
  * text go. A key equal to an entry, or below it, is refused by name.
  */
-export const NEVER_EDITABLE = ["kimi_cmd", "qwen_cmd", "jcode_cmd", "jcode_home", "jcode_provider_profile", "codex_bin", "pi.cmd", "checks", "mlx", "omniroute", "memory.worker_url", "local.read_allow", "local.bash_network", "local.network_allow", "bench.enabled", "terminal", "instances", "adapters"] as const;
+export const NEVER_EDITABLE = ["kimi_cmd", "qwen_cmd", "jcode_cmd", "jcode_home", "jcode_provider_profile", "codex_bin", "pi.cmd", "checks", "mlx", "omniroute", "memory.worker_url", "local.read_allow", "local.bash_network", "local.network_allow", "bench.enabled", "terminal", "instances", "adapters", "adapter_modules"] as const;
 
 /** Derive project-bound rows from the same builtin templates used by lookup, without registering aliases globally. */
 export function projectSettings(instances?: KindMap, adapterCatalog?: ProjectAdapterCatalog): readonly SettingDef[] {
@@ -384,6 +387,10 @@ export function undoSetting(cwd: string, stateDir: string, validate: (scratch: s
 export function storedLocally(cwd: string, def: SettingDef): boolean {
   try { return valueAt(JSON.parse(readFileSync(join(cwd, ".agenthub", CONFIG_LOCAL), "utf8")), def.path) !== undefined; } catch { return false; }
 }
+/** What the shared `.agenthub/config.json` holds for the key, or undefined: a removal here only ever touches the machine-local file. */
+export function sharedValue(cwd: string, def: SettingDef): unknown {
+  try { return valueAt(JSON.parse(readFileSync(join(cwd, ".agenthub", "config.json"), "utf8")), def.path); } catch { return undefined; }
+}
 /**
  * For a config setting: the value the config files would hold for it after the pending undo (the previous version of
  * the machine-local file, else the shared file), or, with `inherit`, after the machine-local value is removed (the
@@ -466,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.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: "not enforced yet: adapter integration pending" } : 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") {
@@ -481,7 +488,7 @@ export function settingRows(input: {
     if (def.type === "roles" && input.roles) { const roles = input.roles(def.path[1]!); return { ...base, ...roles, fileValue: roles.pending !== undefined ? roles.pending : roles.value, file: CONFIG_LOCAL, source: valueAt(local, def.path) !== undefined ? CONFIG_LOCAL : valueAt(shared, def.path) !== undefined ? "config.json" : "profile/default", hint: "Guidance only; grants no tool or permission. At most two roles, applied at the next peer start." }; }
     const value = scalar(input.running(def.path));
     const stored = input.next ? scalar(input.next(def.path)) : value;
-    const source = valueAt(local, def.path) !== undefined ? CONFIG_LOCAL : valueAt(shared, def.path) !== undefined ? "config.json" : "default";
+    const source = valueAt(local, def.path) !== undefined ? CONFIG_LOCAL : !def.key.startsWith("action_policy.") && valueAt(shared, def.path) !== undefined ? "config.json" : "default";
     const dropped = ignoredLine(input.ignored, def);
     return { ...base, ...(def.values ? { values: def.values } : {}), file: CONFIG_LOCAL, value, fileValue: stored, source, ...(same(value, stored) ? {} : { pending: stored }),
       ...(!input.next ? { note: "the config files do not load; fix them in your editor" } : dropped ? { note: `the hub does not read this value: ${dropped}` } : {}) };

package/src/hub/snapshots.ts

@@ -20,19 +20,22 @@ import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
  * ponytail: the trees are unreferenced, so `git gc` may prune them after gc.pruneExpire (two weeks by default); undo
  * of an older turn says so. Refs under refs/agenthub/ would keep them, at the cost of showing up in the user's repo.
  */
-export interface SnapshotBudget { deadline: number; }
+/** `now` is a host-only clock (#661): a test holds it fixed so the budget never runs out whatever the runner's speed. Production leaves it unset (performance.now). */
+export interface SnapshotBudget { deadline: number; now?: () => number; }
+export const budgetNow = (budget: SnapshotBudget): number => budget.now ? budget.now() : performance.now();
 export class SnapshotBudgetExceeded extends Error {
   constructor() { super("snapshot burst budget exhausted; boundary evidence is unknown"); }
 }
-const git = (top: string | Repo, args: string[], env: Record<string, string> = {}, budget?: SnapshotBudget, maxBuffer?: number) => {
+const git = (top: string | Repo, args: string[], env: Record<string, string> = {}, budget?: SnapshotBudget, maxBuffer?: number, input?: string | Buffer) => {
   const argv = repoGitArgs(top, args);
-  const remaining = budget ? budget.deadline - performance.now() : SNAPSHOT_TIMEOUT_MS;
+  const remaining = budget ? budget.deadline - budgetNow(budget) : SNAPSHOT_TIMEOUT_MS;
   if (remaining <= 0) throw new SnapshotBudgetExceeded();
   const result = hubGitSync(argv, {
     encoding: "utf8", env: { ...repoGitEnv(top), ...env }, ...(maxBuffer === undefined ? {} : { maxBuffer }),
+    ...(input === undefined ? {} : { input }),
     timeout: Math.max(1, Math.min(SNAPSHOT_TIMEOUT_MS, Math.floor(remaining))),
   });
-  if (budget && (performance.now() >= budget.deadline || (result.error as NodeJS.ErrnoException | undefined)?.code === "ETIMEDOUT")) throw new SnapshotBudgetExceeded();
+  if (budget && (budgetNow(budget) >= budget.deadline || (result.error as NodeJS.ErrnoException | undefined)?.code === "ETIMEDOUT")) throw new SnapshotBudgetExceeded();
   return result;
 };
 const SNAPSHOT_TIMEOUT_MS = 10_000;
@@ -146,7 +149,7 @@ export function branchHeads(repo: Repo, budget?: SnapshotBudget): string | undef
   const result = git(repo, ["for-each-ref", "--sort=refname", "--format=%(refname) %(objectname)", "refs/heads/", "refs/remotes/"], {}, budget, 1024 * 1024);
   if (result.status !== 0 || result.error) return undefined;
   const digest = createHash("sha256").update(result.stdout).digest("hex");
-  if (budget && performance.now() >= budget.deadline) throw new SnapshotBudgetExceeded();
+  if (budget && budgetNow(budget) >= budget.deadline) throw new SnapshotBudgetExceeded();
   return digest;
 }
 
@@ -158,7 +161,7 @@ export function soleWorktree(repo: Repo, budget?: SnapshotBudget): boolean | und
   const registeredRoot = repo.shadow ? repo.dir : repo.top;
   let count = 0;
   for (const field of result.stdout.split("\0")) {
-    if (budget && performance.now() >= budget.deadline) throw new SnapshotBudgetExceeded();
+    if (budget && budgetNow(budget) >= budget.deadline) throw new SnapshotBudgetExceeded();
     if (!field.startsWith("worktree ")) continue;
     if (field.slice(9) !== registeredRoot || ++count > 1) return false;
   }
@@ -179,7 +182,7 @@ export interface HeadMoveCursor {
 const HEAD_LOG_TAIL_BYTES = 4096;
 const HEAD_LOG_MAX_APPEND_BYTES = 128 * 1024;
 const HEAD_LOG_MAX_MOVES = 64;
-const checkSnapshotBudget = (budget?: SnapshotBudget) => { if (budget && performance.now() >= budget.deadline) throw new SnapshotBudgetExceeded(); };
+const checkSnapshotBudget = (budget?: SnapshotBudget) => { if (budget && budgetNow(budget) >= budget.deadline) throw new SnapshotBudgetExceeded(); };
 const sameLogFile = (a: Stats, b: Stats) => a.dev === b.dev && a.ino === b.ino;
 function readHeadLog<T>(repo: Repo, budget: SnapshotBudget | undefined, read: (fd: number, stat: Stats) => T | undefined): T | undefined {
   let fd: number | undefined;
@@ -309,11 +312,81 @@ export function incomingHeadPaths(repo: Repo, start: HeadMoveCursor, end: HeadMo
   if (appended[appended.length - 1] !== 10) return undefined;
   const lines = appended.toString("utf8").slice(0, -1).split("\n");
   if (lines.length > HEAD_LOG_MAX_MOVES) return undefined;
+
+  const diffCache = new Map<string, string[] | undefined>();
+  const ancestorCache = new Map<string, boolean>();
+  const diffOf = (from: string, to: string): string[] | undefined => {
+    if (from === to) return [];
+    const key = `${from}..${to}`;
+    if (diffCache.has(key)) return diffCache.get(key);
+    const res = knownChangedPaths(repo, from, to, budget);
+    diffCache.set(key, res);
+    return res;
+  };
+  const isAncestor = (oldCommit: string, nextCommit: string): boolean => {
+    if (oldCommit === nextCommit) return true;
+    const key = `${oldCommit}..${nextCommit}`;
+    if (ancestorCache.has(key)) return ancestorCache.get(key)!;
+    const ancestor = git(repo, ["merge-base", "--is-ancestor", oldCommit, nextCommit], {}, budget);
+    const ok = ancestor.status === 0;
+    ancestorCache.set(key, ok);
+    return ok;
+  };
+
+  const parsedRows: Array<ReturnType<typeof headLogRow>> = [];
+  const batchCandidates = new Set<string>();
+  for (const line of lines) {
+    const row = headLogRow(line);
+    parsedRows.push(row);
+    if (!row) continue;
+    const separator = row.action.indexOf(": ");
+    const action = separator < 0 ? "" : row.action.slice(0, separator);
+    // #612: diff-tree --stdin compares a commit to its first parent. In git sequencer, only pick
+    // and initial/regular commits have row.old as the parent of row.next. Sequencer squash, fixup,
+    // reword and edit amend the commit, so row.next's parent is row.old's parent. Only batch rows
+    // where row.old is the parent (pick and commit); other rows are diffed individually.
+    const isPickOrCommit = /^.+ \(pick\)$/.test(action) || action === "commit";
+    if (isPickOrCommit && row.old !== row.next && !/^0+$/.test(row.old)) {
+      batchCandidates.add(row.next);
+    }
+  }
+
+  // Batch single-parent pick/commit diffs across the boundary to stay within burst budget (#612).
+  if (batchCandidates.size > 1) {
+    const commitList = [...batchCandidates];
+    const stdinInput = commitList.join("\n") + "\n";
+    const batchRes = git(repo, ["diff-tree", "--stdin", "--always", "-r", "--no-renames", "--raw", "-z", "--", scope(repo)], {}, budget, undefined, stdinInput);
+    if (batchRes.status === 0) {
+      const parts = batchRes.stdout.split("\0");
+      if (parts.length && parts[parts.length - 1] === "") parts.pop();
+      let i = 0;
+      while (i < parts.length) {
+        const commit = parts[i++];
+        if (!commit) continue;
+        const paths: string[] = [];
+        while (i < parts.length && parts[i]?.startsWith(":")) {
+          i++; // skip raw metadata: :oldmode newmode oldsha newsha status
+          if (i < parts.length && parts[i]) {
+            paths.push(parts[i++]!);
+          }
+        }
+        for (const r of parsedRows) {
+          if (r && r.next === commit && r.old !== r.next) {
+            const sep = r.action.indexOf(": ");
+            const act = sep < 0 ? "" : r.action.slice(0, sep);
+            if (/^.+ \(pick\)$/.test(act) || act === "commit") {
+              diffCache.set(`${r.old}..${r.next}`, [...paths]);
+            }
+          }
+        }
+      }
+    }
+  }
+
   const own = new Set<string>(), incoming = new Set<string>();
   let previous = start.head;
-  for (const line of lines) {
+  for (const row of parsedRows) {
     checkSnapshotBudget(budget);
-    const row = headLogRow(line);
     if (!row || (previous === null ? !/^0+$/.test(row.old) : row.old !== previous)) return undefined;
     // Git preserves the invoking command in sequencer actions (for example pull -q --rebase (pick)).
     // Classify the native phase before considering ordinary command-shaped incoming actions.
@@ -326,10 +399,11 @@ export function incomingHeadPaths(repo: Repo, start: HeadMoveCursor, end: HeadMo
     const incomingCommand = !action.includes("(") && /^(?:merge|pull)(?: [^:]+)?$/.test(action) && !!detail;
     let incomingMove = !ownMove && (incomingStart || incomingCommand || action === "checkout" && /^moving from .+ to .+$/.test(detail));
     if (action === "reset" && /^moving to .+/.test(detail)) {
-      // Policy: a positively fast-forward reset is incoming, even when its target contains the peer's own
-      // descendant commit; reflog ancestry alone cannot distinguish that intent. Rewinds/unknown resets refuse.
-      const ancestor = git(repo, ["merge-base", "--is-ancestor", row.old, row.next], {}, budget);
-      if (ancestor.status !== 0) return undefined;
+      // Policy: a positively fast-forward reset stays incoming, even when its target contains the peer's own
+      // descendant commit made in another worktree during the turn. Reflog ancestry alone cannot distinguish
+      // local worktree coordination from external branch fast-forwards; classifying it as incoming safely
+      // excludes external commits from local turn attribution and undo. Rewinds/unknown resets refuse.
+      if (!isAncestor(row.old, row.next)) return undefined;
       incomingMove = true;
     }
     if (!ownMove && !incomingMove) return undefined;
@@ -337,7 +411,19 @@ export function incomingHeadPaths(repo: Repo, start: HeadMoveCursor, end: HeadMo
     if (/^0+$/.test(row.old)) {
       const root = git(repo, ["diff-tree", "--root", "--no-commit-id", "-r", "--no-renames", "--name-only", "-z", row.next, "--", scope(repo)], {}, budget);
       paths = root.status === 0 ? root.stdout.split("\0").filter(Boolean) : undefined;
-    } else paths = knownChangedPaths(repo, row.old, row.next, budget);
+    } else if (incomingStart) {
+      // #612: take incoming start paths as merge-base(old, upstream)..upstream instead of old..upstream,
+      // so the peer's replayed own commits do not overlap and only true upstream paths are excluded.
+      // Any remaining ambiguity (no merge base, criss-cross multiple merge bases) stays unknown.
+      const mb = git(repo, ["merge-base", "--all", row.old, row.next], {}, budget);
+      if (mb.status !== 0) return undefined;
+      const bases = mb.stdout.trim().split("\n").map(s => s.trim()).filter(Boolean);
+      const base = bases[0];
+      if (bases.length !== 1 || !base || !/^[0-9a-f]{40,64}$/.test(base)) return undefined;
+      paths = base === row.next ? [] : diffOf(base, row.next);
+    } else {
+      paths = diffOf(row.old, row.next);
+    }
     if (!paths) return undefined;
     for (const path of paths) { checkSnapshotBudget(budget); (ownMove ? own : incoming).add(path); }
     previous = row.next;
@@ -392,6 +478,7 @@ export function snapshot(repo: Repo, budget?: SnapshotBudget): string | undefine
 
 /** Project paths (relative to the top level) that differ between two trees. */
 export function knownChangedPaths(repo: Repo, from: string, to: string, budget?: SnapshotBudget): string[] | undefined {
+  if (from === to) return [];
   const r = git(repo, ["diff-tree", "-r", "--no-renames", "--name-only", "-z", from, to, "--", scope(repo)], {}, budget);
   return r.status === 0 ? r.stdout.split("\0").filter(Boolean) : undefined;
 }

package/src/hub/symbol-normalizer.ts

@@ -0,0 +1,26 @@
+/**
+ * Strip parentheses and arguments from a plan symbol name.
+ * Section and source keys (`section ...`, `source ...`) are preserved unchanged.
+ */
+export function normalizePlanSymbol(name: string): string {
+  if (typeof name !== "string") return "";
+  if (name.startsWith("section ") || name.startsWith("source ")) return name;
+  return name.replace(/\s*\(.*$/, "").trim();
+}
+
+/**
+ * Compare two plan symbols for overlap (#682 phase 1b).
+ * - Section and source keys must match exactly.
+ * - Otherwise, names are compared by their last segment; when both names are qualified
+ *   (e.g. `A.run` vs `B.run`), the qualifiers must match as well.
+ */
+export function symbolsOverlap(left: string, right: string): boolean {
+  if (typeof left !== "string" || typeof right !== "string") return false;
+  if (left.startsWith("section ") || left.startsWith("source ") || right.startsWith("section ") || right.startsWith("source ")) {
+    return left === right;
+  }
+  const a = normalizePlanSymbol(left);
+  const b = normalizePlanSymbol(right);
+  if (!a || !b) return false;
+  return a.includes(".") && b.includes(".") ? a === b : a.split(".").at(-1) === b.split(".").at(-1);
+}

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

@@ -0,0 +1,90 @@
+import type { ReviewBrief } from "./review-brief.ts";
+
+export interface TaskCodeSymbol { id: string; path: string; name: string; kind: string }
+export interface TaskCodeSymbols {
+  head: string; mergeBase: string; repositoryKey: string;
+  state: "known" | "unknown"; complete: boolean; countsFloor: true; symbols: TaskCodeSymbol[];
+}
+export const HOST_CODE_SYMBOLS = Symbol("host task code symbols");
+const sha = (value: unknown): value is string => typeof value === "string" && /^[a-f0-9]{40}$/.test(value);
+const text = (value: unknown): value is string => typeof value === "string" && value.length > 0 && Buffer.byteLength(value) <= 512 && !/[\p{Cc}\p{Cf}]/u.test(value);
+const path = (value: unknown): value is string => text(value) && !value.startsWith("/") && !value.includes("\\") && !value.split("/").some(part => !part || part === "." || part === ".." || part.toLowerCase() === ".git");
+const object = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === "object" && !Array.isArray(value) && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+const bounded = (value: unknown) => Buffer.byteLength(JSON.stringify(value)) <= 64 * 1024;
+
+/** Stored observations are host-derived metadata, not code or caller-provided spans. */
+export function parseTaskCodeSymbols(value: unknown): TaskCodeSymbols | undefined {
+  try {
+    if (!object(value) || !sha(value.head) || !sha(value.mergeBase) || !text(value.repositoryKey)
+      || (value.state !== "known" && value.state !== "unknown") || typeof value.complete !== "boolean" || value.countsFloor !== true
+      || !Array.isArray(value.symbols) || value.symbols.length > 500 || !bounded(value)) return;
+    const symbols: TaskCodeSymbol[] = [], ids = new Set<string>();
+    for (const item of value.symbols) {
+      if (!object(item) || !text(item.id) || !path(item.path) || !text(item.name) || !text(item.kind)
+        || !/^[a-z_]+$/.test(item.kind) || item.id !== `symbol:${item.name}@${item.path}` || ids.has(item.id)) return;
+      ids.add(item.id); symbols.push({ id: item.id, path: item.path, name: item.name, kind: item.kind });
+    }
+    if (value.state === "unknown" && (value.complete || symbols.length)) return;
+    return { head: value.head, mergeBase: value.mergeBase, repositoryKey: value.repositoryKey, state: value.state as "known" | "unknown", complete: value.complete, countsFloor: true, symbols };
+  } catch { return; }
+}
+
+/** Caller must certify that the earlier preparation did not filter or truncate any symbols. */
+export function buildTaskCodeSymbols(brief: ReviewBrief | undefined, repositoryKey: string, screen: (text: string) => boolean, privateTask = false): TaskCodeSymbols | undefined {
+  if (privateTask || !brief || !sha(brief.head) || !sha(brief.mergeBase) || !text(repositoryKey)) return;
+  const unknown: TaskCodeSymbols = { head: brief.head, mergeBase: brief.mergeBase, repositoryKey, state: "unknown", complete: false, countsFloor: true, symbols: [] };
+  try {
+    if (brief.symbols?.state !== "known") return unknown;
+    if (!Array.isArray(brief.symbols.files) || brief.symbols.files.length > 500 || !Array.isArray(brief.reviewable) || brief.reviewable.length > 500) return unknown;
+    const reviewable = new Set(brief.reviewable.map(file => file.path)), files = new Set<string>();
+    if ([...reviewable].some(value => !path(value))) return unknown;
+    let complete = brief.symbols.complete === true && brief.withheld === 0 && brief.unlisted.length === 0;
+    const symbols: TaskCodeSymbol[] = [], ids = new Set<string>();
+    let observed = 0;
+    for (const file of brief.symbols.files) {
+      if (!path(file.path) || !reviewable.has(file.path) || files.has(file.path) || !Array.isArray(file.symbols)) return unknown;
+      files.add(file.path);
+      for (const symbol of file.symbols) {
+        if (++observed > 500) return unknown;
+        const id = `symbol:${symbol.name}@${file.path}`;
+        if (symbol.ambiguous || symbol.path !== file.path || !text(symbol.name) || !text(symbol.kind) || !/^[a-z_]+$/.test(symbol.kind)
+          || !text(id) || !screen(file.path) || !screen(symbol.name) || !screen(symbol.kind) || !screen(id)) { complete = false; continue; }
+        if (ids.has(id)) { complete = false; continue; }
+        ids.add(id); symbols.push({ id, path: file.path, name: symbol.name, kind: symbol.kind });
+      }
+    }
+    if (files.size !== reviewable.size) complete = false;
+    const result: TaskCodeSymbols = { ...unknown, state: "known", complete, symbols };
+    return bounded(result) ? result : unknown;
+  } catch { return unknown; }
+}
+
+/** Re-screen every public read; repository place keys are internal and never exported. */
+export function publicTaskCodeSymbols(receipt: TaskCodeSymbols | undefined, head: string | undefined, repositoryKey: string, screen: (text: string) => boolean, privateTask = false): Omit<TaskCodeSymbols, "repositoryKey"> | undefined {
+  const valid = parseTaskCodeSymbols(receipt);
+  if (privateTask || !valid || !sha(head) || valid.head !== head || valid.repositoryKey !== repositoryKey) return;
+  let complete = valid.complete;
+  const symbols = valid.symbols.filter(symbol => {
+    try { if ([symbol.id, symbol.path, symbol.name, symbol.kind].every(value => screen(value))) return true; } catch { /* failed policy is withheld */ }
+    complete = false; return false;
+  });
+  const { repositoryKey: _repositoryKey, ...result } = valid;
+  return { ...result, complete, symbols };
+}
+
+/** Advisory observed disjointness only. Floors/deleted-symbol limitations never justify a gate or lost notice. */
+export function taskCodeSymbolsDisjoint(left: TaskCodeSymbols | undefined, right: TaskCodeSymbols | undefined, leftHead: string | undefined, rightHead: string | undefined, repositoryKey: string, sharedPaths: readonly string[], privateData = false, screen?: (text: string) => boolean): boolean {
+  const current = (receipt: TaskCodeSymbols | undefined, head: string | undefined) => {
+    if (!screen) return parseTaskCodeSymbols(receipt);
+    const projected = publicTaskCodeSymbols(receipt, head, repositoryKey, screen, privateData);
+    return projected ? { ...projected, repositoryKey } : undefined;
+  };
+  const a = current(left, leftHead), b = current(right, rightHead);
+  if (privateData || !a || !b || !sha(leftHead) || !sha(rightHead) || a.head !== leftHead || b.head !== rightHead
+    || a.repositoryKey !== repositoryKey || b.repositoryKey !== repositoryKey || a.state !== "known" || b.state !== "known" || !a.complete || !b.complete
+    || !sharedPaths.length || sharedPaths.length > 500 || sharedPaths.some(value => !path(value))) return false;
+  return sharedPaths.every(file => {
+    const xs = a.symbols.filter(s => s.path === file), ys = b.symbols.filter(s => s.path === file);
+    return xs.length > 0 && ys.length > 0 && !xs.some(x => ys.some(y => x.id === y.id || (!x.name.includes(".") && y.name.endsWith(`.${x.name}`)) || (!y.name.includes(".") && x.name.endsWith(`.${y.name}`))));
+  });
+}

package/src/hub/task-sweep.ts

@@ -1,4 +1,5 @@
 import type { Task } from "./board.ts";
+import { normalizePlanSymbol, symbolsOverlap } from "./symbol-normalizer.ts";
 
 export type SweepKind = "unaccepted-assignment" | "idle-owner" | "review-pending" | "ready-unassigned";
 export interface SweepRecord {
@@ -187,7 +188,7 @@ export function plannerGrooming(tasks: readonly Task[], options: PlannerGrooming
       if (!reviewed && !accepted) unknown.add(task.id);
     }
   }
-  const places = (task: Task) => ({ paths: new Set([...(task.refs.paths ?? []), ...(task.plan?.paths ?? [])].map(groomingPath).filter((path): path is string => path !== undefined)), symbols: new Set(task.plan?.symbols ?? []) });
+  const places = (task: Task) => ({ paths: new Set([...(task.refs.paths ?? []), ...(task.plan?.paths ?? [])].map(groomingPath).filter((path): path is string => path !== undefined)), symbols: new Set((task.plan?.symbols ?? []).map(normalizePlanSymbol)) });
   const open = scoped.filter(task => task.state !== "cancelled");
   const positions = new Map(open.map(task => [task.id, places(task)]));
   const overlaps = (left: string, right: string): boolean => left === right || left === "." || right === "."
@@ -196,7 +197,7 @@ export function plannerGrooming(tasks: readonly Task[], options: PlannerGrooming
     const task = open[left]!;
     if (repositories.get(task.id) !== repositories.get(right.id)) continue;
     const a = positions.get(task.id)!, b = positions.get(right.id)!;
-    if ([...a.paths].some(path => [...b.paths].some(other => overlaps(path, other))) || [...a.symbols].some(symbol => b.symbols.has(symbol))) add({ kind: "overlap", task: task.id, related: [right.id] });
+    if ([...a.paths].some(path => [...b.paths].some(other => overlaps(path, other))) || [...a.symbols].some(symbol => [...b.symbols].some(other => symbolsOverlap(symbol, other)))) add({ kind: "overlap", task: task.id, related: [right.id] });
     if ([...issueIds.get(task.id)!].some(issue => issueIds.get(right.id)!.has(issue))) add({ kind: "duplicate", task: task.id, related: [right.id] });
   }
   for (const blocker of (options.blockers ?? []).slice(0, GROOMING_TASK_LIMIT)) {