petbox-wire 0.1.0-ci.1206

package/src/import-sessions.ts

@@ -0,0 +1,261 @@
+// History importer (spec: wiring-history-import) — backfill the PetBox session archive
+// from the agents' LOCAL history, so a freshly connected project starts with a warm
+// memory instead of an empty one:
+//
+//   node --experimental-strip-types import-sessions.ts [--agent claude|opencode|all]
+//        [--project <key>] [--dry-run] [--since YYYY-MM-DD] [--limit N] [--force]
+//
+// Two invariants protect the archive:
+//   native ids   — a session is pushed under the SAME id its agent's live hook/plugin
+//                  uses (Claude: transcript uuid; opencode: ses_…), so an import lands
+//                  in the same latest-snapshot row — duplicates are impossible;
+//   upgrade-only — latest-snapshot is last-write-wins, so before pushing we compare the
+//                  local message count against the server version (GET /api/sessions)
+//                  and skip unless local is strictly larger (--force overrides) — a
+//                  stale file read can never roll back a fresher snapshot.
+//
+// Only dialogue turns are sent (shared transcript.ts parsing — the same code the Stop
+// hook runs); raw tool outputs never leave the machine. Server-side, the cursor-driven
+// pipelines (digest, facts, patterns) backfill on their own after the push.
+
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, basename } from "node:path";
+import { readRegistry, resolveProject, type ResolvedProject } from "./registry.ts";
+import { buildMessages, readTranscriptCwd, type Msg } from "./transcript.ts";
+
+const FETCH_TIMEOUT_MS = 30000;
+
+type Args = {
+  agent: "claude" | "opencode" | "all";
+  project?: string;
+  dryRun: boolean;
+  since?: Date;
+  limit?: number;
+  force: boolean;
+};
+
+type Candidate = {
+  agent: string;
+  sessionId: string;
+  updated: Date;
+  load: () => Promise<Msg[]>;
+};
+
+function parseArgs(argv: string[]): Args {
+  const a: Args = { agent: "all", dryRun: false, force: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--agent") a.agent = (argv[++i] as Args["agent"]) ?? "all";
+    else if (arg === "--project") {
+      const project = argv[++i];
+      if (project !== undefined) a.project = project;
+    } else if (arg === "--dry-run") a.dryRun = true;
+    else if (arg === "--force") a.force = true;
+    else if (arg === "--since") a.since = new Date(argv[++i] ?? "");
+    else if (arg === "--limit") {
+      const limit = parseInt(argv[++i] ?? "0", 10) || undefined;
+      if (limit !== undefined) a.limit = limit;
+    }
+    else throw new Error(`unknown argument: ${arg}`);
+  }
+  if (!["claude", "opencode", "all"].includes(a.agent)) throw new Error(`invalid --agent: ${a.agent}`);
+  if (a.since && isNaN(a.since.getTime())) throw new Error("invalid --since (use YYYY-MM-DD)");
+  return a;
+}
+
+// The target: --project finds the registry entry by project key; otherwise the cwd
+// resolves like the hooks do.
+function resolveTarget(projectKey?: string): ResolvedProject {
+  if (projectKey) {
+    const entry = readRegistry().find((e) => e.project === projectKey);
+    if (!entry) throw new Error(`project '${projectKey}' not found in ~/.petbox/projects.json`);
+    const apiKey = process.env[entry.envVar];
+    if (!apiKey) throw new Error(`env var ${entry.envVar} is empty`);
+    return {
+      project: entry.project,
+      apiKey,
+      baseUrl: (entry.baseUrl ?? "https://petbox.3po.su").replace(/\/+$/, ""),
+      envVar: entry.envVar,
+    };
+  }
+  const resolved = resolveProject(process.cwd());
+  if (!resolved) throw new Error("cwd is not a registered project (or its env var is empty); use --project");
+  return resolved;
+}
+
+function listDirs(path: string): string[] {
+  try {
+    return readdirSync(path, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
+  } catch {
+    return [];
+  }
+}
+
+function listFiles(path: string, ext: string): string[] {
+  try {
+    return readdirSync(path).filter((f) => f.endsWith(ext));
+  } catch {
+    return [];
+  }
+}
+
+function readJson(path: string): any | null {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+// Claude Code: ~/.claude/projects/<encoded-cwd>/*.jsonl. The encoding is lossy, so a
+// transcript is attributed by the cwd recorded INSIDE it, resolved through the same
+// registry matching the hooks use (worktrees and subfolders included).
+async function claudeCandidates(target: ResolvedProject): Promise<Candidate[]> {
+  const root = join(homedir(), ".claude", "projects");
+  const out: Candidate[] = [];
+  for (const dir of listDirs(root)) {
+    for (const file of listFiles(join(root, dir), ".jsonl")) {
+      const path = join(root, dir, file);
+      const cwd = await readTranscriptCwd(path);
+      if (!cwd) continue;
+      const resolved = resolveProject(cwd);
+      if (!resolved || resolved.project !== target.project) continue;
+      out.push({
+        agent: "claude-code",
+        sessionId: basename(file, ".jsonl"),
+        updated: statSync(path).mtime,
+        load: () => buildMessages(path),
+      });
+    }
+  }
+  return out;
+}
+
+// opencode: ~/.local/share/opencode/storage —
+//   session/<projectHash>/<ses>.json  {id, directory, time.updated}
+//   message/<ses>/<msg>.json          {id, role, time.created}
+//   part/<msg>/<prt>.json             {type:"text", text}
+// A session is attributed by its recorded `directory`; content = the text parts of each
+// message, in message-time order — the same dialogue-only shape the live plugin pushes.
+function opencodeCandidates(target: ResolvedProject): Candidate[] {
+  const storage = join(homedir(), ".local", "share", "opencode", "storage");
+  const out: Candidate[] = [];
+  for (const hash of listDirs(join(storage, "session"))) {
+    for (const file of listFiles(join(storage, "session", hash), ".json")) {
+      const info = readJson(join(storage, "session", hash, file));
+      if (!info || typeof info.id !== "string" || typeof info.directory !== "string") continue;
+      const resolved = resolveProject(info.directory);
+      if (!resolved || resolved.project !== target.project) continue;
+      const sessionId = info.id;
+      out.push({
+        agent: "opencode",
+        sessionId,
+        updated: new Date(info.time?.updated ?? info.time?.created ?? 0),
+        load: async () => {
+          const msgDir = join(storage, "message", sessionId);
+          const metas = listFiles(msgDir, ".json")
+            .map((f) => readJson(join(msgDir, f)))
+            .filter((m) => m && typeof m.role === "string")
+            .sort((a, b) => (a.time?.created ?? 0) - (b.time?.created ?? 0) || String(a.id).localeCompare(String(b.id)));
+          const msgs: Msg[] = [];
+          for (const meta of metas) {
+            const partDir = join(storage, "part", meta.id);
+            const text = listFiles(partDir, ".json")
+              .sort()
+              .map((f) => readJson(join(partDir, f)))
+              .filter((p) => p && p.type === "text" && typeof p.text === "string")
+              .map((p) => p.text)
+              .join("\n")
+              .trim();
+            if (text.length === 0) continue;
+            msgs.push({ role: meta.role, content: text });
+          }
+          return msgs;
+        },
+      });
+    }
+  }
+  return out;
+}
+
+async function serverVersions(target: ResolvedProject): Promise<Map<string, number>> {
+  const res = await fetch(`${target.baseUrl}/api/sessions/${target.project}`, {
+    headers: { "X-Api-Key": target.apiKey },
+    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+  });
+  if (!res.ok) throw new Error(`GET /api/sessions/${target.project} → ${res.status}`);
+  const body = (await res.json()) as { sessions?: { sessionId: string; version: number }[] };
+  return new Map((body.sessions ?? []).map((s) => [s.sessionId, s.version]));
+}
+
+async function push(target: ResolvedProject, c: Candidate, msgs: Msg[]): Promise<void> {
+  const body = msgs.map((m) => JSON.stringify(m)).join("\n");
+  const uri = `${target.baseUrl}/api/sessions/${target.project}/${encodeURIComponent(c.sessionId)}?agent=${encodeURIComponent(c.agent)}`;
+  const res = await fetch(uri, {
+    method: "POST",
+    headers: { "X-Api-Key": target.apiKey, "Content-Type": "application/x-ndjson; charset=utf-8" },
+    body,
+    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+  });
+  if (!res.ok) throw new Error(`POST ${c.sessionId} → ${res.status}`);
+}
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2));
+  const target = resolveTarget(args.project);
+  console.log(`importing into '${target.project}' @ ${target.baseUrl} (agent: ${args.agent}${args.dryRun ? ", DRY-RUN" : ""})`);
+
+  let candidates: Candidate[] = [];
+  if (args.agent === "claude" || args.agent === "all") candidates.push(...(await claudeCandidates(target)));
+  if (args.agent === "opencode" || args.agent === "all") candidates.push(...opencodeCandidates(target));
+  candidates.sort((a, b) => a.updated.getTime() - b.updated.getTime());
+
+  const filtered = args.since ? candidates.filter((c) => c.updated >= args.since!) : candidates;
+  const skippedFiltered = candidates.length - filtered.length;
+  const capped = args.limit ? filtered.slice(0, args.limit) : filtered;
+  const skippedLimit = filtered.length - capped.length;
+
+  const versions = await serverVersions(target);
+  let pushed = 0, upToDate = 0, empty = 0, failed = 0, totalMsgs = 0;
+  for (const c of capped) {
+    try {
+      const msgs = await c.load();
+      if (msgs.length === 0) {
+        empty++;
+        continue;
+      }
+      const server = versions.get(c.sessionId) ?? 0;
+      if (!args.force && msgs.length <= server) {
+        upToDate++; // upgrade-only: never roll a fresher snapshot back
+        continue;
+      }
+      if (args.dryRun) {
+        console.log(`  would push ${c.agent} ${c.sessionId}: ${msgs.length} msgs (server: ${server})`);
+        pushed++;
+        totalMsgs += msgs.length;
+        continue;
+      }
+      await push(target, c, msgs);
+      pushed++;
+      totalMsgs += msgs.length;
+      console.log(`  pushed ${c.agent} ${c.sessionId}: ${msgs.length} msgs (server was ${server})`);
+    } catch (e) {
+      failed++;
+      console.error(`  FAILED ${c.sessionId}: ${e instanceof Error ? e.message : e}`);
+    }
+  }
+
+  console.log(
+    `done: ${pushed} pushed (${totalMsgs} msgs), ${upToDate} up-to-date, ${empty} empty, ` +
+      `${skippedFiltered} before --since, ${skippedLimit} over --limit, ${failed} failed`,
+  );
+  if (pushed > 0 && !args.dryRun)
+    console.log("note: server pipelines (digest/facts/patterns) will backfill in the background over the next minutes.");
+  process.exit(failed > 0 ? 1 : 0);
+}
+
+main().catch((e) => {
+  console.error(e instanceof Error ? e.message : e);
+  process.exit(1);
+});

