@staix/agent-hub 0.14.0 → 0.16.0

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/manager.ts

@@ -155,7 +155,7 @@ export async function startManager(options: ManagerOptions = {}): Promise<Manage
           return { ok: true };
         }
         // The settings actions (#269) reach the project hub as an ordinary session's: this dashboard opens no settings session.
-        if (!["snapshot", "send", "pause", "resume", "permit", "propose", "assign", "backlog_pull", "backlog_return", "planning", "planning_undo", "planner_pull", "backlog_split", "release_new", "release_change", "setting", "setting_undo", "setting_preview", "setting_reload", "start_peer", "sdlc_queue", "sdlc_release"].includes(String(input.action))) return { ok: false, error: "invalid dashboard action" };
+        if (!["snapshot", "send", "pause", "resume", "permit", "propose", "assign", "backlog_pull", "backlog_return", "planning", "planning_undo", "planner_pull", "backlog_split", "release_new", "release_change", "setting", "setting_undo", "setting_preview", "setting_reload", "config_edit_preview", "config_edit_apply", "start_peer", "sdlc_queue", "sdlc_release"].includes(String(input.action))) return { ok: false, error: "invalid dashboard action" };
         client = await ControlClient.connect(project.stateDir, { role: "console", projectId: project.id, projectRoot: project.root, instanceId: input.instanceId });
         const deliveryRead = input.action === "sdlc_queue" || input.action === "sdlc_release";
         let nominalMs = 10_000;

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/peers.ts

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

package/src/hub/permission-payload.ts

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

package/src/hub/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") {

package/src/hub/read-tools.ts

@@ -1,3 +1,4 @@
+import type { MemoryCodeOverlay } from "./memory-code-overlay.ts";
 import type { MemoryStore, View, Graph } from "@staix/agent-mem";
 import { looksSecret } from "@staix/agent-mem";
 import { PreEffectToolRefusal } from "./tool-refusal.ts";
@@ -29,7 +30,7 @@ export function validateMemoryRead(op: string, a: Record<string, unknown>): void
 }
 
 /** Read-only model projection. Counts and caps are computed only after screening whole records and metadata. */
-export function memoryRead(store: MemoryStore | undefined, project: string, screen: MemoryScreen, op: string, a: Record<string, unknown>, stale: (about: readonly string[]) => boolean = () => false): string {
+export function memoryRead(store: MemoryStore | undefined, project: string, screen: MemoryScreen, op: string, a: Record<string, unknown>, stale: (about: readonly string[]) => boolean = () => false, code?: MemoryCodeOverlay): string {
   validateMemoryRead(op, a);
   const safe = (v: unknown): boolean => {
     try {
@@ -93,7 +94,9 @@ export function memoryRead(store: MemoryStore | undefined, project: string, scre
       if (n.startsWith("goal:") && !goals.has(n)) reject();
       return n;
     });
-    const nodes = new Map<string, Graph["nodes"][number]>(), edges = new Map<string, Graph["edges"][number]>();
+    type Node = Graph["nodes"][number] & { derived?: true; head?: string; codeNeighbour?: true };
+    type Edge = Omit<Graph["edges"][number], "rel"> & { rel: string; derived?: true; head?: string };
+    const nodes = new Map<string, Node>(), edges = new Map<string, Edge>();
     for (const start of starts) {
       const graph = store.graph(project, start, Number(a.hops ?? 1), Number.MAX_SAFE_INTEGER);
       for (const n of graph.nodes) {
@@ -105,12 +108,27 @@ export function memoryRead(store: MemoryStore | undefined, project: string, scre
       }
       for (const e of graph.edges) if (safe(e)) edges.set(JSON.stringify(e), e);
     }
+    const overlay = code && /^[a-f0-9]{40}$/.test(code.head ?? "") && starts.some(id => id.startsWith("symbol:")) ? code : undefined;
+    if (overlay) {
+      for (const node of overlay.nodes) if (!nodes.has(node.id) && node.head === overlay.head && node.derived && safe(node)) nodes.set(node.id, node);
+      for (const edge of overlay.edges) if (edge.head === overlay.head && edge.derived && edge.rel === "calls" && safe(edge)) edges.set(JSON.stringify(edge), edge);
+      for (const note of overlay.notes) {
+        const value = visible.get(note.id);
+        if (!value || !safe(note)) continue;
+        nodes.set(note.id, { id: note.id, type: "memory", label: excerpt(value.title ?? value.text), kind: value.kind, codeNeighbour: true });
+        for (const about of value.about) if (overlay.nodes.some(node => node.id === about)) {
+          const edge = { from: note.id, to: about, rel: value.kind === "fail" ? "rules_out" : "about" };
+          edges.set(JSON.stringify(edge), edge);
+        }
+      }
+    }
     const screenedEdges = [...edges.values()].filter(e => nodes.has(e.from) && nodes.has(e.to));
     const connected = new Set(screenedEdges.flatMap(e => [e.from, e.to]));
     const rank = (n: Graph["nodes"][number]) => n.kind === "fail" ? 0 : starts.includes(n.id) ? 1 : n.type !== "memory" ? 2 : 3;
     const eligibleNodes = [...nodes.values()].filter(n => connected.has(n.id) || starts.includes(n.id)).sort((x, y) => rank(x) - rank(y) || x.id.localeCompare(y.id));
     const eligibleEdges = screenedEdges.sort((x, y) => JSON.stringify(x).localeCompare(JSON.stringify(y)));
-    const out: Graph & { truncated: number } = { nodes: [], edges: [], truncated: eligibleNodes.length + eligibleEdges.length };
+    const out: { nodes: Node[]; edges: Edge[]; truncated: number; code?: { state: "known" | "unknown"; head?: string; truncated: boolean; countsFloor: boolean } } = { nodes: [], edges: [], truncated: eligibleNodes.length + eligibleEdges.length,
+      ...(code ? { code: { state: overlay?.state ?? "unknown", ...(overlay?.head ? { head: overlay.head } : {}), truncated: code.truncated, countsFloor: code.countsFloor } } : {}) };
     for (const n of eligibleNodes) {
       if (out.nodes.length >= Number(a.limit ?? 60)) break;
       out.nodes.push(n); out.truncated--;