@staix/agent-hub 0.15.0 → 0.16.0

package/src/hub/envelope.ts

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

package/src/hub/events.ts

@@ -37,8 +37,8 @@ export type HubEvent =
   | { type: "hub_start"; instance: string }
   /** #248: the add-ons a peer works with, names and versions from a closed list, at each attach. */
   | { type: "tooling"; peer: string; addons: import("./tooling.ts").Addon[] }
-  /** #258: a task brief handed to its owner: how many hub-memory items (and fails among them) and claude-mem items, never their text. */
-  | { type: "memory_brief"; peer: string; task: number; native: number; fails: number; claudeMem: number }
+  /** #258: a task brief handed to its owner: how many hub-memory items (and fails among them) and supplemental items (legacy claudeMem field), never their text. New local-library records identify source amem. */
+  | { type: "memory_brief"; source?: "amem"; peer: string; task: number; native: number; fails: number; claudeMem: number }
   | { type: "split"; task: number; where?: "routing" | "cohort"; verdict: "split" | "single" | "unknown"; single?: string; splitS?: number; singleS?: number; reason?: string; trace?: string[] }
   | { type: "state"; peer: string; state: string }
   | { type: "turn_start"; peer: string; turn: string }

package/src/hub/hub-tools.ts

@@ -90,7 +90,7 @@ export const TASK_TOOLS: HubTool[] = [
   tool("hub_check_cancel", "Cancel your task-bound isolated check; only its owner or the person may cancel.", { run: str }, ["run"]),
   tool("hub_delivery_retry", "Request one redelivery of your own needs_review delivery. An earlier attempt may have effects: inspect those effects before acting. Refuses another peer's row or any lineage already explicitly retried; a repeated uncertain row needs the person. Never completes/discards a delivery or changes task state.", { delivery_id: { type: "string", minLength: 1, maxLength: 256 } }, ["delivery_id"]),
   tool("hub_backlog_list", "Read public backlog cards with planning revisions. Configured planners only; PII remains a stub.", {}),
-  tool("hub_backlog_plan", "Plan an unpinned backlog item outside frozen releases with the revision you read and a bounded reason. A person's rank is retained. Actual dates cannot be set.", { id, revision: { type: "integer", minimum: 0 }, reason: { type: "string", maxLength: 1000 }, fields: { type: "object", properties: { rank: { type: ["integer", "null"], minimum: 0 }, priority: { type: ["integer", "null"], minimum: 0, maximum: 3 }, release: { type: ["integer", "null"], minimum: 1 }, plannedStart: { type: ["integer", "null"], minimum: 1 }, due: { type: ["integer", "null"], minimum: 1 }, deps: { type: "array", maxItems: 64, uniqueItems: true, items: { type: "integer", minimum: 1 } }, reserved: { type: ["string", "null"], minLength: 1, maxLength: 32 } }, additionalProperties: false } }, ["id", "revision", "reason", "fields"]),
+  tool("hub_backlog_plan", "Plan an unpinned backlog item outside frozen releases with the revision you read and a bounded reason. Omit fields or give {} for a note-only revision. fields.sdlc accepts only repo/issue identity on unstarted backlog work; relinking clears old spec acceptance. A person's rank is retained. Actual dates cannot be set.", { id, revision: { type: "integer", minimum: 0 }, reason: { type: "string", maxLength: 1000 }, fields: { type: "object", properties: { sdlc: { type: "object", minProperties: 1, properties: { repo: { type: ["string", "null"], maxLength: 400 }, issue: { type: ["integer", "null"], minimum: 1 } }, additionalProperties: false }, rank: { type: ["integer", "null"], minimum: 0 }, priority: { type: ["integer", "null"], minimum: 0, maximum: 3 }, release: { type: ["integer", "null"], minimum: 1 }, plannedStart: { type: ["integer", "null"], minimum: 1 }, due: { type: ["integer", "null"], minimum: 1 }, deps: { type: "array", maxItems: 64, uniqueItems: true, items: { type: "integer", minimum: 1 } }, reserved: { type: ["string", "null"], minLength: 1, maxLength: 32 } }, additionalProperties: false } }, ["id", "revision", "reason"]),
   tool("hub_backlog_pull", "Reserve a WIP slot and pull ready unpinned backlog work into To Do at its current revision. Preserves person order/reservations and frozen scope; pending unowned work can be undone with hub_backlog_undo.", { id, revision: { type: "integer", minimum: 0 }, reason: { type: "string", minLength: 1, maxLength: 1000 } }, ["id", "revision", "reason"]),
   tool("hub_backlog_split", "Split unstarted backlog work into two to eight staged parts. The original card retains integration/acceptance and depends on the children. Use after for existing prerequisite ids and afterParts for earlier zero-based part indexes. Latest unused unchanged children can be undone with hub_backlog_undo.", { id, revision: { type: "integer", minimum: 0 }, reason: { type: "string", minLength: 1, maxLength: 1000 }, parts: { type: "array", minItems: 2, maxItems: 8, items: { type: "object", properties: { title: { type: "string", minLength: 1, maxLength: 300 }, detail: { type: "string", maxLength: 8000 }, class: str, refs, plan, after: { type: "array", maxItems: 64, uniqueItems: true, items: { type: "integer", minimum: 1 } }, afterParts: { type: "array", maxItems: 8, uniqueItems: true, items: { type: "integer", minimum: 0 } } }, required: ["title"], additionalProperties: false } } }, ["id", "revision", "reason", "parts"]),
   tool("hub_backlog_undo", "Undo your latest planning change at its current revision. Refuses intervening changes and another actor's edit.", { id, revision: { type: "integer", minimum: 1 } }, ["id", "revision"]),
@@ -112,9 +112,9 @@ export const TASK_TOOLS: HubTool[] = [
   tool("hub_checkpoint", "Answer a checkpoint request from the hub (quota or context window pressure): what you were doing, what is half done, what whoever continues must know. Write the same to .agenthub/checkpoint.md first if you can.", { summary: str, request_id: { type: "string", description: "The request id supplied by a context checkpoint request; required for context checkpoints" } }, ["summary"]),
   tool("hub_memory_search", "Search daemon-scoped visible memory, fails first. Query <=200 UTF-8 bytes; default 8, max 20 lines; whole output <=4 KB. Incomplete excerpts are marked. No project argument.", { query: { type: "string", maxLength: 200, description: "At most 200 UTF-8 bytes, enforced by the daemon" }, limit: { type: "integer", minimum: 1, maximum: 20 } }, ["query"]),
   tool("hub_memory_show", "Read up to 8 visible memory ids or unique prefixes (6..64 UTF-8 bytes each). Original ids redirect; unavailable ids share one refusal. Whole output <=8 KB.", { ids: { type: "array", minItems: 1, maxItems: 8, items: { type: "string", minLength: 6, maxLength: 64, description: "6 to 64 UTF-8 bytes" } } }, ["ids"]),
-  tool("hub_memory_graph", "Read screened memory neighbourhoods, fails first. Up to 8 starts (<=200 UTF-8 bytes each), 1 or 2 hops; default 60/max 120 nodes, max 240 edges, whole output <=6 KB. No project argument.", { starts: { type: "array", minItems: 1, maxItems: 8, items: { type: "string", minLength: 1, maxLength: 200, description: "At most 200 UTF-8 bytes" } }, hops: { type: "integer", enum: [1, 2] }, limit: { type: "integer", minimum: 1, maximum: 120 } }, ["starts"]),
+  tool("hub_memory_graph", "Read screened memory neighbourhoods, fails first. Symbol starts also include optional current-head one-hop code neighbours as derived SHA-stamped edges; unknown coverage is explicit. Up to 8 starts (<=200 UTF-8 bytes each), 1 or 2 hops; default 60/max 120 nodes, max 240 edges, whole output <=6 KB. No project argument.", { starts: { type: "array", minItems: 1, maxItems: 8, items: { type: "string", minLength: 1, maxLength: 200, description: "At most 200 UTF-8 bytes" } }, hops: { type: "integer", enum: [1, 2] }, limit: { type: "integer", minimum: 1, maximum: 120 } }, ["starts"]),
   tool("hub_memory_correct", "Propose a correction to a visible memory entry. This creates a machine-local candidate only; a person accepts or rejects it with amem review. It never edits a note. id is an exact id or unique visible prefix; text and reason must each fit 4000 UTF-8 bytes.", { id: str, text: str, reason: str }, ["id", "text", "reason"]),
-  tool("hub_remember", "Save a decision, finding, contract or fail to the memory all agents share (the hub's memory and claude-mem); the other agents also get it with their next message. A fail is an approach you tried that does not work, and why: the most useful note, it stops the others spending their quota on it. Do not retry what a fail note rules out without new evidence. Conclusions worth recalling, not chatter. For kind fail, optional approach, symptom, cause, evidence and retry_when strings compose fixed labeled text; text may be omitted when structured fields are supplied. The complete text must fit 4000 UTF-8 bytes and is refused, never truncated, when oversized. A note on an open task is short-term until the task is approved, when its decisions, contracts and fails become long-term; horizon long keeps it now, scope shared lets the person's other projects find it.", { text: str, approach: str, symptom: str, cause: str, evidence: str, retry_when: str, title: str, kind: { type: "string", enum: [...NOTE_KINDS] }, task: id, horizon: { type: "string", enum: ["short", "long"] }, scope: { type: "string", enum: ["project", "shared"] } }),
+  tool("hub_remember", "Save a decision, finding, contract or fail to the memory all agents share (the hub's amem curated store); the other agents also get it with their next message. A fail is an approach you tried that does not work, and why: the most useful note, it stops the others spending their quota on it. Do not retry what a fail note rules out without new evidence. Conclusions worth recalling, not chatter. For kind fail, optional approach, symptom, cause, evidence and retry_when strings compose fixed labeled text; text may be omitted when structured fields are supplied. The complete text must fit 4000 UTF-8 bytes and is refused, never truncated, when oversized. A note on an open task is short-term until the task is approved, when its decisions, contracts and fails become long-term; horizon long keeps it now, scope shared lets the person's other projects find it.", { text: str, approach: str, symptom: str, cause: str, evidence: str, retry_when: str, title: str, kind: { type: "string", enum: [...NOTE_KINDS] }, task: id, horizon: { type: "string", enum: ["short", "long"] }, scope: { type: "string", enum: ["project", "shared"] } }),
 ];
 
 export const PLANNER_REVIEW_TOOLS: HubTool[] = [

package/src/hub/kimi-usage.ts

@@ -52,6 +52,18 @@ export class KimiUsage {
     }
   }
 
+  /**
+   * What the count can say now, for `ahub doctor`, the notes under `ahub budget` and the dashboard. Carries a reason code at most (never a path, id or text from the log).
+   * `off`: no ceiling, so no window. `unreadable`: a log read unknown or was tainted. `counting`: a clean log is bound. `waiting`: no Kimi session is bound yet.
+   */
+  status(): { state: "off" | "waiting" | "counting" } | { state: "unreadable"; reason: string } {
+    if (!this.ports.ceiling()) return { state: "off" };
+    for (const state of this.bound.values()) if (state.unknown) return { state: "unreadable", reason: state.unknown };
+    const now = this.ports.now();
+    for (const until of this.taintedUntil.values()) if (now < until) return { state: "unreadable", reason: "log changed since it was counted" };
+    return { state: this.bound.size ? "counting" : "waiting" };
+  }
+
   /** The peer went offline: its log is no longer read, so an unreadable state of it must not hold the other peers' figure unknown. */
   drop(peer: string): void { this.bound.delete(peer); }
 

package/src/hub/lifecycle.ts

@@ -84,6 +84,9 @@ async function available(base: number): Promise<boolean> {
   }
 }
 