package/src/opencode-plugin.ts

@@ -0,0 +1,127 @@
+/**
+ * PetBox plugin for opencode (GLOBAL) — the opencode port of the two Claude Code hooks:
+ *
+ *   1. pull-memory  (SessionStart) → inject the PetBox memory protocol so the agent recalls
+ *      relevant memory and captures learnings via the connected `petbox` MCP. Appended to the
+ *      system prompt via `experimental.chat.system.transform`.
+ *
+ *   2. push-session (Stop) → mirror the session conversation into PetBox's Session module so it
+ *      auto-populates. Fires on `session.idle` (opencode's "the turn finished") and pushes the
+ *      INCREMENT via the server-authoritative append cursor (see append.ts) — the plugin is
+ *      long-lived, so it remembers each session's lastOrdinal from the previous response in
+ *      process memory (no durable state); a restart self-heals off the structured 409 gap
+ *      reject, and old servers without the append route fall back to the full-snapshot push.
+ *
+ * Unlike the per-project copy this is installed once at user scope. The active project + API
+ * key + base URL are resolved from `directory` (PluginInput) via the shared registry. If the
+ * cwd is not a registered project (or the key is missing) BOTH hooks are no-ops — but the
+ * plugin still loads cleanly in every project.
+ *
+ * Both hooks are best-effort and must never break a turn (every failure is swallowed).
+ *
+ * MCP note: opencode exposes MCP tools as `<server>_<tool>`, so the petbox memory verbs are
+ * `petbox_memory_search` / `petbox_memory_remember` / `petbox_memory_get` /
+ * `petbox_memory_upsert` (the Claude `mcp__petbox__*` names do not apply here).
+ */
+import type { Plugin } from "@opencode-ai/plugin";
+import { resolveAgentDefinitionForSession } from "./agent-def-fetch.ts";
+import { DEFAULT_AGENT_DEFINITION, type AgentDefinition } from "./agent-definition.ts";
+import { pushTranscript } from "./append.ts";
+import { fetchCanonBlock } from "./canon.ts";
+import { buildProtocol, opencodePetboxTool } from "./protocol.ts";
+import { resolveProject } from "./registry.ts";
+
+export const PetboxPlugin: Plugin = async ({ client, directory }) => {
+  // Resolve the active project once at load. null → both hooks no-op.
+  const resolved = resolveProject(directory ?? "");
+
+  // Resolve the banner's orchestrator notes ONCE at plugin load — server → LKG cache → the
+  // built-in default, same order `apply` uses (resolveAgentDefinitionForSession wraps
+  // agent-def-fetch.ts's resolveAgentDefinitionWithLkg). Bounded by that helper's own ~8s
+  // fetch timeout; the plugin instance is long-lived for the opencode session, so this is a
+  // one-time load-time cost, not a per-prompt one, and never throws/blocks indefinitely.
+  let agentDefinition: AgentDefinition = DEFAULT_AGENT_DEFINITION;
+  if (resolved) {
+    const got = await resolveAgentDefinitionForSession(resolved);
+    agentDefinition = got.definition;
+  }
+
+  // Avoid re-POSTing the same state when session.idle fires repeatedly.
+  const lastPushed = new Map<string, string>();
+  // Per-session server cursor (lastOrdinal from the previous response). Process memory only —
+  // a plugin restart just means the first push self-heals via the structured gap reject.
+  const cursors = new Map<string, number>();
+
+  async function pushSession(sessionID: string): Promise<void> {
+    if (!resolved || !sessionID) return;
+
+    const res = await client.session.messages({ path: { id: sessionID } });
+    const messages = res.data;
+    if (!Array.isArray(messages) || messages.length === 0) return;
+
+    // The whole conversation (user + assistant text turns), ordered — pushTranscript sends
+    // only the tail past the remembered server cursor (the increment), not the full history.
+    const msgs = messages
+      .map((m: any) => {
+        const text = m.parts
+          .filter((p: any) => p.type === "text" && typeof p.text === "string")
+          .map((p: any) => p.text)
+          .join("\n")
+          .trim();
+        return text ? { role: m.info.role, content: text } : null;
+      })
+      .filter(Boolean) as { role: string; content: string }[];
+    if (msgs.length === 0) return;
+    const lastID = messages[messages.length - 1]?.info?.id ?? "";
+    if (lastPushed.get(sessionID) === lastID) return;
+
+    const lastOrdinal = await pushTranscript(
+      {
+        baseUrl: resolved.baseUrl,
+        project: resolved.project,
+        sessionId: sessionID,
+        apiKey: resolved.apiKey,
+        agent: "opencode",
+        timeoutMs: 8000,
+      },
+      msgs,
+      cursors.get(sessionID) ?? null,
+    );
+    if (lastOrdinal !== null) {
+      cursors.set(sessionID, lastOrdinal);
+      lastPushed.set(sessionID, lastID);
+    }
+  }
+
+  // No per-prompt context injection is wired here. (The kit's prompt-RAG experiment — exact-match
+  // per-prompt pointer injection on Claude Code's UserPromptSubmit — has been removed entirely, and
+  // opencode never had a clean equivalent of that hook to port it to.)
+  return {
+    // Port of pull-memory — make the memory protocol part of the system prompt.
+    "experimental.chat.system.transform": async (_input, output) => {
+      if (!resolved) return;
+      output.system.push(
+        buildProtocol(resolved.project, opencodePetboxTool, {
+          harness: "opencode",
+          definition: agentDefinition,
+        }),
+      );
+      // Append the curated memory canon when available (best-effort; degrades to nothing).
+      const canon = await fetchCanonBlock(resolved);
+      if (canon) output.system.push(canon);
+    },
+
+    // Port of push-session — mirror the finished turn into PetBox's Session module.
+    event: async ({ event }) => {
+      if (event.type !== "session.idle") return;
+      const sessionID = (event as any).properties?.sessionID;
+      try {
+        await pushSession(sessionID);
+      } catch {
+        /* best-effort: never break the turn */
+      }
+    },
+  };
+};
+
+export default PetboxPlugin;

