@staix/agent-hub 0.12.22 → 0.12.24

package/src/local/sandbox.ts

@@ -1,8 +1,9 @@
 import { spawn, spawnSync } from "node:child_process";
-import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { existsSync, mkdtempSync, readdirSync, rmSync, type Dirent } from "node:fs";
 import { homedir, tmpdir } from "node:os";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { realPath } from "../hub/project.ts";
+import { hubGitSync } from "../hub/git.ts";
 import { denyRegexes, hubWriteRegexes, sbplString } from "./deny.ts";
 
 const SANDBOX_EXEC = "/usr/bin/sandbox-exec";
@@ -40,12 +41,47 @@ function developerDir(): string | undefined {
 
 /** A submodule or worktree keeps its git dir outside the project; git needs it, minus the parts that execute or reconfigure. */
 function externalGitDirs(root: string): string[] {
-  const out = spawnSync("git", ["-C", root, "rev-parse", "--absolute-git-dir", "--git-common-dir"], { encoding: "utf8" });
+  // Runs in the hub process, outside the sandbox: the hardened helper keeps the repo's config from naming a program (#281).
+  const out = hubGitSync(["-C", root, "rev-parse", "--absolute-git-dir", "--git-common-dir"], { encoding: "utf8" });
   if (out.status !== 0) return [];
   const dirs = out.stdout.trim().split("\n").map((d) => resolve(root, d));
   return [...new Set(dirs)].filter((d) => !d.startsWith(`${root}/`));
 }
 
+/**
+ * The project's submodule git directories live under the common dir's `modules/` tree (the worktree case included:
+ * it is the main repo's `.git/modules`). Returns the modules root and every directory entry that must not be
+ * renamed, replaced, symlinked or recreated: each discovered git dir (a directory holding HEAD and config) and
+ * every component between it and the modules root (#281). Discovered in the hub process, outside the sandbox.
+ */
+function moduleGitDirs(root: string): { root: string; entries: string[] } | undefined {
+  const out = hubGitSync(["-C", root, "rev-parse", "--git-common-dir"], { encoding: "utf8" });
+  if (out.status !== 0) return undefined;
+  const modulesRoot = join(resolve(root, out.stdout.trim()), "modules");
+  const dirs: string[] = [];
+  const walk = (dir: string, depth: number): void => {
+    if (depth > 8) return; // submodules do not nest deeper in practice; the regex rules still cover the names
+    let entries: Dirent[];
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return; // no modules tree (no submodules): nothing to discover
+    }
+    const names = new Set(entries.map((e) => e.name));
+    if (names.has("HEAD") && names.has("config")) {
+      dirs.push(dir);
+      const nested = join(dir, "modules");
+      if (names.has("modules")) walk(nested, depth + 1); // a submodule of a submodule
+      return;
+    }
+    for (const e of entries) if (e.isDirectory()) walk(join(dir, e.name), depth + 1);
+  };
+  walk(modulesRoot, 0);
+  const entries = new Set<string>([modulesRoot]);
+  for (const d of dirs) for (let p = d; p.length > modulesRoot.length; p = dirname(p)) entries.add(p);
+  return { root: modulesRoot, entries: [...entries] };
+}
+
 /** The system directories a deny-default profile lets commands read and run from: dyld, frameworks, toolchains. */
 const SYSTEM_READABLE = ["/usr", "/bin", "/sbin", "/System", "/Library", "/opt", "/private/etc", "/private/var/db/timezone", "/private/var/db/dyld"];
 /**
@@ -69,11 +105,12 @@ export type SandboxNetwork = boolean | { proxyPort: number };
  * toolchain and project directories, writing the project and a temp dir of their own. The allow-default profile of
  * 0.9 and earlier was removed in 0.12.0 (issue #83).
  */