+/** The signals the project daemon stops on (see `runProjectDaemon`). */
+export const STOP_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP", "SIGQUIT"] as const;
+
 /** Called only in the detached daemon process. A competing starter exits without touching state. */
 export async function runProjectDaemon(project: Project, unattended = false): Promise<void> {
   assertLifecycleAvailable();
@@ -92,8 +95,8 @@ export async function runProjectDaemon(project: Project, unattended = false): Pr
   let claimed = false;
   let daemon: Awaited<ReturnType<typeof startDaemon>> | undefined;
   // ponytail: shutdown is bounded as a whole, not per peer; a peer whose stop never settles
-  // escapes only through this process-level deadline (issue #56). 15 s leaves the claude-mem
-  // session-end work awaited in stop() its chance. Upgrade path: per-peer stop deadlines.
+  // escapes only through this process-level deadline (issue #56). 15 s leaves the amem
+  // SessionEnd capture row each peer's stop() awaits (`Capture.end`) its chance. Upgrade path: per-peer stop deadlines.
   const SHUTDOWN_DEADLINE_MS = 15_000;
   let forcedExit: ReturnType<typeof setTimeout> | undefined;
   const onShutdownStart = () => {
@@ -128,10 +131,12 @@ export async function runProjectDaemon(project: Project, unattended = false): Pr
     }
     if (!daemon) throw new Error("no free hub port range after 100 attempts");
     const stop = () => { void daemon!.stop().catch((error) => console.error(`shutdown incomplete: ${(error as Error).message}`)); };
-    process.on("SIGINT", stop);
-    process.on("SIGTERM", stop);
+    // Every signal the hub exits on goes through stop(), never the default action: a default action ends the process with no `exit` event and no stop(), so memory sync's git (which
+    // agent-mem 0.7.0 runs in its own process group, stopped only through the daemon's `syncStop` signal) would outlive the hub holding the memory repository. SIGHUP is a closing
+    // terminal, SIGQUIT is Ctrl-\; a handler also keeps SIGQUIT from its default core dump (agent-mem #435: Bun honours it, and a core file of the whole image delays the exit).
+    for (const name of STOP_SIGNALS) process.on(name, stop);
     try { await daemon.stopped; }
-    finally { if (forcedExit) clearTimeout(forcedExit); process.off("SIGINT", stop); process.off("SIGTERM", stop); }
+    finally { if (forcedExit) clearTimeout(forcedExit); for (const name of STOP_SIGNALS) process.off(name, stop); }
   } finally {
     if (claimed) registry.release(project.id, instanceId);
     registry.close();

package/src/hub/memory-code-head.ts

@@ -0,0 +1,44 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync } from "node:fs";
+import { join } from "node:path";
+import { hubGitSync } from "./git.ts";
+import { realPath } from "./project.ts";
+export interface MemoryCodeHead { head: string; current(): string | undefined }
+const SHA = /^[a-f0-9]{40}$/;
+function text(file: string, cap: number): string | null {
+  let fd: number;
+  try { fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return null; throw error; }
+  try {
+    const before = fstatSync(fd); if (!before.isFile() || before.size > cap) throw Error();
+    const bytes = Buffer.alloc(cap + 1), count = readSync(fd, bytes, 0, bytes.length, 0), after = fstatSync(fd), named = lstatSync(file);
+    if (count !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs || named.ino !== before.ino || named.dev !== before.dev || named.isSymbolicLink()) throw Error();
+    return bytes.subarray(0, count).toString("utf8").trim();
+  } finally { closeSync(fd); }
+}
+/** One hardened Git probe per admitted derive; cache validation reads bounded Git-owned HEAD/ref files, never launches Git. */
+export function readMemoryCodeHead(repo: string): MemoryCodeHead | undefined {
+  try {
+    const found = hubGitSync(["-C", repo, "rev-parse", "--path-format=absolute", "--git-dir", "--git-common-dir", "HEAD"], { encoding: "utf8", timeout: 250 });
+    const lines = found.stdout.trim().split("\n");
+    if (found.status !== 0 || lines.length !== 3 || !SHA.test(lines[2]!)) return;
+    const git = realPath(lines[0]!), common = realPath(lines[1]!), marker = join(repo, ".git"), markerStat = lstatSync(marker);
+    if (markerStat.isSymbolicLink()) return;
+    const binding = markerStat.isDirectory() ? `${markerStat.dev}:${markerStat.ino}` : text(marker, 4096);
+    const headFile = join(git, "HEAD"), initial = text(headFile, 1024); if (!initial) return;
+    const branch = initial.startsWith("ref: ") ? initial.slice(5) : undefined;
+    if (branch && (!branch.startsWith("refs/heads/") || /[\\\p{Cc}\p{Cf}]/u.test(branch) || branch.split("/").some(part => !part || part === "." || part === ".."))) return;
+    const current = (): string | undefined => {
+      try {
+        const now = lstatSync(marker); if (now.isSymbolicLink() || (now.isDirectory() ? `${now.dev}:${now.ino}` : text(marker, 4096)) !== binding || text(headFile, 1024) !== initial) return;
+        if (!branch) return SHA.test(initial) ? initial : undefined;
+        const loose = text(join(common, branch), 128);
+        if (loose !== null) return SHA.test(loose) ? loose : undefined;
+        // ponytail: very large packed-ref inventories remain unknown; use a bounded native ref service if this ceiling matters.
+        const packed = text(join(common, "packed-refs"), 1024 * 1024);
+        const matches = (packed ?? "").split("\n").filter(line => line.slice(41) === branch && SHA.test(line.slice(0, 40)) && line[40] === " ");
+        return matches.length === 1 ? matches[0]!.slice(0, 40) : undefined;
+      } catch { return undefined; }
+    };
+    return current() === lines[2] ? { head: lines[2]!, current } : undefined;
+  } catch { return undefined; }
+}