package/src/origin-marker.ts

@@ -0,0 +1,37 @@
+// The origin marker every petbox-wire `apply` render embeds into a generated file's YAML
+// frontmatter, and the ONLY thing the write guard (apply-write.ts) trusts to recognize "this
+// file is ours" before it ever overwrites or deletes something already on disk — no content
+// heuristics, no filename convention, no timestamp guess.
+//
+// Why this exists (bug: apply-clobbers-user-agent-files): `apply` used to writeFileSync
+// unconditionally. A user with their OWN `.claude/agents/worker.md` lost it silently on the
+// first apply — the only trace that a file was "ours" was a `description: PetBox <tier> role
+// (<slug>)` line INSIDE the file apply had already overwritten, which is useless after the
+// fact. The marker line below is written BEFORE any write decision is made, so a pre-existing
+// file can be classified accurately: ours (marker present → safe to update silently) or a
+// real user file (marker absent → refuse, loudly, never touch it).
+//
+// Plain TS for native node type-stripping: zero deps.
+
+export const PETBOX_MARKER_KEY = "petbox";
+export const PETBOX_MARKER_VALUE = "managed";
+/** The literal frontmatter line every renderer appends to a generated file. */
+export const PETBOX_MARKER_LINE = `${PETBOX_MARKER_KEY}: ${PETBOX_MARKER_VALUE}`;
+
+const MARKER_LINE_RE = new RegExp(`^${PETBOX_MARKER_KEY}:\\s*\\S+`, "m");
+
+/**
+ * True when `content`'s YAML frontmatter (the block between the first pair of `---` lines)
+ * carries our origin marker. Frontmatter-scoped on purpose: a user's OWN file that happens to
+ * mention the word "petbox" in its BODY prose must never be mistaken for ours. A file with no
+ * frontmatter at all (no leading `---` block) never matches — it cannot be one of our renders.
+ */
+export function hasPetboxMarker(content: string): boolean {
+  const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return false;
+  const frontmatter = m[1];
+  // The capture group is mandatory in the pattern above (no `?`), so a successful match
+  // always populates it — but a stray content string could still fail to match at all.
+  if (frontmatter === undefined) return false;
+  return MARKER_LINE_RE.test(frontmatter);
+}