-export function profile(cwd: string, network: SandboxNetwork, readAllow: string[] = [], deny: string[] = []): string {
+export function profile(cwd: string, network: SandboxNetwork, readAllow: string[] = [], deny: string[] = [], readOnly: string[] = []): string {
   const home = homedir();
   const inHome = (p: string) => (p.startsWith("~/") ? join(home, p.slice(2)) : p);
   const root = realPath(cwd);
   const gitDirs = externalGitDirs(root);
+  const moduleGit = moduleGitDirs(root);
   const creds = [".ssh", ".aws", ".gnupg", ".config/gh", ".config/gcloud", ".kube", ".docker", ".netrc", ".npmrc", ".omniroute", ".claude", ".codex", ".kimi-code", "Library/Keychains"];
   const dev = developerDir();
   const readable = [root, ...HOME_READABLE.map((p) => join(home, p)), ...readAllow.map(inHome), ...gitDirs, ...(dev ? [dev] : [])];
@@ -101,12 +138,13 @@ export function profile(cwd: string, network: SandboxNetwork, readAllow: string[
     "(version 1)",
     ...start,
     "(deny file-write*)",
-    `(allow file-write* (subpath ${q(root)}) (regex #"^/dev/") ${gitDirs.map((d) => `(subpath ${q(d)})`).join(" ")})`,
+    ...(readOnly.length ? ["(allow file-write* (literal \"/dev/null\"))"] : [`(allow file-write* (subpath ${q(root)}) (regex #"^/dev/") ${gitDirs.map((d) => `(subpath ${q(d)})`).join(" ")})`]),
     // Inside cwd: nothing that runs later outside the sandbox, nothing that reconfigures the hub. The .git and
     // .agenthub patterns tolerate the code points HFS+ ignores in every segment, the .git name itself is refused
-    // at any depth (creation, rename, symlink, gitfile), and the external git dirs get folded hooks/config rules
-    // (#270). The cost: git init, clone and worktree add no longer run inside the sandbox.
-    `(deny file-write* ${hubWriteRegexes(root, gitDirs).join(" ")})`,
+    // at any depth (creation, rename, symlink, gitfile), a submodule git dir's config and hooks under
+    // .git/modules/ are refused at the depth submodules nest (#281), and the external git dirs get folded
+    // hooks/config rules (#270). The cost: git init, clone and worktree add no longer run inside the sandbox.
+    `(deny file-write* ${hubWriteRegexes(root, gitDirs, moduleGit).join(" ")})`,
     `(deny file-read* file-write* ${creds.map((c) => `(subpath ${q(join(home, c))})`).join(" ")})`,
     `(deny file-read* file-write* ${denyRegexes(root, deny).join(" ")})`,
     // Python's own CA bundle (certifi, which pip vendors too): pip, requests and httpx read it instead of the system's (#64).
@@ -121,14 +159,16 @@ export interface ExecResult {
 }
 
 /** Run argv under seatbelt with a scrubbed environment. Never runs unsandboxed: no sandbox, no exec. */
-export function sandboxedExec(argv: string[], opts: { cwd: string; profile: string; timeoutMs?: number; env?: Record<string, string>; signal?: AbortSignal }): Promise<ExecResult> {
+export function sandboxedExec(argv: string[], opts: { cwd: string; profile: string; timeoutMs?: number; env?: Record<string, string>; signal?: AbortSignal; readOnlyData?: boolean }): Promise<ExecResult> {
+  if (opts.readOnlyData && /\(allow file-write\* \(subpath /.test(opts.profile)) return Promise.resolve({ code: null, output: "error: data.readonly command profile contains a broad write grant" });
   if (!sandboxAvailable()) return Promise.resolve({ code: null, output: "error: command execution needs macOS sandbox-exec and is disabled on this host" });
   if (opts.signal?.aborted) return Promise.resolve({ code: null, output: "error: command cancelled before execution" });
   return new Promise((resolve) => {
     // A temp dir of its own (#63): the user's is shared with every other process, and what a command reads can reach
     // an answer shown to cloud peers. Allowed after the profile's denies, and gone when the command ends.
     const own = realPath(mkdtempSync(join(tmpdir(), "ahub-cmd-")));
-    const sandbox = `${opts.profile}\n(allow file-read* file-write* process-exec (subpath ${q(own)}))`;
+    const sandbox = `${opts.profile}\n(allow file-read* ${opts.readOnlyData ? "" : "file-write* "}process-exec (subpath ${q(own)}))`;
+    // A path-only deny cannot contain hardlink aliases; data mode allows reads/stdout, never filesystem writes.
     const env = { PATH: process.env.PATH ?? "/usr/bin:/bin", HOME: homedir(), LANG: process.env.LANG ?? "en_US.UTF-8", TERM: "dumb", ...opts.env, TMPDIR: `${own}/` };
     // Own process group: a timeout has to take the grandchildren too, or they keep the pipes open and the project writable.
     const child = spawn(SANDBOX_EXEC, ["-p", sandbox, ...argv], { cwd: opts.cwd, env, stdio: ["ignore", "pipe", "pipe"], detached: true });

package/src/local/tools.ts

@@ -2,6 +2,7 @@ import { lstatSync, mkdirSync, readFileSync, statSync, writeFileSync } from "nod
 import { dirname, join, relative, resolve } from "node:path";
 import { realPath } from "../hub/project.ts";
 import { isHubWritePath } from "../hub/permission-mode.ts";
+import { matchesPolicy } from "../hub/path-policy.ts";
 import { isDenied } from "./deny.ts";
 import { OUTPUT_CAP, sandboxedExec } from "./sandbox.ts";
 
@@ -17,6 +18,7 @@ const approvalError = (picked: ToolApproval, denied: string): string | undefined
   : picked === "aborted" ? "error: approval withdrawn because the turn ended; no operation was executed" : denied;
 
 export interface ToolContext {
+  readOnly?: string[];
   cwd: string;
   /** Extra denylist entries from config: substrings of the project-relative path. */
   deny: string[];
@@ -27,7 +29,7 @@ export interface ToolContext {
   /** Turn cancellation signal, including the execution-budget wall cap. */
   signal?: AbortSignal;
   /** Only true permits an effect; expiry and abort remain distinct from a person's denial. */
-  permit: (title: string, tool?: string, signal?: AbortSignal, canonicalTarget?: string, observe?: ApprovalObserver) => Promise<ToolApproval>;
+  permit: (title: string, tool?: string, signal?: AbortSignal, canonicalTarget?: string, observe?: ApprovalObserver, originalPath?: string) => Promise<ToolApproval>;
   /** Trusted process status, independent of what its stdout says. */
   onProcessExit?: (code: number | null) => void;
   /** Publish a message to other peers mid-turn. Returns a one-line receipt. */
@@ -44,7 +46,7 @@ const lexists = (p: string) => {
 };
 
 /** Absolute path inside cwd after resolving symlinks, or an Error. `write` also refuses .git and .agenthub. */
-export function guardPath(ctx: Pick<ToolContext, "cwd" | "deny">, path: string, mode: "read" | "write"): string {
+export function guardPath(ctx: Pick<ToolContext, "cwd" | "deny" | "readOnly">, path: string, mode: "read" | "write"): string {
   const root = realPath(ctx.cwd);
   const abs = resolve(root, path);
   // Resolve symlinks on the deepest part that exists: a link pointing outside must not pass as an inside path.
@@ -64,6 +66,9 @@ export function guardPath(ctx: Pick<ToolContext, "cwd" | "deny">, path: string,
   // Not secret, but writing .git or .agenthub changes what runs outside the worker's control. Names are compared
   // folded: a new `.GIT/config` is `.git/config` to a case-insensitive disk, and git then runs what it names.
   if (mode === "write" && isHubWritePath(rel)) throw new Error(`${path} is not writable by the local worker`);
+  // Identity refusal is stable even when realPath names a protected hardlink alias.
+  if (mode === "write" && ctx.readOnly?.length && (lstatSync(real, { throwIfNoEntry: false })?.nlink ?? 1) > 1) throw new Error("hardlinked write target cannot be verified with data.readonly");
+  if (mode === "write" && matchesPolicy(root, path, ctx.readOnly ?? [])) throw new Error("target is protected by data.readonly");
   return real;
 }
 
@@ -142,7 +147,7 @@ export async function runTool(name: string, rawArgs: string, ctx: ToolContext):
         let file = guardPath(ctx, String(a.path), "write");
         const approvedTarget = file;
         const content = String(a.content ?? "");
-        const refused = approvalError(await ctx.permit(`write ${a.path} (${content.length} chars):\n${preview(content)}`, "write", ctx.signal, file), "error: the user did not approve this write");
+        const refused = approvalError(await ctx.permit(`write ${a.path} (${content.length} chars):\n${preview(content)}`, "write", ctx.signal, file, undefined, String(a.path)), "error: the user did not approve this write");
         if (refused) return refused;
         if (ctx.signal?.aborted) return "error: turn cancelled before write";
         file = guardPath(ctx, String(a.path), "write");
@@ -157,7 +162,7 @@ export async function runTool(name: string, rawArgs: string, ctx: ToolContext):
         let text = readFileSync(file, "utf8");
         let count = text.split(String(a.old)).length - 1;
         if (!a.old || count !== 1) return `error: \`old\` must match exactly once, it matched ${count} times`;
-        const refused = approvalError(await ctx.permit(`edit ${a.path}:\n- ${preview(String(a.old), 600)}\n+ ${preview(String(a.new ?? ""), 600)}`, "edit", ctx.signal, file), "error: the user did not approve this edit");
+        const refused = approvalError(await ctx.permit(`edit ${a.path}:\n- ${preview(String(a.old), 600)}\n+ ${preview(String(a.new ?? ""), 600)}`, "edit", ctx.signal, file, undefined, String(a.path)), "error: the user did not approve this edit");
         if (refused) return refused;
         if (ctx.signal?.aborted) return "error: turn cancelled before edit";
         // Approval can outlive another peer's edit or a path change. Apply only the approved fragment to current bytes.
@@ -176,7 +181,7 @@ export async function runTool(name: string, rawArgs: string, ctx: ToolContext):
         if (command.length > 4000) return "error: command longer than 4000 characters; put it in a script file with write, then run that";
         const refused = approvalError(await ctx.permit(`bash: ${command}`, "bash", ctx.signal), "error: the user did not approve this command");
         if (refused) return refused;
-        const res = await sandboxedExec(["/bin/bash", "-c", command], { cwd: ctx.cwd, profile: ctx.sandboxProfile, timeoutMs: (Number(a.timeout_s) || 120) * 1000, ...(ctx.sandboxEnv ? { env: ctx.sandboxEnv } : {}), ...(ctx.signal ? { signal: ctx.signal } : {}) });
+        const res = await sandboxedExec(["/bin/bash", "-c", command], { cwd: ctx.cwd, profile: ctx.sandboxProfile, readOnlyData: !!ctx.readOnly?.length, timeoutMs: (Number(a.timeout_s) || 120) * 1000, ...(ctx.sandboxEnv ? { env: ctx.sandboxEnv } : {}), ...(ctx.signal ? { signal: ctx.signal } : {}) });
         try { ctx.onProcessExit?.(res.code); } catch { /* optional status observer never changes a tool result */ }
         return `${res.output}\n(exit ${res.code})`;
       }
@@ -191,7 +196,7 @@ export async function runTool(name: string, rawArgs: string, ctx: ToolContext):
           if (refused) return refused;
         }
         // Sandboxed like bash: flags such as --output or an editor cannot write outside the project or reach the network.
-        const res = await sandboxedExec(["git", "--no-pager", ...args], { cwd: ctx.cwd, profile: ctx.sandboxProfile, ...(ctx.sandboxEnv ? { env: ctx.sandboxEnv } : {}), ...(ctx.signal ? { signal: ctx.signal } : {}) });
+        const res = await sandboxedExec(["git", "--no-pager", ...args], { cwd: ctx.cwd, profile: ctx.sandboxProfile, readOnlyData: !!ctx.readOnly?.length, ...(ctx.sandboxEnv ? { env: ctx.sandboxEnv } : {}), ...(ctx.signal ? { signal: ctx.signal } : {}) });
         try { ctx.onProcessExit?.(res.code); } catch { /* optional status observer never changes a tool result */ }
         return `${res.output}\n(exit ${res.code})`;
       }

package/src/memory/brief.ts

@@ -27,33 +27,47 @@ export async function related(client: MemoryClient, project: string, query: stri
   return out;
 }
 
+/** A native memory line for a brief (#258): `mem:<id8> <kind> <tier>: <title or text>`, fails first. */
+export interface NativeItem { id: string; line: string; kind?: string }
+export type NativeBrief = (task: BriefTask) => NativeItem[];
+export interface BriefTask { id?: number; created?: number; title: string; refs: { paths?: string[] }; plan?: { paths?: string[]; symbols?: string[] } }
+
 /**
- * Task briefs: what memory already knows about a piece of work, handed over with it. Index first (search), then the
- * neighbourhood of the top hit (timeline); details stay in claude-mem for the receiver to fetch by id. A peer is never
- * shown the same observation twice in one hub run.
+ * Task briefs: what memory already knows about a piece of work, handed over with it. The hub's own store first (#258:
+ * entries one or two hops from the task's paths, symbols, issue and task, a linked fail first, superseded entries
+ * dropped), then claude-mem: index first (search), then the neighbourhood of the top hit (timeline); details stay in
+ * the store for the receiver to fetch by id. `brief_items` caps both together. A peer is never shown the same entry
+ * twice in one hub run.
  */
 export class Briefs {
-  private readonly seen = new Map<PeerId, Set<number>>();
+  private readonly seen = new Map<PeerId, Set<string>>();
 
   constructor(
-    private readonly client: MemoryClient,
+    private readonly client: MemoryClient | undefined,
     private readonly project: string,
     private readonly maxItems = 8,
+    private readonly native?: NativeBrief,
+    /** Counts of what a brief carried, for the research records (#258 AC11); never its text. */
+    private readonly observe?: (peer: PeerId, task: number, counts: { native: number; fails: number; claudeMem: number }) => void,
   ) {}
 
-  async forTask(peer: PeerId, task: { title: string; refs: { paths?: string[] } }): Promise<string | undefined> {
-    const found = await related(this.client, this.project, [task.title, ...(task.refs.paths ?? [])].join(" "));
-    if (!found.length) return undefined;
-    const seen = this.seen.get(peer) ?? new Set<number>();
+  async forTask(peer: PeerId, task: BriefTask): Promise<string | undefined> {
+    const seen = this.seen.get(peer) ?? new Set<string>();
     this.seen.set(peer, seen);
+    const own: NativeItem[] = [];
+    try { for (const item of this.native?.(task) ?? []) if (!seen.has(item.id) && own.length < this.maxItems) own.push(item); } catch { /* fail-open: the store is optional */ }
+    const found = this.client && own.length < this.maxItems ? await related(this.client, this.project, [task.title, ...(task.refs.paths ?? [])].join(" ")) : [];
     const items: BriefItem[] = [];
     for (const item of found) {
-      if (seen.has(item.id)) continue;
+      if (seen.has(`#${item.id}`)) continue;
       items.push(item);
-      if (items.length === this.maxItems) break;
+      if (own.length + items.length === this.maxItems) break;
     }
-    if (!items.length) return undefined;
-    for (const item of items) seen.add(item.id);
-    return ["Memory brief (claude-mem; fetch details by id if you need them):", ...items.map((i) => `#${i.id} ${i.time} ${i.type} ${i.title}`)].join("\n");
+    if (!own.length && !items.length) return undefined;
+    for (const item of own) seen.add(item.id);
+    for (const item of items) seen.add(`#${item.id}`);
+    if (task.id !== undefined) try { this.observe?.(peer, task.id, { native: own.length, fails: own.filter((i) => i.kind === "fail").length, claudeMem: items.length }); } catch { /* telemetry never fails a brief */ }
+    const header = own.length ? "Memory brief (hub memory first, fails first: ahub memory show <mem id>; claude-mem by #id):" : "Memory brief (claude-mem; fetch details by id if you need them):";
+    return [header, ...own.map((i) => i.line), ...items.map((i) => `#${i.id} ${i.time} ${i.type} ${i.title}`)].join("\n");
   }
 }

package/src/memory/import.ts

@@ -0,0 +1,55 @@
+import { Database } from "bun:sqlite";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { KINDS, looksSecret, type Kind, type MemoryStore } from "./store.ts";
+
+/** The claude-mem store is another program's: opened read-only, never written, its locks waited on briefly. */
+export const CLAUDE_MEM_BUSY_TIMEOUT_MS = 3000;
+/** Titles `ahub ask --remember` gives a model's answer (ask.ts ASK_NOTE_TITLE): never imported as a finding. */
+const MODEL_ANSWER = "ahub ask (model answer)";
+
+export interface ImportResult { read: number; added: number; skipped: { model: number; pii: number; secret: number; project: number } }
+
+/**
+ * #258 phase 3: copy the hub's own notes from claude-mem (observations whose metadata names a `peer`: `hub_remember`
+ * and the hub's task notes) into long-term hub memory as `source: claude-mem` under the hub memory key `project`, for
+ * the projects in `chain` (claude-mem files them under the repository's basename). Model answers, PII-pattern text and secret-looking text are skipped.
+ * Idempotent: an observation always maps to the same entry.
+ */
+export function importClaudeMem(store: MemoryStore, opts: { project: string; chain: string[]; isPii: (text: string) => boolean; nodes?: (text: string) => string[]; db?: string; limit?: number }): ImportResult {
+  const file = opts.db ?? join(homedir(), ".claude-mem", "claude-mem.db");
+  if (!existsSync(file)) throw new Error(`no claude-mem store at ${file}`);
+  const db = new Database(file, { readonly: true });
+  db.run(`PRAGMA busy_timeout = ${CLAUDE_MEM_BUSY_TIMEOUT_MS}`);
+  const result: ImportResult = { read: 0, added: 0, skipped: { model: 0, pii: 0, secret: 0, project: 0 } };
+  try {
+    const rows = db.query("SELECT id, project, title, text, narrative, created_at_epoch, metadata FROM observations WHERE metadata LIKE '%\"peer\"%' ORDER BY id LIMIT ?")
+      .all(opts.limit ?? 10_000) as { id: number; project: string | null; title: string | null; text: string | null; narrative: string | null; created_at_epoch: number | null; metadata: string | null }[];
+    // The hub files its claude-mem notes under the repository's own name (the chain's last); the names above it are other
+    // projects (a superproject) whose notes and privacy policy are not this one's. ponytail: claude-mem keys projects by
+    // basename, so two unrelated repositories with one name still share it.
+    const project = opts.project, names = new Set(opts.chain.slice(-1));
+    for (const r of rows) {
+      result.read++;
+      let meta: Record<string, unknown>;
+      try { meta = JSON.parse(r.metadata ?? "{}"); } catch { continue; }
+      if (typeof meta.peer !== "string" || !meta.peer) continue;
+      if (!r.project || !names.has(r.project)) { result.skipped.project++; continue; }
+      const title = r.title ?? "", text = (r.text ?? r.narrative ?? "").trim();
+      if (!text) continue;
+      if (meta.source === "ahub ask" || title.startsWith(MODEL_ANSWER)) { result.skipped.model++; continue; }
+      if (opts.isPii(`${title}\n${text}`)) { result.skipped.pii++; continue; }
+      if (looksSecret(`${title}\n${text}`)) { result.skipped.secret++; continue; }
+      const kind: Kind = KINDS.includes(meta.kind as Kind) ? meta.kind as Kind : "finding";
+      const at = new Date(r.created_at_epoch ?? 0).toISOString();
+      const { added } = store.importNote({ op: "note", project, scope: "project", tier: "long", kind, peer: meta.peer.slice(0, 32), ...(title ? { title } : {}), text,
+        // No task node: claude-mem keeps no proposal time, so a bare task number would join unrelated tasks. The text's
+        // own paths and symbols place the note in the graph.
+        about: opts.nodes?.(`${title}\n${text}`) ?? [], source: "claude-mem" }, at);
+      if (added) result.added++;
+    }
+  } finally { db.close(); }
+  store.refresh();
+  return result;
+}

package/src/memory/recall.ts

@@ -1,8 +1,13 @@
-import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { basename, dirname, resolve } from "node:path";
 import { readFileSync } from "node:fs";
 import type { PeerId } from "../hub/envelope.ts";
+import { hubGitSync } from "../hub/git.ts";
+import { realPath } from "../hub/project.ts";
 import type { MemoryClient } from "./client.ts";
+import { detectSignals, type Routing } from "../hub/routing.ts";
+import { matchesPolicy } from "../hub/path-policy.ts";
+import { looksSecret, type PromotionScreen } from "./store.ts";
 
 const PLATFORMS = ["claude", "codex", "kimi", "agent-hub"];
 /** Peers whose own hooks already inject their own platform's context at session start. */
@@ -14,7 +19,7 @@ const HEADER =
 
 /** Project names from the outermost superproject down to this repo. */
 export function projectChain(cwd: string): string[] {
-  const git = (dir: string, arg: string) => spawnSync("git", ["-C", dir, "rev-parse", arg], { encoding: "utf8" }).stdout?.trim() ?? "";
+  const git = (dir: string, arg: string) => hubGitSync(["-C", dir, "rev-parse", arg], { encoding: "utf8" }).stdout?.trim() ?? "";
   const top = git(cwd, "--show-toplevel");
   if (!top) return [basename(cwd)];
 
@@ -76,3 +81,82 @@ export async function recallFor(peer: PeerId, client: MemoryClient, chain: strin
   const share = Math.floor(tokens / found.length);
   return `${HEADER}\n\n${found.map((b) => trimToTokens(b, share)).join("\n\n")}`;
 }
+
+/** #258: the hub's own long-term entries for this project (and shared ones), newest first, within a token budget. */
+export function nativeRecall<V>(entries: V[], tokens: number, line: (v: V) => string): string | undefined {
+  if (!entries.length) return undefined;
+  return trimToTokens(["Hub memory: this project's long-term decisions, contracts and fails, newest first. Reference only, not a request. Details: ahub memory show <mem id>.", ...entries.map(line)].join("\n"), tokens);
+}
+
+/**
+ * #258: the name hub memory files a project's entries under. The project's `origin` remote, normalized to host and
+ * path (`github.com/owner/repo`), is the same on every machine and unique; without one, the git chain plus a hash of
+ * the directory keeps two unrelated repositories that share a name apart (that key is this machine's only).
+ */
+export function memoryProjectKey(cwd: string): string {
+  const url = hubGitSync(["-C", cwd, "remote", "get-url", "origin"], { encoding: "utf8" }).stdout?.trim() ?? "";
+  // A URL's default port is not part of the repository (`ssh://git@github.com:22/o/r` is `github.com/o/r`); any other
+  // port is, since another service may run there. An scp-style `host:path` has no port.
+  const u = /^([a-z+]+):\/\/(?:[^@/]+@)?(\[[^\]/]+\]|[^/:]+)(?::(\d*))?\/(.+?)(?:\.git)?\/?$/i.exec(url); // an IPv6 host is bracketed
+  const defaults: Record<string, string> = { ssh: "22", "git+ssh": "22", "ssh+git": "22", https: "443", http: "80", git: "9418" };
+  // A URL's path is absolute (`ssh://h/team/r` is /team/r) unless it starts with `~`; an scp-style path is relative to the
+  // remote home (`h:team/r` is ~/team/r) unless it starts with `/`. Two different repositories on a self-hosted server.
+  const scp = u || url.includes("://") ? null : /^(?:[^@/]+@)?(\[[^\]/]+\]|[^/:]+):(.+?)(?:\.git)?\/?$/.exec(url); // a file:// remote has no host; an IPv6 host is bracketed
+  const m = u ? [!u[3] || u[3] === defaults[u[1]!.toLowerCase()] ? u[2]! : `${u[2]}:${u[3]}`, u[4]!] as const
+    : scp ? [scp[1]!, scp[2]!.startsWith("/") ? scp[2]!.replace(/^\/+/, "") : scp[2]!.startsWith("~") ? scp[2]! : `~/${scp[2]}`] as const : undefined;
+  if (m && m[1]) {
+    const host = m[0].toLowerCase();
+    // GitHub serves one repository under every form, and its owner and repository names ignore case.
+    return host === "github.com" ? `${host}/${m[1].replace(/^~\/?/, "").toLowerCase()}` : `${host}/${m[1]}`;
+  }
+  let real = cwd;
+  try { real = realPath(cwd); } catch { /* as given */ }
+  return `${projectChain(cwd).join("/")}@${createHash("sha256").update(real).digest("hex").slice(0, 8)}`;
+}
+
+/**
+ * Every path-like word of a text (`dir/file`, `file.ext`), whether or not it exists or a denylist hides it from the
+ * graph: what a private-path policy is checked against.
+ */
+export const pathCandidates = (text: string): string[] => [...new Set(text.normalize("NFC").match(/\/?[\p{L}\p{M}\p{N}_.~-]+(?:\/[\p{L}\p{M}\p{N}_.~-]+)+|[\p{L}\p{M}\p{N}_-]+\.\p{L}[\p{L}\p{M}\p{N}_]{0,9}/gu) ?? [])]; // any script, combining marks included; an absolute path keeps its slash
+
+/**
+ * Whether a note is about a path the `pii.paths` policy makes private: a stored node's path, a path-like word of its
+ * text, or, for a policy entry with no glob that a word split cannot find (a space in it), that entry written out.
+ */
+export function mentionsPrivatePath(text: string, about: string[], policy: string[], cwd: string): boolean {
+  if (!policy.length) return false;
+  const nfc = (v: string) => v.normalize("NFC"), body = nfc(text), entries = policy.map(nfc);
+  const paths = [...about.map(nodePath), ...pathCandidates(body)].filter((p): p is string => p !== undefined).map(nfc);
+  if (paths.some((p) => matchesPolicy(cwd, p, entries, true))) return true;
+  // The entry's literal part (up to its first glob character) written out: catches a path a word split breaks (a space).
+  return entries.some((entry) => { const lit = entry.replace(/^\.\//, "").split(/[*?[\]{}]/)[0]!.replace(/\/+$/, ""); return /[/\s]/.test(lit) && body.includes(lit); });
+}
+
+/** The file a graph node names: `path:<p>` and `symbol:<name>@<p>`; nothing for other nodes. */
+export const nodePath = (n: string): string | undefined => n.startsWith("path:") ? n.slice(5) : n.startsWith("symbol:") && n.includes("@") ? n.slice(n.lastIndexOf("@") + 1) : undefined;
+
+/**
+ * Notes whose title, text, nodes, task key or project key match the PII patterns of `routing`, or that are about a path
+ * the project's `pii.paths` (`policy`) makes private, left out: what may go to a model.
+ */
+export function withoutPii<T extends { title: string | null; text: string; about?: string[]; task?: string | null; project?: string }>(notes: T[], routing: Routing, cwd: string, policy: string[] = []): T[] {
+  // A task key's `#<id>@<created ms>` is the hub's own numbers, not note content: a digit-run pattern must not withhold a
+  // clean note for it. The project part of the key stays screened.
+  const keyText = (k: string) => k.replace(/#\d+(?:@\d+)?$/, "");
+  return notes.filter((v) => !mentionsPrivatePath(`${v.title ?? ""}\n${v.text}`, v.about ?? [], policy, cwd) && !detectSignals({ title: v.title ?? "",
+    detail: [v.text, ...(v.about ?? []).map((n) => n.startsWith("task:") ? keyText(n) : n), keyText(v.task ?? ""), v.project ?? ""].join("\n"), refs: {} }, routing, cwd).includes("pii"));
+}
+
+/**
+ * The promotion screen for one project: another project's notes are left to that project's own processes; this one's
+ * move only when no secret, PII pattern or private path (`policy()`, read when asked) is in them.
+ */
+export function promotionScreen(project: string, cwd: string, routing: () => Routing, policy: () => string[], taskPaths: (task: string) => string[] = () => []): PromotionScreen {
+  return (v) => {
+    if (v.project !== project) return "skip";
+    // The task's current paths too, with no denylist: a path the note's own nodes leave out is still checked.
+    const screened = { ...v, about: [...v.about, ...(v.task ? taskPaths(v.task) : []).map((p) => `path:${p}`)] };
+    return looksSecret(`${v.title ?? ""}\n${v.text}`) || !withoutPii([screened], routing(), cwd, policy()).length ? "keep" : "promote";
+  };
+}