package/src/hub/memory-code-overlay.ts

@@ -0,0 +1,119 @@
+import type { NativeItem } from "../memory/brief.ts";
+import { unindexedSymbolSyntax, type CodeFactResult, type CodeSymbol } from "./code-facts.ts";
+import { canonicalMemorySymbolNode, MEMORY_SYMBOL_START_BUDGET_MS, type MemorySymbolContext } from "./memory-symbols.ts";
+
+export const MEMORY_CODE_SEEDS = 4, MEMORY_CODE_NEIGHBOURS = 32, MEMORY_CODE_EDGES = 64;
+const NOTE_LIMIT = 16, NOTE_SCAN_LIMIT = 128, SHA = /^[a-f0-9]{40}$/;
+export interface MemoryCodeNode { id: string; type: "symbol"; label: string; derived: true; head: string }
+export interface MemoryCodeEdge { from: string; to: string; rel: "calls"; derived: true; head: string }
+export interface MemoryCodeOverlay {
+  state: "known" | "unknown";
+  head?: string;
+  nodes: MemoryCodeNode[];
+  edges: MemoryCodeEdge[];
+  notes: NativeItem[];
+  queried: number;
+  unknown: number;
+  truncated: boolean;
+  countsFloor: boolean;
+}
+export interface CodeNeighbourhood { callers: CodeSymbol[]; callees: CodeSymbol[]; hiddenAmbiguous: number; countsFloor: boolean }
+export interface MemoryCodeOverlayOptions {
+  context(): Omit<MemorySymbolContext, "allowed">;
+  head(): string | undefined;
+  /** Current binding, invocation, repository and task provenance, checked across every await. */
+  valid(): boolean;
+  private?(): boolean;
+  publicMetadataText(text: string): boolean;
+  neighbours(repo: string, head: string, selector: string, depth: 1): Promise<CodeFactResult<CodeNeighbourhood>>;
+  /** Fully screened current notes only; no authoritative memory/candidate writes. */
+  related?(nodes: readonly string[], limit: number): readonly NativeItem[];
+  now?: () => number;
+}
+export function unavailableMemoryCodeOverlay(): MemoryCodeOverlay {
+  return { state: "unknown", nodes: [], edges: [], notes: [], queried: 0, unknown: 0, truncated: false, countsFloor: false };
+}
+
+/** One read-time call hop, distinct from the stored memory graph. Never persists nodes, edges or notes. */
+export async function deriveMemoryCodeOverlay(starts: readonly string[], options: MemoryCodeOverlayOptions): Promise<MemoryCodeOverlay> {
+  const out = unavailableMemoryCodeOverlay(), now = options.now ?? performance.now.bind(performance);
+  const deadline = now() + MEMORY_SYMBOL_START_BUDGET_MS;
+  try {
+    const initial = options.context(), head = options.head();
+    const valid = () => {
+      const current = options.context();
+      return !options.private?.() && options.valid() && options.head() === head
+        && current.cwd === initial.cwd && current.project === initial.project && current.repo === initial.repo;
+    };
+    if (!head || !SHA.test(head) || !valid()) return out;
+    out.head = head; out.state = "known"; out.truncated = starts.length > MEMORY_CODE_SEEDS;
+    const canonical = (raw: string) => canonicalMemorySymbolNode(raw, { ...options.context(), allowed: options.publicMetadataText });
+    const nodes = new Map<string, MemoryCodeNode>(), edges = new Map<string, MemoryCodeEdge>(), neighbours = new Set<string>(), seen = new Set<string>();
+    const node = (id: string): MemoryCodeNode => ({ id, type: "symbol", label: id.slice(7), derived: true, head });
+    for (const raw of starts.slice(0, MEMORY_CODE_SEEDS)) {
+      if (!valid()) return { ...unavailableMemoryCodeOverlay(), queried: out.queried, truncated: out.truncated };
+      const seed = canonical(raw);
+      if (!seed) { out.unknown++; continue; }
+      const at = seed.lastIndexOf("@"), name = seed.slice(7, at), path = seed.slice(at + 1);
+      // The CLI's file:name selector cannot certify a colon-bearing file or unsupported host name syntax.
+      if (path.includes(":") || unindexedSymbolSyntax(name)) { out.unknown++; continue; }
+      if (seen.has(seed)) continue;
+      seen.add(seed);
+      if (now() >= deadline) { out.unknown++; out.truncated = true; continue; }
+      try {
+        out.queried++;
+        const answer = await options.neighbours(initial.cwd, head, `${path}:${name}`, 1);
+        if (!valid()) return { ...unavailableMemoryCodeOverlay(), queried: out.queried, truncated: out.truncated };
+        if (canonical(raw) !== seed) { out.unknown++; continue; }
+        if (answer.state !== "known") { out.unknown++; continue; }
+        const facts = answer.value;
+        if (!Array.isArray(facts.callers) || !Array.isArray(facts.callees) || !Number.isSafeInteger(facts.hiddenAmbiguous) || facts.hiddenAmbiguous < 0 || typeof facts.countsFloor !== "boolean") { out.unknown++; continue; }
+        nodes.set(seed, node(seed)); out.countsFloor ||= facts.countsFloor;
+        if (facts.hiddenAmbiguous) out.unknown++;
+        for (const [items, incoming] of [[facts.callers, true], [facts.callees, false]] as const) {
+          if (items.length > 256) out.truncated = true;
+          for (const item of items.slice(0, 256)) {
+            if (item.ambiguous !== false) { out.unknown++; continue; }
+            const id = canonical(`symbol:${item.name}@${item.path}`);
+            if (!id) { out.unknown++; continue; }
+            if (id === seed) continue;
+            const from = incoming ? id : seed, to = incoming ? seed : id, key = JSON.stringify([from, to]);
+            if (edges.has(key)) continue;
+            if (edges.size >= MEMORY_CODE_EDGES || (!neighbours.has(id) && neighbours.size >= MEMORY_CODE_NEIGHBOURS)) { out.truncated = true; continue; }
+            neighbours.add(id); nodes.set(id, node(id)); edges.set(key, { from, to, rel: "calls", derived: true, head });
+          }
+        }
+      } catch { out.unknown++; }
+    }
+    if (!valid()) return { ...unavailableMemoryCodeOverlay(), queried: out.queried, truncated: out.truncated };
+    // Later queries can tighten policy for an earlier result. Reproject everything synchronously under current policy.
+    const kept = new Set([...nodes.keys()].filter(id => canonical(id) === id));
+    if (kept.size !== nodes.size) out.unknown++;
+    out.edges = [...edges.values()].filter(edge => kept.has(edge.from) && kept.has(edge.to));
+    const connected = new Set(out.edges.flatMap(edge => [edge.from, edge.to]));
+    out.nodes = [...nodes.values()].filter(value => kept.has(value.id) && (connected.has(value.id) || seen.has(value.id)));
+    const neighbourIds = [...neighbours].filter(id => kept.has(id) && connected.has(id));
+    if (options.related && neighbourIds.length) {
+      try {
+        const rows = options.related(neighbourIds, NOTE_SCAN_LIMIT);
+        if (rows.length > NOTE_SCAN_LIMIT) out.truncated = true;
+        const safe = rows.slice(0, NOTE_SCAN_LIMIT).filter(item => /^mem:[a-f0-9]{32}$/.test(item.id) && Buffer.byteLength(item.line) <= 1024
+          && item.about && item.about.length <= 64 && item.about.some(id => neighbourIds.includes(id))
+          && [item.id, item.line, item.kind ?? "", ...item.about].every(options.publicMetadataText));
+        const ordered = [...new Map(safe.map(item => [item.id, item])).values()].sort((a, b) => Number(b.kind === "fail") - Number(a.kind === "fail") || a.id.localeCompare(b.id));
+        out.truncated ||= ordered.length > NOTE_LIMIT;
+        out.notes = ordered.slice(0, NOTE_LIMIT).map(item => ({ ...item, about: [...item.about!] }));
+      } catch { out.unknown++; }
+    }
+    if (!valid()) return { ...unavailableMemoryCodeOverlay(), queried: out.queried, truncated: out.truncated };
+    const finalIds = new Set(out.nodes.filter(value => canonical(value.id) === value.id).map(value => value.id));
+    if (finalIds.size !== out.nodes.length) out.unknown++;
+    out.edges = out.edges.filter(edge => finalIds.has(edge.from) && finalIds.has(edge.to));
+    const finalConnected = new Set(out.edges.flatMap(edge => [edge.from, edge.to]));
+    out.nodes = out.nodes.filter(value => finalIds.has(value.id) && (seen.has(value.id) || finalConnected.has(value.id)));
+    out.notes = out.notes.filter(item => item.about?.some(id => neighbours.has(id) && finalIds.has(id) && finalConnected.has(id))
+      && [item.id, item.line, item.kind ?? "", ...(item.about ?? [])].every(options.publicMetadataText));
+    if (out.unknown || out.truncated) out.state = "unknown";
+    return out;
+  } catch { return { ...unavailableMemoryCodeOverlay(), queried: out.queried, truncated: out.truncated }; }
+}