package/src/posix-env.test.ts

@@ -0,0 +1,99 @@
+// Unit tests for the POSIX env-sourcing logic (persistKeyForAgentsPosix), extracted into its
+// own module specifically so it's importable here — wire.ts itself runs main() at module top
+// level and must never be imported by a test (see bin/petbox-wire.js's comment on that).
+//
+// Run: node --test src/posix-env.test.ts   (Node >= 23.6 native TS type-stripping; no build step)
+
+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 { persistKeyForAgentsPosix } from "./posix-env.ts";
+
+const MARKER = "# petbox-wire";
+
+function freshHome(): string {
+  return mkdtempSync(join(tmpdir(), "petbox-wire-test-"));
+}
+
+test("no pre-existing profile files: .zshenv is created and gets the marker (macOS/zsh case)", () => {
+  const home = freshHome();
+  try {
+    assert.equal(existsSync(join(home, ".profile")), false);
+    assert.equal(existsSync(join(home, ".zshenv")), false);
+
+    persistKeyForAgentsPosix(home);
+
+    const zshenvPath = join(home, ".zshenv");
+    assert.equal(existsSync(zshenvPath), true, ".zshenv must be created even with no pre-existing profile files");
+    assert.match(readFileSync(zshenvPath, "utf8"), new RegExp(MARKER));
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("pre-existing .bashrc (no .zshenv): marker still appended to .bashrc, AND .zshenv is created too", () => {
+  const home = freshHome();
+  try {
+    writeFileSync(join(home, ".bashrc"), "# my existing bashrc\n", "utf8");
+
+    persistKeyForAgentsPosix(home);
+
+    const bashrc = readFileSync(join(home, ".bashrc"), "utf8");
+    assert.match(bashrc, new RegExp(MARKER), "existing .bashrc must still get the source line (no regression)");
+    assert.ok(bashrc.includes("# my existing bashrc"), "existing .bashrc content must be preserved");
+
+    const zshenvPath = join(home, ".zshenv");
+    assert.equal(existsSync(zshenvPath), true, ".zshenv must be created even when another profile pre-existed");
+    assert.match(readFileSync(zshenvPath, "utf8"), new RegExp(MARKER));
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("pre-existing .zshenv without the marker: marker gets appended, content preserved", () => {
+  const home = freshHome();
+  try {
+    writeFileSync(join(home, ".zshenv"), "# my existing zshenv\n", "utf8");
+
+    persistKeyForAgentsPosix(home);
+
+    const zshenv = readFileSync(join(home, ".zshenv"), "utf8");
+    assert.match(zshenv, new RegExp(MARKER));
+    assert.ok(zshenv.includes("# my existing zshenv"), "existing .zshenv content must be preserved");
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("idempotent: running twice does not duplicate the marker in .zshenv or .bashrc", () => {
+  const home = freshHome();
+  try {
+    writeFileSync(join(home, ".bashrc"), "# existing\n", "utf8");
+
+    persistKeyForAgentsPosix(home);
+    persistKeyForAgentsPosix(home);
+
+    const countMarker = (s: string) => s.split(MARKER).length - 1;
+    assert.equal(countMarker(readFileSync(join(home, ".bashrc"), "utf8")), 1);
+    assert.equal(countMarker(readFileSync(join(home, ".zshenv"), "utf8")), 1);
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("writes ~/.petbox/env.sh from the key store", () => {
+  const home = freshHome();
+  try {
+    mkdirSync(join(home, ".petbox"), { recursive: true });
+    writeFileSync(join(home, ".petbox", "keys.json"), JSON.stringify({ MY_PROJECT_API_KEY: "secret" }), "utf8");
+
+    persistKeyForAgentsPosix(home);
+
+    const envSh = readFileSync(join(home, ".petbox", "env.sh"), "utf8");
+    assert.match(envSh, /export MY_PROJECT_API_KEY="secret"/);
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});

package/src/posix-env.ts

@@ -0,0 +1,61 @@
+// POSIX half of persistKeyForAgents (see wire.ts) — split into its own side-effect-free module
+// (no top-level main()) so it can be imported directly by tests without triggering the CLI.
+// wire.ts is NOT import-safe: it runs main() at module top level (see bin/petbox-wire.js), so a
+// test must not `import` it — this file exists to give the logic a testable home.
+
+import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+function readJson(path: string): any {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+// Regenerate <homeDir>/.petbox/env.sh from the whole key store and ensure a login shell will
+// source it. Parameterized on homeDir (instead of reading os.homedir() directly) so tests can
+// point it at a throwaway tmp dir rather than touching the real $HOME. Returns the path written,
+// for the caller's log message.
+export function persistKeyForAgentsPosix(homeDir: string): string {
+  const store = readJson(join(homeDir, ".petbox", "keys.json")) ?? {};
+  const lines = Object.entries(store)
+    .filter(([, v]) => typeof v === "string")
+    .map(([k, v]) => `export ${k}=${JSON.stringify(v)}`);
+  const envShPath = join(homeDir, ".petbox", "env.sh");
+  // In production ~/.petbox/ already exists by this point (writeKeyToStore runs first in
+  // main()'s step 4), but mkdirSync recursive is a harmless no-op then — and it makes this
+  // module safe to call standalone (e.g. from tests against a bare tmp dir).
+  mkdirSync(join(homeDir, ".petbox"), { recursive: true });
+  writeFileSync(envShPath, "# Generated by petbox-wire from ~/.petbox/keys.json — do not edit.\n" + lines.join("\n") + "\n", "utf8");
+  try {
+    chmodSync(envShPath, 0o600);
+  } catch {
+    /* best-effort */
+  }
+
+  const marker = "# petbox-wire";
+  const sourceLine = `[ -f "$HOME/.petbox/env.sh" ] && . "$HOME/.petbox/env.sh" ${marker}`;
+  const profilePath = join(homeDir, ".profile");
+  const bashrcPath = join(homeDir, ".bashrc");
+  const zshenvPath = join(homeDir, ".zshenv");
+  const profiles = [profilePath, bashrcPath, zshenvPath];
+  let sourced = false;
+  for (const p of profiles) {
+    if (!existsSync(p)) continue;
+    const content = readFileSync(p, "utf8");
+    if (!content.includes(marker)) appendFileSync(p, `\n${sourceLine}\n`, "utf8");
+    sourced = true;
+  }
+  if (!sourced) writeFileSync(profilePath, sourceLine + "\n", "utf8");
+
+  // zsh always sources ~/.zshenv for EVERY shell (login or not, interactive or not) — unlike
+  // .profile/.bashrc, which bash only sources under specific conditions. macOS ships zsh as the
+  // default shell and a fresh account typically has none of the three files, so the fallback
+  // above (which only ever creates .profile) would silently leave zsh unwired. Guarantee the
+  // marker lands in .zshenv too, independent of whichever profile the loop above touched.
+  if (!existsSync(zshenvPath)) writeFileSync(zshenvPath, sourceLine + "\n", "utf8");
+
+  return envShPath;
+}