petbox-wire 0.1.0-ci.1206

package/src/apply-root.test.ts

@@ -0,0 +1,148 @@
+// Unit + integration tests for the apply target-directory fix
+// (bug: apply-root-overwrites-primary-worktree).
+//
+// Run: node --test src/apply-root.test.ts
+
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { defaultGitToplevel, resolveApplyRoot } from "./apply-root.ts";
+
+function freshDir(): string {
+  // realpathSync so Windows short-path / symlink quirks in TMP don't make string comparisons
+  // against `git rev-parse --show-toplevel`'s output flaky.
+  return realpathSync(mkdtempSync(join(tmpdir(), "petbox-apply-root-")));
+}
+
+function norm(p: string): string {
+  return p.replace(/\\/g, "/").replace(/\/+$/, "").toLowerCase();
+}
+
+function hasGit(): boolean {
+  try {
+    execFileSync("git", ["--version"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ---- pure unit tests (injected gitToplevel — no real git process) ----
+
+test("resolveApplyRoot: uses the injected git toplevel and reports via 'git'", () => {
+  const result = resolveApplyRoot("/some/cwd", () => "/some/toplevel");
+  assert.deepEqual(result, { root: "/some/toplevel", via: "git" });
+});
+
+test("resolveApplyRoot: falls back to cwd (via 'cwd') when git resolution returns null", () => {
+  const result = resolveApplyRoot("/some/cwd", () => null);
+  assert.deepEqual(result, { root: "/some/cwd", via: "cwd" });
+});
+
+test("resolveApplyRoot: NEVER consults a registry — identical cwd/root regardless of any external prefix table", () => {
+  // The whole point of the fix: no registry longest-prefix matching happens here at all. The
+  // injected gitToplevel is the only source of truth for the target directory.
+  const result = resolveApplyRoot("/registered/prefix/worktree/x", () => "/registered/prefix/worktree/x");
+  assert.equal(result.root, "/registered/prefix/worktree/x");
+  assert.equal(result.via, "git");
+});
+
+// ---- defaultGitToplevel against a REAL git process ----
+
+test("defaultGitToplevel: a plain non-git directory resolves to null", (t) => {
+  if (!hasGit()) {
+    t.skip("git not on PATH");
+    return;
+  }
+  const dir = freshDir();
+  try {
+    // A tmp dir is not expected to be inside this repo's tree; guard just in case.
+    const top = defaultGitToplevel(dir);
+    if (top !== null) {
+      t.skip(`environment surprise: ${dir} resolved inside a git tree (${top}) — skipping`);
+      return;
+    }
+    assert.equal(top, null);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("defaultGitToplevel: a git repo resolves to its own toplevel, from a nested subdir too", (t) => {
+  if (!hasGit()) {
+    t.skip("git not on PATH");
+    return;
+  }
+  const dir = freshDir();
+  try {
+    execFileSync("git", ["init", "-q"], { cwd: dir });
+    const top = defaultGitToplevel(dir);
+    assert.ok(top, "expected a toplevel for a freshly-init'd repo");
+    assert.equal(norm(top!), norm(dir));
+
+    const nested = join(dir, "a", "b", "c");
+    mkdirSync(nested, { recursive: true });
+    const topFromNested = defaultGitToplevel(nested);
+    assert.equal(norm(topFromNested!), norm(dir), "toplevel from a nested subdir must still be the repo root");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// ---- the actual regression: worktree under a REGISTERED PRIMARY prefix must resolve to itself ----
+
+test("resolveApplyRoot regression: apply from a real git worktree resolves to the WORKTREE, not the primary tree it was branched from", (t) => {
+  if (!hasGit()) {
+    t.skip("git not on PATH");
+    return;
+  }
+  const primary = freshDir();
+  let worktree: string | null = null;
+  try {
+    execFileSync("git", ["init", "-q"], { cwd: primary });
+    execFileSync("git", ["config", "user.email", "test@example.com"], { cwd: primary });
+    execFileSync("git", ["config", "user.name", "Test"], { cwd: primary });
+    writeFileSync(join(primary, "README.md"), "primary\n", "utf8");
+    execFileSync("git", ["add", "."], { cwd: primary });
+    execFileSync("git", ["commit", "-q", "-m", "init"], { cwd: primary });
+
+    // A worktree living UNDER the primary tree's own filesystem prefix — the exact shape that
+    // triggered the bug: a registry entry for `primary` would longest-prefix-match this path too.
+    worktree = join(primary, ".claude", "worktrees", "agent-x");
+    mkdirSync(join(primary, ".claude", "worktrees"), { recursive: true });
+    execFileSync("git", ["worktree", "add", "-q", "-b", "agent-x-branch", worktree], { cwd: primary });
+
+    // Simulate the OLD buggy behavior for contrast: a registry longest-prefix match for a
+    // `primary` entry would have returned `primary` for a cwd under it. The FIXED resolver must
+    // not do that — it must answer with the worktree itself.
+    const fromWorktree = resolveApplyRoot(worktree);
+    assert.equal(fromWorktree.via, "git");
+    assert.equal(
+      norm(fromWorktree.root),
+      norm(worktree),
+      "apply run from the worktree must target the worktree, never the primary tree",
+    );
+    assert.notEqual(
+      norm(fromWorktree.root),
+      norm(primary),
+      "must NOT resolve to the primary tree just because the worktree sits under its filesystem prefix",
+    );
+
+    // And apply from the primary tree itself still resolves to the primary tree — this isn't a
+    // "worktree always wins" hack, it's "git toplevel for THIS cwd, whichever tree that is".
+    const fromPrimary = resolveApplyRoot(primary);
+    assert.equal(norm(fromPrimary.root), norm(primary));
+  } finally {
+    if (worktree && existsSync(worktree)) {
+      try {
+        execFileSync("git", ["worktree", "remove", "-f", worktree], { cwd: primary });
+      } catch {
+        /* best-effort cleanup */
+      }
+    }
+    rmSync(primary, { recursive: true, force: true });
+  }
+});

package/src/apply-root.ts

@@ -0,0 +1,68 @@
+// Target directory resolution for petbox-wire apply (wiring-registry-resolve).
+//
+// Two DIFFERENT questions get answered by two DIFFERENT mechanisms — conflating them was the
+// bug (apply-root-overwrites-primary-worktree):
+//   - PROJECT IDENTITY (projectKey / baseUrl / apiKey) comes from the registry
+//     (~/.petbox/projects.json), longest-prefix match — see registry.ts's resolveProject.
+//   - the ARTIFACT TARGET DIRECTORY (where apply writes .claude/agents/, .opencode/agent/,
+//     .factory/droids/) is the git worktree apply is actually running in.
+//
+// Before this fix, resolveApplyRoot ALSO used the registry's longest-prefix match to pick the
+// target directory. A worktree living under a registered prefix (e.g.
+// `<registered>/.claude/worktrees/agent-x`) resolved its apply root to the REGISTERED prefix —
+// the PRIMARY tree — not the worktree apply was invoked from. `apply` run from inside a worktree
+// silently rewrote the primary tree's `.claude/agents/*`, which may be checked out on an
+// entirely different branch (a live, hostile side effect on someone else's working copy).
+//
+// Fix: the artifact root is git's own toplevel for cwd, full stop — no registry involved.
+// Falls back to cwd when cwd is not inside a git working tree at all (plain directory, or a
+// git binary that is missing/fails) — same "no better answer, use cwd" fallback the old code
+// already had for the "no registry entry" case.
+//
+// Plain TS for native node type-stripping: zero deps beyond node:child_process.
+
+import { execFileSync } from "node:child_process";
+
+export type ApplyRootVia = "git" | "cwd";
+
+export type ApplyRootResolution = {
+  readonly root: string;
+  readonly via: ApplyRootVia;
+};
+
+/**
+ * Default git toplevel probe: `git rev-parse --show-toplevel` from cwd. Returns null on ANY
+ * failure — cwd is not inside a git working tree, `git` is not on PATH, a bare/detached repo
+ * that cannot resolve a toplevel, etc. Never throws (mirrors registry.ts's resolveProject
+ * never-throws contract for the same reason: this runs inside a CLI step that must not crash
+ * just because cwd happens to be a plain, non-git directory).
+ */
+export function defaultGitToplevel(cwd: string): string | null {
+  try {
+    const out = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    const trimmed = out.trim();
+    return trimmed.length > 0 ? trimmed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve WHERE `apply` writes artifacts: the git worktree toplevel for cwd, or cwd itself when
+ * cwd is not inside a git working tree. Deliberately does NOT consult the registry — the
+ * registry answers project IDENTITY, not artifact location (see module comment). `gitToplevel`
+ * is injectable so tests never have to shell out to a real git process to exercise the pure
+ * fallback branch.
+ */
+export function resolveApplyRoot(
+  cwd: string,
+  gitToplevel: (cwd: string) => string | null = defaultGitToplevel,
+): ApplyRootResolution {
+  const top = gitToplevel(cwd);
+  if (top) return { root: top, via: "git" };
+  return { root: cwd, via: "cwd" };
+}

package/src/apply-write.test.ts

@@ -0,0 +1,169 @@
+// Unit tests for the apply write guard (bug: apply-clobbers-user-agent-files) and the
+// namespacing-rename legacy cleanup it enables (chore: petbox-namespaced-agent-names).
+//
+// Run: node --test src/apply-write.test.ts
+
+import assert from "node:assert/strict";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { renderAgentMarkdown } from "./apply-artifacts.ts";
+import { cleanupLegacyArtifact, writeArtifact } from "./apply-write.ts";
+import { DEFAULT_AGENT_DEFINITION } from "./agent-definition.ts";
+import { hasPetboxMarker, PETBOX_MARKER_LINE } from "./origin-marker.ts";
+
+function freshDir(): string {
+  return mkdtempSync(join(tmpdir(), "petbox-apply-write-"));
+}
+
+test("hasPetboxMarker: true only for our marker inside frontmatter, never body text", () => {
+  assert.equal(hasPetboxMarker(`---\nname: x\n${PETBOX_MARKER_LINE}\n---\n\nbody`), true);
+  assert.equal(hasPetboxMarker(`---\nname: x\n---\n\nbody mentions petbox: managed here`), false);
+  assert.equal(hasPetboxMarker("no frontmatter at all"), false);
+  assert.equal(hasPetboxMarker(""), false);
+});
+
+test("writeArtifact: fresh path (no existing file) is written, reason 'new'", () => {
+  const dir = freshDir();
+  try {
+    const abs = join(dir, "sub", "petbox-worker.md");
+    const outcome = writeArtifact(abs, "hello");
+    assert.deepEqual(outcome, { kind: "written", path: abs, reason: "new" });
+    assert.equal(readFileSync(abs, "utf8"), "hello");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("writeArtifact: an existing file WITHOUT our marker is refused — content untouched, loud outcome", () => {
+  const dir = freshDir();
+  try {
+    const abs = join(dir, "worker.md");
+    const foreignContent = "# My own worker agent\n\nI wrote this by hand.\n";
+    writeFileSync(abs, foreignContent, "utf8");
+
+    const outcome = writeArtifact(abs, "petbox content");
+    assert.deepEqual(outcome, { kind: "blocked", path: abs });
+    // The file must be byte-for-byte exactly what the user had — apply never touches it.
+    assert.equal(readFileSync(abs, "utf8"), foreignContent);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("writeArtifact: an existing file WITH our marker is overwritten silently (routine re-apply)", () => {
+  const dir = freshDir();
+  try {
+    const abs = join(dir, "petbox-worker.md");
+    const oldOurs = `---\nname: petbox-worker\n${PETBOX_MARKER_LINE}\n---\n\nold body\n`;
+    writeFileSync(abs, oldOurs, "utf8");
+
+    const newContent = `---\nname: petbox-worker\n${PETBOX_MARKER_LINE}\n---\n\nnew body\n`;
+    const outcome = writeArtifact(abs, newContent);
+    assert.deepEqual(outcome, { kind: "written", path: abs, reason: "own" });
+    assert.equal(readFileSync(abs, "utf8"), newContent);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("writeArtifact: an existing marker-carrying file for a DIFFERENT role is still ours — overwritten (marker is the only signal)", () => {
+  // Documents the guard's actual contract: it trusts the marker, not path/name matching.
+  const dir = freshDir();
+  try {
+    const abs = join(dir, "petbox-worker.md");
+    writeFileSync(abs, `---\nname: petbox-utility\n${PETBOX_MARKER_LINE}\n---\n\nstale\n`, "utf8");
+    const outcome = writeArtifact(abs, "fresh");
+    assert.equal(outcome.kind, "written");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("cleanupLegacyArtifact: absent path → 'absent', no-op", () => {
+  const dir = freshDir();
+  try {
+    assert.equal(cleanupLegacyArtifact(join(dir, "worker.md")), "absent");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("cleanupLegacyArtifact: an OWNED pre-rename file is removed", () => {
+  const dir = freshDir();
+  try {
+    const abs = join(dir, "worker.md");
+    writeFileSync(abs, `---\nname: worker\n${PETBOX_MARKER_LINE}\n---\n\nold pre-rename body\n`, "utf8");
+    assert.equal(cleanupLegacyArtifact(abs), "removed");
+    assert.equal(existsSync(abs), false);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("cleanupLegacyArtifact: a FOREIGN file at the legacy path is left alone — never deleted", () => {
+  const dir = freshDir();
+  try {
+    const abs = join(dir, "worker.md");
+    const foreign = "# a real user agent named worker, no marker\n";
+    writeFileSync(abs, foreign, "utf8");
+    assert.equal(cleanupLegacyArtifact(abs), "kept-foreign");
+    assert.equal(existsSync(abs), true);
+    assert.equal(readFileSync(abs, "utf8"), foreign);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// --- end-to-end-ish: a real renderAgentMarkdown output round-trips through the guard ---
+
+test("a freshly rendered role file always carries the marker, so a second apply run is a silent no-op re-write", () => {
+  const role = DEFAULT_AGENT_DEFINITION.roles.find((r) => r.slug === "worker")!;
+  const content = renderAgentMarkdown(role);
+  assert.ok(hasPetboxMarker(content));
+
+  const dir = freshDir();
+  try {
+    const abs = join(dir, "petbox-worker.md");
+    const first = writeArtifact(abs, content);
+    assert.equal(first.kind, "written");
+    assert.equal(first.reason, "new");
+
+    const second = writeArtifact(abs, content);
+    assert.equal(second.kind, "written");
+    assert.equal(second.reason, "own");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("simulated apply flow: a real user's own worker.md survives the FIRST apply that now writes petbox-worker.md alongside it", () => {
+  // This is the scenario from the bug report: a friend has their own .claude/agents/worker.md.
+  // apply now writes .claude/agents/petbox-worker.md (namespacing) and must neither touch nor
+  // delete the user's worker.md (it has no marker, so it is never mistaken for a pre-rename
+  // leftover of OURS either).
+  const role = DEFAULT_AGENT_DEFINITION.roles.find((r) => r.slug === "worker")!;
+  const content = renderAgentMarkdown(role);
+
+  const dir = freshDir();
+  try {
+    const agentsDir = join(dir, ".claude", "agents");
+    mkdirSync(agentsDir, { recursive: true });
+    const userFile = join(agentsDir, "worker.md");
+    const userContent = "# worker\n\nMy hand-written worker agent. Do not touch.\n";
+    writeFileSync(userFile, userContent, "utf8");
+
+    const newAbs = join(agentsDir, "petbox-worker.md");
+    const writeOutcome = writeArtifact(newAbs, content);
+    assert.equal(writeOutcome.kind, "written");
+
+    // Legacy cleanup targets the bare name — but it is NOT ours (no marker), so it must survive.
+    const legacyOutcome = cleanupLegacyArtifact(userFile);
+    assert.equal(legacyOutcome, "kept-foreign");
+    assert.equal(readFileSync(userFile, "utf8"), userContent, "user's own file must be untouched");
+    assert.equal(readFileSync(newAbs, "utf8"), content);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/src/apply-write.ts

@@ -0,0 +1,84 @@
+// Filesystem writer for petbox-wire apply's PlannedFiles.
+//
+// Kept out of apply-artifacts.ts (which stays pure / filesystem-free by its own contract —
+// "Does not touch the filesystem") and out of wire.ts (whose main() runs at import time, so
+// helpers that need to be unit-testable in isolation live in a side module — same pattern as
+// posix-env.ts).
+//
+// The whole point (bug: apply-clobbers-user-agent-files): before this module existed, apply's
+// write loop was an unconditional writeFileSync — no existence check, no origin marker, no
+// refusal. A user's own `.claude/agents/worker.md` was destroyed on the first `apply` with zero
+// warning. writeArtifact fixes that with ONE rule: an existing file is only ever overwritten
+// when it already carries OUR origin marker (origin-marker.ts); anything else is refused, loud,
+// non-zero exit at the call site — never partially touched.
+//
+// cleanupLegacyArtifact is the companion used by the namespaced-agent-names rename
+// (petbox-namespaced-agent-names): once role files are emitted under a new `petbox-<slug>`
+// name, the OLD unprefixed file (e.g. `.claude/agents/worker.md`) would otherwise be left
+// behind as an orphan. It is only ever removed when it carries our marker — a real user file
+// that happens to share the old bare name is left alone, exactly like writeArtifact.
+//
+// Plain TS for native node type-stripping: zero deps.
+
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { hasPetboxMarker } from "./origin-marker.ts";
+
+export type WriteOutcome =
+  | { readonly kind: "written"; readonly path: string; readonly reason: "new" | "own" }
+  | { readonly kind: "blocked"; readonly path: string };
+
+/**
+ * Write one generated file to `absPath`.
+ *  - Path does not exist → write it (reason "new").
+ *  - Path exists and its frontmatter carries our origin marker → overwrite silently
+ *    (reason "own") — this is the routine, expected re-apply case.
+ *  - Path exists and does NOT carry our marker (a real file we did not create, or one we
+ *    cannot even read) → refuse. Returns "blocked"; the file is left byte-for-byte untouched.
+ * Never throws for the ordinary cases above (a directory-creation failure still throws — that
+ * is a genuine environment error, not a clobber decision).
+ */
+export function writeArtifact(absPath: string, content: string): WriteOutcome {
+  const existed = existsSync(absPath);
+  if (existed) {
+    let existing: string;
+    try {
+      existing = readFileSync(absPath, "utf8");
+    } catch {
+      // Unreadable existing entry (permissions, a directory, binary junk, ...) — treat as
+      // foreign rather than guess; never overwrite something we could not even inspect.
+      return { kind: "blocked", path: absPath };
+    }
+    if (!hasPetboxMarker(existing)) {
+      return { kind: "blocked", path: absPath };
+    }
+  }
+  mkdirSync(dirname(absPath), { recursive: true });
+  writeFileSync(absPath, content, "utf8");
+  return {
+    kind: "written",
+    path: absPath,
+    reason: existed ? "own" : "new",
+  };
+}
+
+export type LegacyCleanupOutcome = "removed" | "kept-foreign" | "absent";
+
+/**
+ * Remove an old, pre-namespacing artifact at `absPath` IF AND ONLY IF it carries our origin
+ * marker. Returns "absent" when there is nothing there (the common steady-state case once
+ * migration has run once), "removed" when an owned leftover was deleted, "kept-foreign" when
+ * something exists there that is NOT ours — left untouched, never deleted, never renamed.
+ */
+export function cleanupLegacyArtifact(absPath: string): LegacyCleanupOutcome {
+  if (!existsSync(absPath)) return "absent";
+  let existing: string;
+  try {
+    existing = readFileSync(absPath, "utf8");
+  } catch {
+    return "kept-foreign";
+  }
+  if (!hasPetboxMarker(existing)) return "kept-foreign";
+  unlinkSync(absPath);
+  return "removed";
+}

package/src/canon.ts

@@ -0,0 +1,140 @@
+// Shared memory-canon fetch + offline cache — the ONE implementation both SessionStart hooks
+// (pull-memory.ts for Claude Code, opencode-plugin.ts for opencode) use, so the injected canon
+// block is byte-identical across agents (spec: agent-wiring, wiring-canon-inject).
+//
+// The server exposes the curated memory index (canon) at
+//   GET {baseUrl}/api/memory/{project}/canon   (header X-Api-Key)
+//   → 200 { "project": {body,updatedAt,version}|null, "workspace": {...}|null }
+// We turn that into a markdown block appended to the session context. On any failure we fall
+// back to a local cache (~/.petbox/cache/{project}.canon.md) written on the last good fetch,
+// marked stale. This is best-effort and TOTAL: every path returns string | null, never throws.
+//
+// NOTE: production may not have this endpoint yet — a 404/error degrades gracefully (no canon
+// block, the memory protocol is still injected by the caller).
+//
+// Plain TS for native node type-stripping: no enum/namespace/parameter-properties, type-only
+// imports, zero deps.
+
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { ResolvedProject } from "./registry.ts";
+
+const FETCH_TIMEOUT_MS = 8000;
+
+const STALE_MARKER = "⚠ Canon below is from the local cache (PetBox unreachable) — may be stale.";
+
+type CanonPart = { body?: unknown; updatedAt?: unknown; version?: unknown };
+type CanonResponse = { project?: CanonPart | null; workspace?: CanonPart | null };
+
+function cacheDir(): string {
+  return join(homedir(), ".petbox", "cache");
+}
+
+function cachePath(project: string): string {
+  return join(cacheDir(), `${project}.canon.md`);
+}
+
+// Pull a usable markdown body out of a canon part, or null when the part is missing/empty.
+function partBody(part: CanonPart | null | undefined): string | null {
+  if (!part || typeof part.body !== "string") return null;
+  const body = part.body.trim();
+  return body.length > 0 ? body : null;
+}
+
+// Assemble the canon block from the two parts. Returns null when both are empty.
+function buildBlock(project: string, resp: CanonResponse | null): string | null {
+  if (!resp) return null;
+  const projectBody = partBody(resp.project);
+  const workspaceBody = partBody(resp.workspace);
+  if (projectBody === null && workspaceBody === null) return null;
+
+  let out = `## PetBox memory canon
+
+The curated memory index (canon) for this project — pointers to durable facts; pull full bodies via memory_get/memory_search.`;
+  if (projectBody !== null) {
+    out += `\n\n### Project (${project})\n\n${projectBody}`;
+  }
+  if (workspaceBody !== null) {
+    out += `\n\n### Workspace\n\n${workspaceBody}`;
+  }
+  return out;
+}
+
+// Returns { ok: true, resp } on a successful HTTP fetch (resp may still carry empty canon),
+// or { ok: false } on any failure (404 endpoint-absent / 401 / 5xx / network / timeout / bad
+// JSON) — the caller uses ok to decide whether to fall back to the stale offline cache.
+async function fetchCanon(
+  resolved: ResolvedProject,
+  timeoutMs: number = FETCH_TIMEOUT_MS,
+): Promise<{ ok: true; resp: CanonResponse | null } | { ok: false }> {
+  const ctrl = new AbortController();
+  // timeoutMs <= 0 (budget already exhausted by a prior sequential fetch, e.g. pull-memory.ts's
+  // shared session-start budget) aborts on the next tick — same effect as skipping the network
+  // call, degrading straight to the offline cache below rather than blocking.
+  const timer = setTimeout(() => ctrl.abort(), Math.max(0, timeoutMs));
+  try {
+    const url = `${resolved.baseUrl}/api/memory/${resolved.project}/canon`;
+    const resp = await fetch(url, {
+      method: "GET",
+      // Connection: close so this socket doesn't linger keep-alive after the response —
+      // a SessionStart/Stop hook process exits right after this fetch, and a kept-alive
+      // socket is a libuv handle that either stalls natural process exit for seconds or
+      // races a forced process.exit() against the handle's own close teardown (the crash
+      // this header exists to prevent; see pull-memory.ts's exit comment).
+      headers: { "X-Api-Key": resolved.apiKey, Connection: "close" },
+      signal: ctrl.signal,
+    });
+    if (!resp.ok) return { ok: false }; // 404 (endpoint absent) / 401 / 5xx → degrade to cache
+    const j = (await resp.json().catch(() => null)) as CanonResponse | null;
+    return { ok: true, resp: j };
+  } catch {
+    return { ok: false }; // network/timeout → degrade to cache
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function writeCache(project: string, block: string): Promise<void> {
+  try {
+    await mkdir(cacheDir(), { recursive: true });
+    await writeFile(cachePath(project), block, "utf8");
+  } catch {
+    // best-effort: a failed cache write must not affect the returned block
+  }
+}
+
+async function readCache(project: string): Promise<string | null> {
+  try {
+    const body = await readFile(cachePath(project), "utf8");
+    return body.trim().length > 0 ? body : null;
+  } catch {
+    return null; // no cache file yet
+  }
+}
+
+// Build the canon block for a resolved project. On a successful fetch the fresh block is
+// cached and returned; on failure a cached block (if any) is returned PREFIXED with a stale
+// marker. Returns null when there is nothing to show (fetch failed AND no cache, or both
+// canon parts are empty). Never throws.
+export async function fetchCanonBlock(
+  resolved: ResolvedProject,
+  opts?: { timeoutMs?: number },
+): Promise<string | null> {
+  try {
+    const result = await fetchCanon(resolved, opts?.timeoutMs);
+    if (result.ok) {
+      // Successful fetch — the server is authoritative. A real block is cached and returned;
+      // an empty canon returns null (do NOT show a stale cache when the server says "nothing").
+      const block = buildBlock(resolved.project, result.resp);
+      if (block !== null) await writeCache(resolved.project, block);
+      return block;
+    }
+    // Fetch failed (endpoint absent / unreachable) → fall back to the offline cache if present.
+    const cached = await readCache(resolved.project);
+    if (cached !== null) return `${STALE_MARKER}\n\n${cached}`;
+    return null;
+  } catch {
+    return null; // total: any unexpected error → no canon block
+  }
+}