package/src/hub/memory-plan-guard.ts

@@ -1,3 +1,4 @@
+import { normalizeMemorySymbolInput } from "./memory-symbols.ts";
 import { extractNodes, nodePath, type View } from "@staix/agent-mem";
 import type { BriefTask } from "../memory/brief.ts";
 
@@ -13,10 +14,18 @@ export function planGuardNodes(task: BriefTask, context: PlanGuardContext): stri
   }
   const onlyPath = nodes.size === 1 ? nodePath([...nodes][0]!) : undefined;
   for (const symbol of task.plan?.symbols ?? []) {
-    for (const node of extractNodes("", { ...context, paths: onlyPath ? [onlyPath] : [], symbols: [symbol], checkExists: false })) nodes.add(node);
+    if (typeof symbol !== "string") continue;
+    for (const form of new Set([symbol, normalizeMemorySymbolInput(symbol)])) {
+      for (const node of extractNodes("", { ...context, paths: onlyPath ? [onlyPath] : [], symbols: [form], checkExists: false })) nodes.add(node);
+    }
   }
   return [...nodes].sort();
 }
+/** Retrieval nodes retain the title/task context as well as the explicit plan query. */
+export function taskMemoryQueryNodes(task: BriefTask, context: PlanGuardContext): string[] {
+  const ordinary = extractNodes(task.title, { ...context, paths: [...(task.refs.paths ?? []), ...(task.plan?.paths ?? [])], ...(task.id !== undefined && task.created !== undefined ? { task: { id: task.id, created: task.created } } : {}) });
+  return [...new Set([...ordinary, ...planGuardNodes(task, context)])].sort();
+}
 const samePath = (a: string, b: string) => a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
 
 /** Fail.about is the source of the graph's rules_out edges in v1; there is no additional stored rules_out field. */

