petbox-wire 0.1.0-ci.1206

package/src/protocol.test.ts

@@ -0,0 +1,236 @@
+// Protocol inject: memory always; spawn prescriptions when harness has spawn_subagents.
+//
+// Run: node --test src/protocol.test.ts
+
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { resolveAgentDefinitionForSession } from "./agent-def-fetch.ts";
+import { DEFAULT_AGENT_DEFINITION, type AgentDefinition } from "./agent-definition.ts";
+import {
+  buildProtocol,
+  mcpPetboxTool,
+  orchestrationPrescriptionsAllowed,
+} from "./protocol.ts";
+
+const project = "demo";
+
+function freshHome(): string {
+  return mkdtempSync(join(tmpdir(), "petbox-protocol-"));
+}
+
+const SERVER_BODY = {
+  key: "default",
+  version: 7,
+  definition: {
+    name: "server-roster",
+    roles: [
+      {
+        slug: "orchestrator",
+        tier: "orchestrator",
+        requiredCapabilities: ["mcp_main_session", "spawn_subagents"],
+        spawn: { allowed: true, allowedRoles: ["worker"] },
+        escalation: { available: true, targets: ["reserve"] },
+        notes: "SERVER-AUTHORED-ORCHESTRATOR-NOTES-xyz789",
+      },
+    ],
+  },
+};
+
+test("orchestrationPrescriptionsAllowed tracks spawn_subagents for all three harnesses", () => {
+  assert.equal(orchestrationPrescriptionsAllowed("claude-code"), true);
+  assert.equal(orchestrationPrescriptionsAllowed("opencode"), true);
+  // Factory Task tool on main session — https://docs.factory.ai/cli/configuration/custom-droids
+  assert.equal(orchestrationPrescriptionsAllowed("droid"), true);
+  assert.equal(orchestrationPrescriptionsAllowed(undefined), false);
+  assert.equal(orchestrationPrescriptionsAllowed("unknown"), false);
+});
+
+test("buildProtocol for droid CONTAINS spawn/orchestrator prose (Factory spawns via Task)", () => {
+  const text = buildProtocol(project, mcpPetboxTool, { harness: "droid" });
+  const lower = text.toLowerCase();
+  assert.ok(
+    lower.includes("spawn workers") || lower.includes("delegate by default"),
+    `droid protocol must prescribe spawn/delegate:\n${text}`,
+  );
+  assert.match(text, /orchestrator/i);
+  assert.match(text, /PetBox memory active/);
+  assert.match(text, /search before rework/i);
+  // Must not fall back to "· main" no-spawn self-intro
+  assert.ok(!lower.includes("· main"), `droid must not use no-spawn main intro:\n${text}`);
+});
+
+test("buildProtocol for claude-code / opencode MUST contain spawn/delegate language", () => {
+  for (const harness of ["claude-code", "opencode"] as const) {
+    const text = buildProtocol(project, mcpPetboxTool, { harness });
+    const lower = text.toLowerCase();
+    assert.ok(
+      lower.includes("spawn workers") || lower.includes("delegate by default"),
+      `${harness} protocol must prescribe spawn/delegate:\n${text}`,
+    );
+    assert.match(text, /orchestrator/i);
+    assert.match(text, /plan, decompose, delegate|Orchestrator notes/i);
+  }
+});
+
+test("buildProtocol without harness omits spawn prescriptions (safe default)", () => {
+  const text = buildProtocol(project, mcpPetboxTool);
+  const lower = text.toLowerCase();
+  assert.ok(!lower.includes("spawn workers"));
+  assert.ok(!lower.includes("delegate by default"));
+});
+
+// --- petbox-namespaced-agent-names: the literal spawn-target string in the orchestrator
+// self-intro must be the COMPUTED, namespaced identity (apply-artifacts.ts's emittedRoleName),
+// never a hardcoded `worker` constant — that was exactly the bug at protocol.ts:62 (a third
+// source of truth that could drift from the actual .claude/agents/petbox-worker.md apply emits). ---
+
+test("buildProtocol's orchestrator self-intro tells it to spawn the NAMESPACED worker name, not a bare `worker` constant", () => {
+  for (const harness of ["claude-code", "opencode", "droid"] as const) {
+    const text = buildProtocol(project, mcpPetboxTool, { harness });
+    assert.match(text, /Spawn as `petbox-worker`/, `${harness}: must render the computed emitted name`);
+    assert.ok(!text.includes("Spawn as `worker`"), `${harness}: must not hardcode the bare slug`);
+  }
+});
+
+test("buildProtocol computes the spawn-target name from the SUPPLIED definition, not a constant", () => {
+  // A definition whose worker role has a different internal slug still renders correctly —
+  // proves the name is computed per-definition, not baked into protocol.ts as a literal string.
+  const custom: AgentDefinition = {
+    name: "custom-roster",
+    roles: [
+      { slug: "orchestrator", tier: "orchestrator", requiredCapabilities: [] },
+      { slug: "worker", tier: "worker", requiredCapabilities: [] },
+    ],
+  };
+  const text = buildProtocol(project, mcpPetboxTool, { harness: "claude-code", definition: custom });
+  assert.match(text, /Spawn as `petbox-worker`/);
+});
+
+test("buildProtocol falls back to petbox-worker when the supplied definition has no worker role (never crashes)", () => {
+  const noWorker: AgentDefinition = {
+    name: "no-worker",
+    roles: [{ slug: "orchestrator", tier: "orchestrator", requiredCapabilities: [] }],
+  };
+  const text = buildProtocol(project, mcpPetboxTool, { harness: "claude-code", definition: noWorker });
+  assert.match(text, /Spawn as `petbox-worker`/);
+});
+
+// --- kit-prose-contradicts-server-definition: the kit banner must DELIVER role/model
+// semantics from the server definition's notes, never assert its own competing version.
+// Regression guard for two prose bugs that contradicted the definition inside the SAME
+// injected banner: (1) telling the orchestrator to dictate a subagent's self-intro, which
+// the definition's rule 5 explicitly forbids (the subagent's own self-report is the only
+// evidence of what actually ran — a dictated line turns signal into echo); (2) pointing at
+// a "worker preamble" that doesn't exist anywhere else in the kit. ---
+
+test("buildProtocol's orchestrator self-intro no longer tells the orchestrator to dictate a subagent's self-intro", () => {
+  for (const harness of ["claude-code", "opencode", "droid"] as const) {
+    const text = buildProtocol(project, mcpPetboxTool, { harness });
+    assert.ok(
+      !text.includes("write their self-intro into the brief"),
+      `${harness}: kit must not instruct dictating a subagent's self-intro:\n${text}`,
+    );
+  }
+});
+
+test("buildProtocol does not reference a nonexistent 'worker preamble'", () => {
+  for (const harness of ["claude-code", "opencode", "droid"] as const) {
+    const text = buildProtocol(project, mcpPetboxTool, { harness });
+    assert.ok(
+      !/worker preamble/i.test(text),
+      `${harness}: kit must not promise a "worker preamble" the kit never defines:\n${text}`,
+    );
+  }
+});
+
+// --- definition-driven banner (wiring-startup-symmetry: main-loop banner must resolve the
+// portable definition the same way `apply` does — server → LKG → built-in default) ---
+
+test("buildProtocol renders orchestrator notes from an explicitly-supplied definition", () => {
+  const custom: AgentDefinition = {
+    name: "custom-roster",
+    roles: [
+      {
+        slug: "orchestrator",
+        tier: "orchestrator",
+        requiredCapabilities: [],
+        notes: "CUSTOM-SERVER-NOTES-abc123",
+      },
+    ],
+  };
+  const text = buildProtocol(project, mcpPetboxTool, { harness: "claude-code", definition: custom });
+  assert.match(text, /CUSTOM-SERVER-NOTES-abc123/);
+  const defaultOrchestratorNotes = DEFAULT_AGENT_DEFINITION.roles.find(
+    (r) => r.slug === "orchestrator",
+  )?.notes;
+  assert.ok(
+    !text.includes(defaultOrchestratorNotes ?? " "),
+    "must not also carry the built-in default's notes once a definition is supplied",
+  );
+});
+
+test("buildProtocol falls back to the built-in DEFAULT_AGENT_DEFINITION notes when no definition is supplied", () => {
+  const text = buildProtocol(project, mcpPetboxTool, { harness: "claude-code" });
+  const defaultOrchNotes = DEFAULT_AGENT_DEFINITION.roles.find((r) => r.slug === "orchestrator")?.notes;
+  assert.ok(defaultOrchNotes, "fixture assumption: DEFAULT_AGENT_DEFINITION has orchestrator notes");
+  assert.ok(text.includes(defaultOrchNotes!));
+});
+
+// --- end-to-end: resolveAgentDefinitionForSession (server → LKG → DEFAULT) feeding buildProtocol,
+// the same wiring pull-memory.ts / droid-pull-memory.ts / opencode-plugin.ts now use. ---
+
+test("SessionStart banner renders server-supplied definition when the server answers", async () => {
+  const home = freshHome();
+  try {
+    const got = await resolveAgentDefinitionForSession(
+      { project: "proj", baseUrl: "https://petbox.example", apiKey: "k" },
+      {
+        homeDir: home,
+        fetchImpl: async () =>
+          new Response(JSON.stringify(SERVER_BODY), {
+            status: 200,
+            headers: { "Content-Type": "application/json" },
+          }),
+      },
+    );
+    assert.equal(got.source, "server");
+    const text = buildProtocol("proj", mcpPetboxTool, {
+      harness: "claude-code",
+      definition: got.definition,
+    });
+    assert.match(text, /SERVER-AUTHORED-ORCHESTRATOR-NOTES-xyz789/);
+    assert.match(text, /PetBox memory active/);
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("SessionStart banner falls back to the built-in default when neither server nor LKG cache is available (never crashes, never empty)", async () => {
+  const home = freshHome(); // fresh dir → guaranteed no LKG cache file
+  try {
+    const got = await resolveAgentDefinitionForSession(
+      { project: "proj", baseUrl: "https://petbox.example", apiKey: "k" },
+      {
+        homeDir: home,
+        fetchImpl: async () => {
+          throw new Error("ECONNREFUSED");
+        },
+      },
+    );
+    assert.equal(got.source, "default");
+    assert.equal(got.definition, DEFAULT_AGENT_DEFINITION);
+
+    const text = buildProtocol("proj", mcpPetboxTool, {
+      harness: "claude-code",
+      definition: got.definition,
+    });
+    assert.ok(text.length > 0, "banner must never be empty");
+    assert.match(text, /PetBox memory active/);
+    assert.match(text, /orchestrator/i);
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});

package/src/protocol.ts

@@ -0,0 +1,136 @@
+// Shared PetBox memory-protocol builder — the ONE implementation every SessionStart injector
+// renders from (pull-memory.ts for Claude Code, opencode-plugin.ts for opencode,
+// droid-pull-memory.ts for Factory Droid), so the protocol text can no longer drift between
+// agents as hand-synced copies (spec: agent-wiring, wiring-single-source).
+//
+// The ONLY thing that varies per agent is how an MCP tool is named: pass a `tool` mapper that
+// turns a bare verb (e.g. "memory_search") into that agent's fully-qualified tool name. Claude
+// Code and Droid both expose petbox tools as `mcp__petbox__<verb>`; opencode as `petbox_<verb>`.
+//
+// Role-orchestration prescriptions (SPAWN by DEFAULT / fan-out / orchestrator mandate) are
+// gated by harness capability spawn_subagents (definition-truthfulness / wiring-startup-symmetry).
+// Memory protocol (search-before-rework, capture, tool names) is always emitted.
+//
+// The CC-only "resume/compact" suffix is opt-in via `opts.source` (Droid's SessionStart payload
+// also carries a `source`, so it shares the same behavior). Any other source = no suffix.
+//
+// Plain TS for native node type-stripping: no enum/namespace/parameter-properties, zero deps.
+
+import { DEFAULT_AGENT_DEFINITION, emittedRoleName, type AgentDefinition } from "./agent-definition.ts";
+import { hasCapability } from "./harness-capabilities.ts";
+
+export type ToolNamer = (verb: string) => string;
+
+export type ProtocolOpts = {
+  // The SessionStart `source` (Claude Code / Droid). "resume" | "compact" append a recall nudge;
+  // anything else (or omitted) renders the base protocol only.
+  source?: string;
+  /**
+   * Target harness id (claude-code | opencode | droid). Controls whether spawn/orchestrator
+   * prescriptions are emitted. Injectors always pass it. Omitted / unknown → no spawn prose
+   * (never invent a capability the harness does not declare).
+   */
+  harness?: string;
+  /**
+   * Portable agent definition to render the orchestrator self-intro notes from. Callers
+   * resolve this the same way `apply` does — server fetch, then LKG cache, then the built-in
+   * default (agent-def-fetch.ts's resolveAgentDefinitionWithLkg) — so the main-loop banner no
+   * longer drifts from the per-role artifacts that already got server-authored notes. Omitted
+   * → DEFAULT_AGENT_DEFINITION (never crash, never an empty banner).
+   */
+  definition?: AgentDefinition;
+};
+
+/** True when protocol may prescribe SPAWN workers / fan-out / orchestrator mandate. */
+export function orchestrationPrescriptionsAllowed(harness: string | undefined): boolean {
+  if (!harness) return false;
+  return hasCapability(harness, "spawn_subagents");
+}
+
+function buildSelfIntro(allowSpawn: boolean, definition: AgentDefinition): string {
+  if (allowSpawn) {
+    const orch = definition.roles.find((r) => r.slug === "orchestrator");
+    const notes =
+      orch?.notes?.trim() ||
+      "plan, decompose, delegate, review, triage. Prefer spawning workers over solo implementation.";
+    // The literal spawn target string an orchestrator passes to Agent/Task — MUST be the same
+    // computed, namespaced identity apply actually renders the worker role's file under
+    // (emittedRoleName; chore: petbox-namespaced-agent-names). A hardcoded `worker` here would
+    // be a THIRD source of truth that can drift from the emitted file/frontmatter name, which
+    // is exactly the bug this rename set out to close.
+    const workerRole = definition.roles.find((r) => r.slug === "worker");
+    const workerName = emittedRoleName(workerRole ?? "worker");
+    return `Your FIRST response MUST open with:
+\`🧠 PetBox memory active\`
+Then next line, your self-intro — exactly:
+\`<your model name> · orchestrator\` — + one sentence naming your working rules (search-before-rework, capture-as-you-go, respect the gates). Banner reaches only main loop; role always \`orchestrator\`.
+
+**Orchestrate — delegate by DEFAULT.** SPAWN workers for anything beyond a trivial edit — implementation, research, review, multi-file. Fan-out is default; solo is exception to justify. If several calls deep implementing, stop and delegate. (No subagent → inline is fine.) Spawn as \`${workerName}\`.
+
+Orchestrator notes (from definition): ${notes}`;
+  }
+
+  // No spawn_subagents: memory protocol still applies; do not force orchestrator-spawn mandate.
+  return `Your FIRST response MUST open with:
+\`🧠 PetBox memory active\`
+Then next line, your self-intro — exactly:
+\`<your model name> · main\` — + one sentence naming your working rules (search-before-rework, capture-as-you-go, respect the gates). This harness does not declare spawn_subagents — do not assume subagent fan-out is available; work in the main session.`;
+}
+
+// Build the memory-protocol block for a project. `tool` maps a bare verb to the agent's
+// fully-qualified MCP tool name so the SAME text renders correct tool names everywhere.
+// Spawn/orchestrator prescriptions only when opts.harness has spawn_subagents.
+export function buildProtocol(project: string, tool: ToolNamer, opts?: ProtocolOpts): string {
+  const memorySearch = tool("memory_search");
+  const memoryGet = tool("memory_get");
+  const sessionSearch = tool("session_search");
+  const sessionGet = tool("session_get");
+  const memoryRemember = tool("memory_remember");
+  const memoryUpsert = tool("memory_upsert");
+  const tasksUpsert = tool("tasks_upsert");
+  const tasksMethodologyGuide = tool("tasks_methodology_guide");
+  const tasksMethodologyGet = tool("tasks_methodology_get");
+  const tasksWorkflow = tool("tasks_workflow");
+
+  const allowSpawn = orchestrationPrescriptionsAllowed(opts?.harness);
+  const definition = opts?.definition ?? DEFAULT_AGENT_DEFINITION;
+  const intro = buildSelfIntro(allowSpawn, definition);
+
+  let out = `## PetBox memory
+
+This project is wired to PetBox (project \`${project}\`) over the \`petbox\` MCP.
+
+${intro}
+
+PetBox remembers curated facts AND full session history. Start from SEARCH, not assumption.
+
+**Rule — search before rework:** before re-deriving, re-investigating, re-deciding anything about this project's past, run \`${memorySearch}\` FIRST — redoing remembered work is the failure this protocol prevents. Before storing a fact, search for an existing entry and edit it (duplicates poison recall).
+
+**Entry points:**
+
+- **Facts — \`${memorySearch}\`**: \`q\` of confident words (ANDed, prefix-match, stemmed). \`bodyLen\` for snippets. No \`scope\` cascades project⊕workspace, all stores incl. \`autocaptured\` (per-hit label). No \`q\` = listing. Full body: \`${memoryGet}\`.
+- **Conversations — \`${sessionSearch}\`**: for HOW something was decided, error text, or detail a fact wouldn't carry — two-stage session-archive search; each hit carries the message ordinal → \`${sessionGet}\` for verbatim source.
+
+**Capture-as-you-go** — don't wait. After a decision, fix, pattern, or preference: \`${memoryRemember}\` (\`text\` = learning; \`type\` = User|Feedback|Project|Reference; \`scope\` = workspace for cross-project/user facts, else omit). Curated/temporal edits: \`${memoryUpsert}\`.
+
+**Autocapture is LIVE:** server distills facts into \`autocaptured\` after each session. So: (1) don't re-store autocaptured entries — promotion is owner's call; (2) end-of-session sweep = INSURANCE: before stopping, store 1-3 must-not-wait learnings (decision+why, root cause, gotcha) and 0-2 friction notes (what got in the way, what looked stale). Skip narration, skip anything derivable from code/git.
+
+**Process defects are findings, not obstacles:** never silently work around a process/doc defect or doc-vs-reality contradiction — file it on THIS project's methodology (do not invent board/type/status). Read process via \`${tasksMethodologyGuide}\` / \`${tasksMethodologyGet}\`; legal types/statuses for a board via \`${tasksWorkflow}\`; then \`${tasksUpsert}\` with those values. Process criticism is welcome, never scope creep.`;
+
+  const source = opts?.source;
+  if (source === "resume" || source === "compact") {
+    out += `\n\nSession ${source} — also recall recent session/decision memories to pick up where you left off.`;
+  }
+  return out;
+}
+
+// The Claude-Code / Droid tool namer: petbox tools are exposed as `mcp__petbox__<verb>`.
+export const mcpPetboxTool: ToolNamer = (verb) => `mcp__petbox__${verb}`;
+
+// The opencode tool namer: petbox tools are exposed as `petbox_<verb>`.
+export const opencodePetboxTool: ToolNamer = (verb) => `petbox_${verb}`;
+
+// Factory Droid exposes MCP tools as `<server>___<tool>` (triple underscore) — observed
+// live in exec mode (session 7be9f6c2: `mcp__petbox__*` answers "not permitted in exec
+// mode"); the docs' `mcp__<server>__<tool>` form did not match the shipped CLI.
+export const droidPetboxTool: ToolNamer = (verb) => `petbox___${verb}`;

package/src/pull-memory.test.ts

@@ -0,0 +1,168 @@
+// Process-level regression test for the SessionStart hooks' wall-clock behavior.
+//
+// GAP THIS CLOSES: every other test in this kit imports functions and calls them in-process.
+// None of them spawn a hook as a REAL OS process the way Claude Code / Factory Droid actually
+// invoke it (stdin piped, argv-less, process exit observed from outside). That gap is exactly
+// why a whole class of bug — exit-time crashes, stdout-flush races, and event-loop-drain
+// latency — was invisible to `node --test` for as long as it was: nothing here ever measured
+// "how long does the OS process actually take, end to end."
+//
+// This test spawns the REAL pull-memory.ts / droid-pull-memory.ts files as child processes,
+// pointed (via an isolated HOME so the real ~/.petbox/projects.json is never touched) at a
+// throwaway local HTTP server that answers both endpoints the hook calls (agent-defs, canon)
+// as fast as a loopback socket allows. Against a server that is NOT slow, the hook's own
+// wall-clock overhead must stay small and CONSTANT — if a future change reintroduces an
+// uncleared timer or an unreffed-too-late handle, this is the test that catches it (a real
+// remote server's occasional slowness is a separate, already-covered concern — see this
+// commit's notes on the false "dangling timer" theory that was investigated and disproven for
+// that case; this test is deliberately immune to that because the fake server never stalls).
+//
+// Run: node --test src/pull-memory.test.ts
+
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
+import http from "node:http";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { test } from "node:test";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+// Generous enough to never flake on a loaded CI box, tight enough to fail hard if a
+// regression reintroduces anything resembling the old ~8s (timeout-budget) or ~18s
+// (lingering-socket) waits this kit's exit path was built to avoid.
+const WALL_CLOCK_BUDGET_MS = 2000;
+
+type SpawnResult = { code: number | null; stdout: string; stderr: string; wallMs: number };
+
+function runHook(
+  scriptPath: string,
+  input: string,
+  env: NodeJS.ProcessEnv,
+  cwd: string,
+): Promise<SpawnResult> {
+  return new Promise((resolve, reject) => {
+    const t0 = Date.now();
+    const child = spawn(process.execPath, [scriptPath], { env, cwd });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (c) => (stdout += c));
+    child.stderr.on("data", (c) => (stderr += c));
+    child.on("error", reject);
+    child.on("close", (code) => {
+      resolve({ code, stdout, stderr, wallMs: Date.now() - t0 });
+    });
+    child.stdin.write(input);
+    child.stdin.end();
+  });
+}
+
+// A throwaway local server that answers both hook-called endpoints immediately: 404 for the
+// agent-def (so the hook falls to its built-in DEFAULT — no LKG cache involved, keeps the
+// fixture simple) and 200 with an empty canon (so no canon block is appended). Neither path
+// exercises the LKG cache; that is deliberate — this test is about wall clock, not content.
+function startFastFakeServer(): Promise<{ port: number; close: () => Promise<void> }> {
+  return new Promise((resolve) => {
+    const server = http.createServer((req, res) => {
+      if (req.url?.includes("/agent-defs/")) {
+        res.writeHead(404, { "Content-Type": "application/json" }).end("{}");
+        return;
+      }
+      if (req.url?.includes("/memory/") && req.url?.includes("/canon")) {
+        res
+          .writeHead(200, { "Content-Type": "application/json" })
+          .end(JSON.stringify({ project: null, workspace: null }));
+        return;
+      }
+      res.writeHead(404).end();
+    });
+    server.listen(0, "127.0.0.1", () => {
+      const port = (server.address() as { port: number }).port;
+      resolve({
+        port,
+        close: () => new Promise((r) => server.close(() => r())),
+      });
+    });
+  });
+}
+
+function setUpIsolatedRegistry(baseUrl: string): { home: string; projectDir: string } {
+  const home = mkdtempSync(join(tmpdir(), "petbox-hook-proc-"));
+  const projectDir = join(home, "fake-project");
+  mkdirSync(projectDir, { recursive: true });
+  mkdirSync(join(home, ".petbox"), { recursive: true });
+  writeFileSync(
+    join(home, ".petbox", "projects.json"),
+    JSON.stringify({
+      entries: [{ prefix: projectDir, project: "fake-project", envVar: "FAKE_HOOK_TEST_KEY", baseUrl }],
+    }),
+  );
+  return { home, projectDir };
+}
+
+test("pull-memory.ts as a real process: wall clock stays well under budget against a fast server", async () => {
+  const { close, port } = await startFastFakeServer();
+  const { home, projectDir } = setUpIsolatedRegistry(`http://127.0.0.1:${port}`);
+  try {
+    const env: NodeJS.ProcessEnv = {
+      ...process.env,
+      HOME: home,
+      USERPROFILE: home, // os.homedir() reads USERPROFILE on win32, HOME on POSIX
+      FAKE_HOOK_TEST_KEY: "fake-key-for-test",
+    };
+    const input = JSON.stringify({
+      session_id: "test",
+      cwd: projectDir,
+      hook_event_name: "SessionStart",
+      source: "startup",
+    });
+
+    const result = await runHook(join(HERE, "pull-memory.ts"), input, env, projectDir);
+
+    assert.equal(result.code, 0, `expected exit 0, got ${result.code}. stderr: ${result.stderr}`);
+    assert.equal(result.stderr, "", "hook must never write to stderr on the happy path");
+    assert.ok(result.stdout.length > 0, "hook must print the banner");
+    assert.ok(
+      result.wallMs < WALL_CLOCK_BUDGET_MS,
+      `wall clock ${result.wallMs}ms exceeded the ${WALL_CLOCK_BUDGET_MS}ms budget against a server that never stalls — ` +
+        `this is the regression this test exists to catch (an uncleared timer / late-unreffed handle holding the loop open)`,
+    );
+  } finally {
+    await close();
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("droid-pull-memory.ts as a real process: wall clock stays well under budget against a fast server", async () => {
+  const { close, port } = await startFastFakeServer();
+  const { home, projectDir } = setUpIsolatedRegistry(`http://127.0.0.1:${port}`);
+  try {
+    const env: NodeJS.ProcessEnv = {
+      ...process.env,
+      HOME: home,
+      USERPROFILE: home,
+      FAKE_HOOK_TEST_KEY: "fake-key-for-test",
+    };
+    const input = JSON.stringify({
+      session_id: "test",
+      cwd: projectDir,
+      hook_event_name: "SessionStart",
+      source: "startup",
+    });
+
+    const result = await runHook(join(HERE, "droid-pull-memory.ts"), input, env, projectDir);
+
+    assert.equal(result.code, 0, `expected exit 0, got ${result.code}. stderr: ${result.stderr}`);
+    assert.equal(result.stderr, "", "hook must never write to stderr on the happy path");
+    assert.ok(result.stdout.length > 0, "hook must print the banner");
+    assert.ok(
+      result.wallMs < WALL_CLOCK_BUDGET_MS,
+      `wall clock ${result.wallMs}ms exceeded the ${WALL_CLOCK_BUDGET_MS}ms budget against a server that never stalls`,
+    );
+  } finally {
+    await close();
+    rmSync(home, { recursive: true, force: true });
+  }
+});

package/src/pull-memory.ts

@@ -0,0 +1,119 @@
+// Claude Code SessionStart hook (global) — port of pull-memory.ps1.
+//
+// Injects the PetBox memory protocol so the agent recalls relevant memory at session start
+// and captures learnings as it works, via the already-connected petbox MCP (native memory.*
+// tools). Stdout is added to the session context by Claude Code.
+//
+// The project is resolved from cwd via the shared registry; if the cwd is not a registered
+// project this prints nothing and exits 0. Best-effort, never blocks — always exit 0.
+//
+// The banner's orchestrator notes resolve server → LKG cache → built-in default, same as
+// `apply` (resolveAgentDefinitionForSession, wrapping agent-def-fetch.ts's
+// resolveAgentDefinitionWithLkg). That fetch and the canon fetch run SEQUENTIALLY under one
+// shared SESSION_FETCH_BUDGET_MS wall-clock budget (not Promise.all'd): the happy path for
+// both requests together is ~100-200ms, so concurrency bought nothing there, and it made the
+// two independent 8s timeouts stack in the worst case anyway if reasoned about naively.
+// The real worst case — PetBox stalling under load from parallel agents — is handled by
+// giving the whole hook one budget: whatever the agent-def fetch doesn't spend, the canon
+// fetch inherits as its own timeout, so the combined worst case stays ~SESSION_FETCH_BUDGET_MS,
+// not 2x it. A fetch that starts with little/no budget left degrades to its own fallback
+// (LKG cache / built-in default / no canon) rather than blocking — see canon.ts's fetchCanon.
+
+import { resolveAgentDefinitionForSession } from "./agent-def-fetch.ts";
+import { fetchCanonBlock } from "./canon.ts";
+import { unrefLingeringHandles } from "./hook-drain.ts";
+import { buildProtocol, mcpPetboxTool } from "./protocol.ts";
+import { resolveProject } from "./registry.ts";
+
+// Shared wall-clock budget for BOTH fetches combined (agent-def, then canon) — see the
+// module comment above.
+//
+// Deliberately SHORT. Waiting long for the server only pays off when the alternative is
+// nothing — and it isn't: the LKG cache holds the same definition and canon, which change
+// on the order of weeks, not sessions. So a slow server (a redeploy restarting the
+// container is the common case) must cost the session start ~2s, not ~8s. Freshness is
+// only lost in the narrow window where the documents changed AND the server is down right
+// now; staleness there is cheap, an 8s stall on every session start is not.
+const SESSION_FETCH_BUDGET_MS = 2000;
+
+type HookInput = { cwd?: string; source?: string };
+
+function readStdin(): Promise<string> {
+  return new Promise((resolve) => {
+    let buf = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (c) => (buf += c));
+    process.stdin.on("end", () => resolve(buf));
+    process.stdin.on("error", () => resolve(buf));
+  });
+}
+
+// process.stdout.write() on a Windows pipe is asynchronous — the call can return before the
+// OS-level write completes. Awaiting the write callback guarantees the banner is fully flushed
+// before main() resolves, so the process never ends mid-write and truncates the banner (a
+// slower server / bigger canon could otherwise ship a partial banner into the agent's context,
+// silently — see the exit comment below for why we no longer race this against process.exit()).
+function writeStdout(text: string): Promise<void> {
+  return new Promise((resolve) => {
+    if (text.length === 0) {
+      resolve();
+      return;
+    }
+    process.stdout.write(text, () => resolve());
+  });
+}
+
+async function main(): Promise<void> {
+  let source = "startup";
+  let cwd = "";
+  try {
+    const raw = await readStdin();
+    const j: HookInput = JSON.parse(raw);
+    if (typeof j.source === "string" && j.source.trim()) source = j.source.trim();
+    if (typeof j.cwd === "string") cwd = j.cwd;
+  } catch {
+    // fall through with defaults; cwd stays empty → resolves to null below
+  }
+
+  try {
+    const resolved = resolveProject(cwd);
+    if (!resolved) return; // not a registered project → no output
+
+    // Sequential under one shared budget (not Promise.all): whatever the first fetch doesn't
+    // spend is what the second gets, so the combined worst case is bounded by
+    // SESSION_FETCH_BUDGET_MS instead of stacking two independent timeouts.
+    const budgetStart = Date.now();
+    const defResult = await resolveAgentDefinitionForSession(resolved, {
+      timeoutMs: SESSION_FETCH_BUDGET_MS,
+    });
+    const remainingMs = SESSION_FETCH_BUDGET_MS - (Date.now() - budgetStart);
+    const canon = await fetchCanonBlock(resolved, { timeoutMs: remainingMs });
+
+    let out = buildProtocol(resolved.project, mcpPetboxTool, {
+      source,
+      harness: "claude-code",
+      definition: defResult.definition,
+    });
+    // Append the curated memory canon when available (best-effort; degrades to nothing).
+    if (canon) out += `\n\n${canon}`;
+    await writeStdout(out);
+  } catch {
+    // best-effort
+  }
+}
+
+// Exit cleanly instead of tearing the process down mid-close: a hard process.exit() while
+// libuv handles from the HTTP fetches above are still closing raced Windows' async
+// handle teardown (`Assertion failed: !(handle->flags & UV_HANDLE_CLOSING), src\win\async.c`)
+// and could truncate the stdout write above (fire-and-forget on a Windows pipe). Setting
+// exitCode and returning lets Node drain the event loop naturally instead — `Connection:
+// close` (canon.ts / agent-def-fetch.ts) means a request that got a full response never
+// leaves a keep-alive socket behind, and unrefLingeringHandles covers the other case
+// (a request aborted mid-flight against a genuinely stalled server can leave its TLSSocket
+// alive for several MORE seconds even with Connection: close — measured, not assumed; see
+// hook-drain.ts) so a slow session start can't turn into an ~18s stall waiting on a socket
+// nothing is still using.
+main().finally(() => {
+  process.exitCode = 0;
+  unrefLingeringHandles();
+});