package/src/hub/memory-stale-anchors.ts

@@ -0,0 +1,159 @@
+import { ASK_NOTE_TITLE } from "./ask.ts";
+import { looksSecret, taskKey, type MemoryStore, type View } from "@staix/agent-mem";
+import { unindexedSymbolSyntax, type CodeFactResult } from "./code-facts.ts";
+import { canonicalMemorySymbolNode, MEMORY_SYMBOL_LIMIT, MEMORY_SYMBOL_START_BUDGET_MS, type MemorySymbolContext } from "./memory-symbols.ts";
+
+export const MEMORY_STALE_SCAN_LIMIT = 256;
+const PAGE = 64, NODE_SCAN_LIMIT = 256;
+const SHA = /^[a-f0-9]{40}$/, ID = /^[a-f0-9]{32}$/;
+export type MemoryTaskPrivacy = "public" | "private" | "unknown";
+export type MemoryStaleReason = "absent" | "withheld" | "provenance" | "task-private" | "task-privacy-unknown" | "unavailable" | "ambiguous" | "present-path-unverified" | "budget" | "head-changed";
+export interface MemoryStaleAnchorRow { id?: string; anchor?: string; state: "stale" | "unknown"; reason: MemoryStaleReason; label?: "absent from indexed definitions" }
+export interface MemoryStaleAnchorReport {
+  state: "known" | "unknown";
+  head?: string;
+  rows: MemoryStaleAnchorRow[];
+  scanned: number;
+  queried: number;
+  stale: number;
+  /** Null means the source inventory itself was unavailable, not zero unresolved anchors. */
+  unknown: number | null;
+  truncated: boolean;
+  limit: number;
+  scanLimit: number;
+}
+export interface MemoryStaleAnchorOptions {
+  cwd: string;
+  project: string;
+  store: Pick<MemoryStore, "readPage" | "withDeferredPromotions">;
+  context(): MemorySymbolContext;
+  publicMetadataText(text: string): boolean;
+  head(): string | undefined;
+  assertCurrent?(): void;
+  taskPrivacy?(key: string): MemoryTaskPrivacy;
+  exists(repo: string, head: string, name: string): Promise<CodeFactResult<{ exists: boolean; ambiguous: boolean }>>;
+  now?: () => number;
+  /** Owned query teardown finishes before the final policy/HEAD projection. */
+  finishQueries?(): Promise<void>;
+}
+export function unavailableMemoryStaleAnchors(): MemoryStaleAnchorReport {
+  return { state: "unknown", rows: [], scanned: 0, queried: 0, stale: 0, unknown: null, truncated: false, limit: MEMORY_SYMBOL_LIMIT, scanLimit: MEMORY_STALE_SCAN_LIMIT };
+}
+/** Parse only the package's exact reset-safe identity; legacy ids never establish current task privacy. */
+export function memoryAnchorTaskIdentity(key: string, project: string): { id: number; created: number; legacy: string } | undefined {
+  if (!key.startsWith(`${project}#`)) return;
+  const match = /^([1-9][0-9]*)@([1-9][0-9]*)$/.exec(key.slice(project.length + 1));
+  if (!match) return;
+  const id = Number(match[1]), created = Number(match[2]);
+  if (!Number.isSafeInteger(id) || !Number.isSafeInteger(created) || taskKey(project, { id, created }) !== key) return;
+  return { id, created, legacy: `${project}#${id}` };
+}
+// Structural task ids/timestamps are host metadata; arbitrary text and symbol/path digits stay screened unchanged.
+const taskNamespace = (key: string): string => key.replace(/#[0-9]+(?:@[0-9]+)?$/, "");
+const literalNote = (note: View): string => [note.title ?? "", note.text, taskNamespace(note.task ?? ""), note.project,
+  ...note.about.map(node => node.startsWith("task:") ? taskNamespace(node) : node)].join("\n");
+function privacy(note: View, options: MemoryStaleAnchorOptions): MemoryStaleReason | undefined {
+  try {
+    options.assertCurrent?.();
+    if (note.about.length > NODE_SCAN_LIMIT) return "unavailable";
+    if (note.project !== options.project || !ID.test(note.id) || note.title?.startsWith(ASK_NOTE_TITLE)) return "provenance";
+    const raw = literalNote(note);
+    if (looksSecret(raw) || !options.publicMetadataText(raw)) return "withheld";
+    let ownLegacy: string | undefined;
+    if (note.task) {
+      const identity = memoryAnchorTaskIdentity(note.task, options.project);
+      if (!identity) return "task-privacy-unknown";
+      const state = options.taskPrivacy?.(note.task) ?? "unknown";
+      if (state !== "public") return state === "private" ? "task-private" : "task-privacy-unknown";
+      ownLegacy = identity.legacy;
+    }
+    for (const task of new Set(note.about.filter(node => node.startsWith("task:")).map(node => node.slice(5)))) {
+      if (task === note.task || task === ownLegacy) continue;
+      if (!memoryAnchorTaskIdentity(task, options.project)) return "task-privacy-unknown";
+      const state = options.taskPrivacy?.(task) ?? "unknown";
+      if (state !== "public") return state === "private" ? "task-private" : "task-privacy-unknown";
+    }
+  } catch { return "unavailable"; }
+}
+
+/** A read-only derived report. The deadline bounds query starts; the existing core refresh/CodeFacts preparation bounds still apply. */
+export async function memoryStaleAnchors(options: MemoryStaleAnchorOptions): Promise<MemoryStaleAnchorReport> {
+  const report = unavailableMemoryStaleAnchors(), now = options.now ?? performance.now.bind(performance), deadline = now() + MEMORY_SYMBOL_START_BUDGET_MS;
+  const candidates: Array<{ note: View; raw: string }> = [];
+  const identities = new Map<MemoryStaleAnchorRow, string>();
+  let after: { position: number; id: string } | undefined;
+  try {
+    options.assertCurrent?.();
+    const head = options.head(); if (head && SHA.test(head)) report.head = head;
+    for (let page = 0; page < MEMORY_STALE_SCAN_LIMIT / PAGE; page++) {
+      if (now() >= deadline) { report.truncated = true; break; }
+      options.assertCurrent?.();
+      const result = options.store.withDeferredPromotions(() => options.store.readPage({ project: options.project, limit: PAGE, ...(after ? { after } : {}) }));
+      report.scanned += result.rows.length;
+      for (const note of result.rows) {
+        if (note.about.length > NODE_SCAN_LIMIT) report.truncated = true;
+        for (const raw of note.about.slice(0, NODE_SCAN_LIMIT)) {
+          if (!raw.startsWith("symbol:") || candidates.some(candidate => candidate.note.id === note.id && candidate.raw === raw)) continue;
+          if (candidates.length >= MEMORY_SYMBOL_LIMIT) { report.truncated = true; break; }
+          candidates.push({ note, raw });
+        }
+      }
+      if (!result.next) { after = undefined; break; }
+      after = result.next;
+      if (page === MEMORY_STALE_SCAN_LIMIT / PAGE - 1) {
+        const more = options.store.withDeferredPromotions(() => options.store.readPage({ project: options.project, limit: 1, after }));
+        report.truncated ||= more.rows.length > 0 || more.next !== undefined;
+      }
+    }
+    report.unknown = 0;
+    for (const candidate of candidates) {
+      if (now() >= deadline) { report.rows.push({ state: "unknown", reason: "budget" }); report.truncated = true; continue; }
+      const hidden = privacy(candidate.note, options);
+      if (hidden) { report.rows.push({ state: "unknown", reason: hidden }); continue; }
+      const context = options.context();
+      const anchor = context.project === options.project && context.cwd === options.cwd ? canonicalMemorySymbolNode(candidate.raw, context) : undefined;
+      if (!anchor) { report.rows.push({ state: "unknown", reason: "withheld" }); continue; }
+      const row: MemoryStaleAnchorRow = { id: candidate.note.id, anchor, state: "unknown", reason: "unavailable" };
+      report.rows.push(row); identities.set(row, context.repo);
+      const name = anchor.slice(7, anchor.lastIndexOf("@"));
+      if (unindexedSymbolSyntax(name)) continue;
+      if (!report.head) continue;
+      if (now() >= deadline) { row.reason = "budget"; report.truncated = true; continue; }
+      if (options.head() !== report.head) { row.reason = "head-changed"; continue; }
+      try {
+        options.assertCurrent?.(); report.queried++;
+        const answer = await options.exists(options.cwd, report.head, name);
+        const withheld = privacy(candidate.note, options);
+        const current = options.context();
+        if (withheld || current.project !== options.project || current.cwd !== options.cwd || current.repo !== context.repo || canonicalMemorySymbolNode(candidate.raw, current) !== anchor) { delete row.id; delete row.anchor; row.reason = withheld ?? "withheld"; continue; }
+        if (options.head() !== report.head) { row.reason = "head-changed"; continue; }
+        if (answer.state !== "known") continue;
+        if (answer.value.ambiguous === true) row.reason = "ambiguous";
+        else if (answer.value.exists === false && answer.value.ambiguous === false) { row.state = "stale"; row.reason = "absent"; }
+        else if (answer.value.exists === true && answer.value.ambiguous === false) row.reason = "present-path-unverified"; // exists() does not attest the defining file, so this anchor is not proven present.
+      } catch { row.reason = "unavailable"; }
+    }
+    await options.finishQueries?.();
+    options.assertCurrent?.();
+    if (report.head && options.head() !== report.head) for (const row of report.rows) { row.state = "unknown"; row.reason = "head-changed"; }
+    // Policy and current-task privacy may change during another anchor's awaited query.
+    for (let index = 0; index < candidates.length; index++) {
+      const row = report.rows[index], candidate = candidates[index]; if (!row || !candidate) continue;
+      const hidden = privacy(candidate.note, options), current = options.context();
+      const changed = row.anchor !== undefined && (current.project !== options.project || current.cwd !== options.cwd || current.repo !== identities.get(row) || canonicalMemorySymbolNode(candidate.raw, current) !== row.anchor);
+      if (hidden || changed) { delete row.id; delete row.anchor; row.state = "unknown"; row.reason = hidden ?? "withheld"; }
+    }
+    for (const row of report.rows) if (row.state === "stale" && row.reason === "absent") row.label = "absent from indexed definitions";
+    report.stale = report.rows.filter(row => row.state === "stale").length;
+    report.unknown = report.rows.length - report.stale;
+    report.state = report.unknown || report.truncated || !report.head ? "unknown" : "known";
+    return report;
+  } catch { return { ...unavailableMemoryStaleAnchors(), scanned: report.scanned, queried: report.queried, truncated: report.truncated }; }
+}
+
+export function formatMemoryStaleAnchors(report: MemoryStaleAnchorReport): string {
+  return [`stale anchors: ${report.stale}; unknown: ${report.unknown ?? "unknown"}; coverage: ${report.state}${report.truncated ? " (truncated)" : ""}`,
+    `scope: ${report.head ?? "HEAD unavailable"}; scanned ${report.scanned}/${report.scanLimit}; queried ${report.queried}/${report.limit}`,
+    ...report.rows.map(row => `${row.id ? `mem:${row.id} ` : ""}${row.anchor ? `${row.anchor} ` : ""}${row.state} (${row.reason})${row.label ? `: ${row.label}` : ""}`),
+    "review only; no memory entries or candidate records changed"].join("\n");
+}

package/src/hub/memory-symbols.ts

@@ -0,0 +1,74 @@
+import { isDenied } from "../local/deny.ts";
+import { foldSegment } from "./permission-mode.ts";
+import { matchesPolicyLexically } from "./path-policy.ts";
+import { extractNodes } from "@staix/agent-mem";
+import { normalizePlanSymbol } from "./symbol-normalizer.ts";
+import type { CodeFactResult } from "./code-facts.ts";
+
+export const MEMORY_SYMBOL_LIMIT = 16;
+export const MEMORY_SYMBOL_START_BUDGET_MS = 2000;
+export interface MemorySymbolContext {
+  cwd: string; project: string; repo: string; deny?: string[];
+  allowed: (text: string) => boolean;
+}
+export interface MemorySymbolNodes {
+  state: "known" | "unknown";
+  nodes: string[];
+  unknown: number;
+  truncated: boolean;
+}
+
+/** Preserve an explicit file suffix while normalizing a plan's function signature. */
+export function normalizeMemorySymbolInput(value: string): string {
+  if (typeof value !== "string") return "";
+  const at = value.lastIndexOf("@");
+  return at < 0 ? normalizePlanSymbol(value) : `${normalizePlanSymbol(value.slice(0, at))}@${value.slice(at + 1)}`;
+}
+
+/** Candidate identity only. Callers must obtain positive code facts before storing it as an about node. */
+export function canonicalMemorySymbolNode(node: string, context: MemorySymbolContext): string | undefined {
+  if (typeof node !== "string" || !node.startsWith("symbol:") || Buffer.byteLength(node) > 512 || /[\p{Cc}\p{Cf}]/u.test(node)) return;
+  const at = node.lastIndexOf("@");
+  if (at <= 7 || at === node.length - 1 || node.slice(at + 1).includes("\\")) return;
+  const name = normalizePlanSymbol(node.slice(7, at)), path = node.slice(at + 1);
+  if (!name || /\s|@|\(|\)/u.test(name) || name.startsWith("section ") || name.startsWith("source ")) return;
+  // Use the package's path/deny normalization, without reading a working tree or following symlinks.
+  const paths = extractNodes("", { ...context, paths: [path], checkExists: false }).filter(value => value.startsWith("path:"));
+  if (paths.length !== 1) return;
+  const file = paths[0]!.slice(5), deny = context.deny ?? [];
+  // Core extraction covers literal denies; host read-time policy also covers folded names and declared globs.
+  if (isDenied(foldSegment(file), deny.map(foldSegment)) || matchesPolicyLexically(context.cwd, file, deny)) return;
+  const normalized = `symbol:${name}@${file}`;
+  try { if ([node, name, path, normalized].every(context.allowed)) return normalized; } catch { /* Unknown policy withholds. */ }
+}
+
+/** A bounded optional check of host-observed identities, never plan guesses or source structure. */
+export async function resolveMemorySymbolNodes(
+  candidates: readonly string[], context: MemorySymbolContext,
+  exists: (name: string) => Promise<CodeFactResult<{ exists: boolean; ambiguous: boolean }>>,
+  now: () => number = performance.now.bind(performance),
+): Promise<MemorySymbolNodes> {
+  const result: MemorySymbolNodes = { state: "known", nodes: [], unknown: 0, truncated: candidates.length > MEMORY_SYMBOL_LIMIT };
+  const deadline = now() + MEMORY_SYMBOL_START_BUDGET_MS, seen = new Set<string>();
+  const lookups = new Map<string, Promise<CodeFactResult<{ exists: boolean; ambiguous: boolean }>>>();
+  for (const candidate of candidates.slice(0, MEMORY_SYMBOL_LIMIT)) {
+    const node = canonicalMemorySymbolNode(candidate, context);
+    if (!node) { result.unknown++; continue; }
+    if (seen.has(node)) continue;
+    seen.add(node);
+    if (now() >= deadline) { result.unknown++; result.truncated = true; continue; }
+    try {
+      const name = node.slice(7, node.lastIndexOf("@"));
+      let lookup = lookups.get(name);
+      if (!lookup) {
+        lookup = Promise.resolve().then(() => exists(name)).catch(() => ({ state: "unknown" } as const));
+        lookups.set(name, lookup);
+      }
+      const fact = await lookup;
+      if (fact.state === "known" && fact.value.exists === true && fact.value.ambiguous === false) result.nodes.push(node);
+      else result.unknown++;
+    } catch { result.unknown++; }
+  }
+  if (result.unknown || result.truncated) result.state = "unknown";
+  return result;
+}

package/src/hub/planning.ts

@@ -1,9 +1,10 @@
 import type { ReleaseTrainData } from "./sdlc-release.ts";
+import { planningIssueIdentity, type PlanningIssueIdentity } from "./sdlc.ts";
 import type { Task } from "./board.ts";
 
 export const BACKLOG_SPLIT_SCREEN_TIMEOUT_MS = 8000;
 
-export const PLANNING_FIELDS = ["rank", "priority", "release", "plannedStart", "due", "pinned", "deps", "reserved"] as const;
+export const PLANNING_FIELDS = ["rank", "priority", "release", "plannedStart", "due", "pinned", "deps", "reserved", "sdlc"] as const;
 export interface PlanningFields {
   rank?: number | null;
   priority?: number | null;
@@ -13,6 +14,7 @@ export interface PlanningFields {
   pinned?: boolean;
   deps?: number[];
   reserved?: string | null;
+  sdlc?: PlanningIssueIdentity;
 }
 export interface PlanningPatch extends PlanningFields {}
 /** Machine-local capacity settings; ids never grant roster membership or authority. */
@@ -29,6 +31,8 @@ export function planningWipLimits(input: unknown): Record<string, number> {
 export const RELEASE_STATES = ["planning", "active", "frozen", "shipped", "dropped"] as const;
 export type ReleaseState = (typeof RELEASE_STATES)[number];
 export interface Release {
+  /** Null for rows created before task-scoped planners; no inferred backfill. */
+  planner?: string | null;
   train?: ReleaseTrainData;
   id: number; name: string; goal: string; order: number; state: ReleaseState;
   plannedStart: number | null; cut: number | null; ship: number | null;
@@ -37,15 +41,17 @@ export interface Release {
 }
 
 /** Validate the entire planning input before a write; actual dates are never caller input. */
-export function planningPatch(input: unknown): PlanningPatch {
+export function planningPatch(input: unknown = {}): PlanningPatch {
   if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error("planning fields must be an object");
   const fields = input as Record<string, unknown>;
-  if (!Object.keys(fields).length || Object.keys(fields).some(key => !(PLANNING_FIELDS as readonly string[]).includes(key))) throw new Error("unknown or empty planning fields");
+  if (Object.keys(fields).some(key => !(PLANNING_FIELDS as readonly string[]).includes(key))) throw new Error("unknown planning fields");
   const result: PlanningPatch = {};
   for (const key of PLANNING_FIELDS) {
     if (!Object.hasOwn(fields, key)) continue;
     const value = fields[key];
-    if (key === "deps") {
+    if (key === "sdlc") {
+      result.sdlc = planningIssueIdentity(value);
+    } else if (key === "deps") {
       if (!Array.isArray(value) || value.length > 64 || value.some(id => !Number.isSafeInteger(id) || id <= 0) || new Set(value).size !== value.length) throw new Error("deps must be at most 64 unique positive task ids");
       result.deps = [...value];
     } else if (key === "reserved") {