@agfpd/iapeer-memory 0.1.13 → 0.2.1

package/src/fleet.ts

@@ -7,13 +7,21 @@
  * new peer wakes → SessionStart kick → `verify --repair` re-writes the
  * map → memoryd renders the newcomer's fragment within a tick.
  *
- * `iapeer list` is READ-ONLY on the host — no test fuse needed here
- * (the fuse class guards host MUTATIONS); deterministic tests pass a
- * fake `iapeerBin` instead.
+ * READ-AS-EGRESS (incident 11.06, the FOURTH of its class — first FILE-path
+ * one): `iapeer list` is read-only, but its RESULT is the target list of the
+ * surfaces sweep — a sandboxed `verify --repair` with no fleet map repaired
+ * the map from the LIVE registry and then swept the LIVE peers' cwds with
+ * direct surfaces (the send-fuse never saw it: no IAP send involved).
+ * Querying the live registry from a test IS the leak — the query now goes
+ * through the egress handle (deny-by-default §4 П5): a refusing handle
+ * blocks the default binary; tests pass a fake `iapeerBin` (explicit-bin
+ * allowance) or write the map file directly.
  */
 
 import fs from "node:fs";
 import path from "node:path";
+import { IAPEER_BIN, type Egress } from "./egress.js";
+import { guardedWriteFileSync } from "@agfpd/iapeer-memory-core";
 
 export type FleetMapResult = {
   action: "written" | "failed";
@@ -21,33 +29,78 @@ export type FleetMapResult = {
   detail: string;
 };
 
-type ListedPeer = { personality?: unknown; cwd?: unknown };
+type ListedPeer = {
+  personality?: unknown;
+  cwd?: unknown;
+  /** iapeer registry: `[{runtime: "claude"|"codex"|…, status}]`. */
+  runtimes?: Array<{ runtime?: unknown }>;
+};
+
+/** Fleet-map entry. `runtimes` (ADR-009 v1.2) names the peer's session
+ *  runtimes from the registry — the surfaces sweep keys its per-runtime
+ *  forms on it (claude: hooks+mcp+skills; codex: project-local MCP).
+ *  Core's memoryd reader takes personality/cwd only — additive, fail-open. */
+export type FleetPeer = { personality: string; cwd: string; runtimes: string[] };
 
-export function writeFleetMap(opts: {
-  fleetMapPath: string;
-  iapeerBin?: string;
-  /** Injectable for tests. */
-  nowIso?: string;
-}): FleetMapResult {
-  const bin = opts.iapeerBin ?? "iapeer";
-  let stdout: string;
+/** Fail-open fleet-map reader (the package side: the surfaces sweep and
+ *  verify's per-peer checks). Missing/unreadable map → null — callers report
+ *  honestly instead of guessing the fleet. Entries without a runtimes array
+ *  (pre-v1.2 maps) read as `runtimes: []` — the sweep skips them until the
+ *  next map re-write (init/update/verify --repair). */
+export function readFleetMap(fleetMapPath: string): FleetPeer[] | null {
   try {
-    const proc = Bun.spawnSync([bin, "list", "--json"], {
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-    if (proc.exitCode !== 0) {
-      return {
-        action: "failed",
-        count: 0,
-        detail:
-          (proc.stderr.toString().trim() || `iapeer list exited ${proc.exitCode}`).slice(0, 160),
-      };
-    }
-    stdout = proc.stdout.toString();
-  } catch (err) {
-    return { action: "failed", count: 0, detail: `${bin} unavailable: ${String(err)}` };
+    const raw = JSON.parse(fs.readFileSync(fleetMapPath, "utf-8")) as {
+      peers?: Array<{ personality?: unknown; cwd?: unknown; runtimes?: unknown }>;
+    };
+    if (!Array.isArray(raw?.peers)) return null;
+    return raw.peers
+      .filter(
+        (p): p is { personality: string; cwd: string; runtimes?: unknown } =>
+          typeof p?.personality === "string" && typeof p?.cwd === "string",
+      )
+      .map((p) => ({
+        personality: p.personality,
+        cwd: p.cwd,
+        runtimes: Array.isArray(p.runtimes)
+          ? p.runtimes.filter((r): r is string => typeof r === "string")
+          : [],
+      }));
+  } catch {
+    return null;
+  }
+}
+
+export function writeFleetMap(
+  egress: Egress,
+  opts: {
+    fleetMapPath: string;
+    iapeerBin?: string;
+    /** Injectable for tests. */
+    nowIso?: string;
+  },
+): FleetMapResult {
+  const bin = opts.iapeerBin ?? IAPEER_BIN;
+  const proc = egress.spawnSync([bin, "list", "--json"], {
+    explicitBin: opts.iapeerBin !== undefined,
+  });
+  if (proc.refused) {
+    return {
+      action: "failed",
+      count: 0,
+      detail: "live-registry query suppressed (test sandbox) — pass a fake iapeerBin",
+    };
+  }
+  if (proc.spawnError) {
+    return { action: "failed", count: 0, detail: `${bin} unavailable: ${proc.spawnError}` };
+  }
+  if (proc.exitCode !== 0) {
+    return {
+      action: "failed",
+      count: 0,
+      detail: (proc.stderr.trim() || `iapeer list exited ${proc.exitCode}`).slice(0, 160),
+    };
   }
+  const stdout = proc.stdout;
 
   let listed: ListedPeer[];
   try {
@@ -57,15 +110,25 @@ export function writeFleetMap(opts: {
     return { action: "failed", count: 0, detail: "iapeer list --json: unparsable output" };
   }
 
-  const peers = listed
+  const peers: FleetPeer[] = listed
     .filter(
-      (p): p is { personality: string; cwd: string } =>
+      (p): p is ListedPeer & { personality: string; cwd: string } =>
         typeof p.personality === "string" &&
         p.personality.trim() !== "" &&
         typeof p.cwd === "string" &&
         p.cwd.trim() !== "",
     )
-    .map((p) => ({ personality: p.personality.trim(), cwd: p.cwd.trim() }));
+    .map((p) => ({
+      personality: p.personality.trim(),
+      cwd: p.cwd.trim(),
+      runtimes: [
+        ...new Set(
+          (Array.isArray(p.runtimes) ? p.runtimes : [])
+            .map((r) => (typeof r?.runtime === "string" ? r.runtime.trim() : ""))
+            .filter(Boolean),
+        ),
+      ],
+    }));
 
   const body =
     JSON.stringify(
@@ -75,7 +138,7 @@ export function writeFleetMap(opts: {
     ) + "\n";
   fs.mkdirSync(path.dirname(opts.fleetMapPath), { recursive: true });
   const tmp = `${opts.fleetMapPath}.tmp`;
-  fs.writeFileSync(tmp, body, "utf-8");
+  guardedWriteFileSync(tmp, body, "utf-8");
   fs.renameSync(tmp, opts.fleetMapPath); // atomic — memoryd may race a read
   return {
     action: "written",

package/src/paths.ts

@@ -48,6 +48,10 @@ export type MemoryPaths = {
   binaryPath: string;
   /** Materialised package-owned templates (roles, guide) — see templates/index.ts. */
   templatesDir: string;
+  /** Materialised hook shims (fail-open bash, 3 lines) — the ABSOLUTE command
+   *  paths merged into peers' `.claude/settings.json` (ownership lives IN THE
+   *  DATA: the command path is the identity of our entries — ADR-009 v1.2). */
+  hooksDir: string;
   /** memoryd launcher — the notifier watcher's script (wraps the stable binary). */
   launcherPath: string;
   /** Sweep check-script — gates the fail-open inbox sweep (ADR-015). */
@@ -92,6 +96,7 @@ export function memoryPaths(
     binaryPath:
       env.IAPEER_MEMORY_BINARY_PATH || path.join(home, ".local", "bin", "iapeer-memory"),
     templatesDir: path.join(path.dirname(configFile), "templates"),
+    hooksDir: path.join(path.dirname(configFile), "hooks"),
     launcherPath: path.join(path.dirname(configFile), "memoryd-launcher.sh"),
     checkScriptPath: path.join(path.dirname(configFile), "inbox-stale-check.sh"),
     fleetMapPath: path.join(stateDir, "fleet.json"),

package/src/provision.ts

@@ -13,6 +13,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import type { LocaleId, TaxonomyPreset } from "@agfpd/iapeer-memory-core";
+import { guardedWriteFileSync } from "@agfpd/iapeer-memory-core";
 
 export type ProvisionResult = {
   createdDirs: string[];
@@ -129,7 +130,7 @@ export function provisionVault(opts: {
       continue;
     }
     fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, content, "utf-8");
+    guardedWriteFileSync(file, content, "utf-8");
     createdFiles.push(rel);
   }
 
@@ -183,6 +184,6 @@ export function writeDefaultConfig(
 ): "written" | "exists" {
   if (fs.existsSync(opts.configFile)) return "exists";
   fs.mkdirSync(path.dirname(opts.configFile), { recursive: true });
-  fs.writeFileSync(opts.configFile, defaultConfigContent(opts), "utf-8");
+  guardedWriteFileSync(opts.configFile, defaultConfigContent(opts), "utf-8");
   return "written";
 }

package/src/roles.ts

@@ -12,6 +12,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import { guardedWriteFileSync } from "@agfpd/iapeer-memory-core";
 
 export type RoleEntry = { role: string; peerCwd: string; template: string };
 
@@ -23,7 +24,7 @@ export function writeRolesManifest(opts: {
 }): void {
   fs.mkdirSync(path.dirname(opts.rolesManifestPath), { recursive: true });
   const tmp = `${opts.rolesManifestPath}.tmp`;
-  fs.writeFileSync(
+  guardedWriteFileSync(
     tmp,
     JSON.stringify({ roles: opts.roles } satisfies RolesManifest, null, 2) + "\n",
     "utf-8",

package/src/signing.ts

@@ -38,6 +38,8 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import type { Egress } from "./egress.js";
+import { guardedRmSync } from "@agfpd/iapeer-memory-core";
 
 export const SIGNING_IDENTITY_CN = "iapeer Local Codesign";
 export const SIGNING_IDENTIFIER = "com.agfpd.iapeer-memory";
@@ -53,22 +55,16 @@ export type SigningRunner = (
   args: string[],
 ) => { status: number | null; stdout: string; stderr: string };
 
-const defaultRunner: SigningRunner = (cmd, args) => {
-  try {
-    const r = Bun.spawnSync([cmd, ...args], {
-      stdout: "pipe",
-      stderr: "pipe",
-      timeout: 90_000,
-    });
-    return {
-      status: r.exitCode,
-      stdout: r.stdout.toString(),
-      stderr: r.stderr.toString(),
-    };
-  } catch (err) {
-    return { status: null, stdout: "", stderr: String(err) };
-  }
-};
+/** The keychain trio (security/openssl/codesign) goes out through the
+ *  egress handle — 90 s ceiling so an unanswered keychain prompt can't
+ *  wedge an unattended update. */
+function egressRunner(egress: Egress): SigningRunner {
+  return (cmd, args) => {
+    const r = egress.spawnSync([cmd, ...args], { timeoutMs: 90_000 });
+    if (r.spawnError) return { status: null, stdout: "", stderr: r.spawnError };
+    return { status: r.exitCode, stdout: r.stdout, stderr: r.stderr };
+  };
+}
 
 export type SigningOutcome = {
   state:
@@ -120,7 +116,7 @@ function createIdentity(run: SigningRunner): { ok: boolean; detail?: string } {
     return { ok: true };
   } finally {
     try {
-      fs.rmSync(dir, { recursive: true, force: true });
+      guardedRmSync(dir, { recursive: true, force: true });
     } catch {
       // best-effort cleanup of the throwaway key material
     }
@@ -134,14 +130,14 @@ function createIdentity(run: SigningRunner): { ok: boolean; detail?: string } {
  * grant) stays constant while the bytes change.
  */
 export function signInstalledBinary(
+  egress: Egress,
   binPath: string,
-  run: SigningRunner = defaultRunner,
+  run: SigningRunner = egressRunner(egress),
 ): SigningOutcome {
-  // Both test belts (keychain is HOST-GLOBAL, same class as live sends).
-  if (
-    process.env.IAPEER_TEST_SANDBOX === "1" ||
-    process.env.IAPEER_MEMORY_SUPPRESS_IAP_SEND === "1"
-  ) {
+  // The keychain is HOST-GLOBAL — same class as live sends. The sandbox
+  // decision lives in the egress constructor (deny-by-default §4); a
+  // refusing handle maps to the historical skipped-sandbox outcome.
+  if (egress.refused) {
     return { state: "skipped-sandbox", detail: "test sandbox — not touching the real keychain" };
   }
   let created = false;

package/src/slot.ts

@@ -1,8 +1,8 @@
 /**
- * Memory-provider slot declaration — the iapeer memory-slot contract (FINAL,
- * iapeer docs fc68c54/e2195a7/c968219). The slot file tells the core that
- * the three public surfaces (layer-5 fragments / MCP tools / daemon under a
- * notifier watcher) are occupied:
+ * Memory-provider slot declaration — the iapeer memory-slot contract (FINAL
+ * base, iapeer docs fc68c54/e2195a7/c968219; v1.2 revision agreed 11.06).
+ * The slot file tells the core that the three public surfaces (layer-5
+ * fragments / MCP tools / daemon under a notifier watcher) are occupied:
  *
  * - the PROVIDER writes and removes the file (our init/uninstall), atomic
  *   temp+rename; the core only reads it (absent/unreadable = empty slot);
@@ -12,23 +12,33 @@
  *   marker, ADR-010); our `update` re-writes it (P4 obligation);
  * - `heartbeat` (optional) = the absolute path whose mtime memoryd touches —
  *   the core may show staleness in `iapeer status`, never acts on it;
- * - `plugin` (v1.1, agreed 10.06 + live in iapeer 0.2.25) = the marketplace
- *   identity of the session plugin. The core DERIVES installs from this block:
- *   birth-hook installs for new peers, `iapeer memory-plugin on|off (--peer|
- *   --all)` is the operator verb (built-in marketplace ensure + stale-cache
- *   retry). Reference reader: iapeer src/status/index.ts parsePluginBlock —
- *   all three fields required non-empty, anything less = treated as a v1
- *   declaration (no install). marketplaceRef matches iapeer onboard's
- *   MARKETPLACE_REF for the distribution default.
+ * - `provision`/`unprovision` (v1.2, ADR-009 v1.2 — boris's birth-joint
+ *   inversion, schema fixed with the core 11.06): the PROVIDER's OWN command
+ *   the core shells into at peer birth / verb sweeps / peer removal. The
+ *   core never learns the surface forms; placeholders {cwd} {runtime}
+ *   {personality} {occasion} substitute PER-ARGUMENT (argv spawn, no shell,
+ *   120s timeout, best-effort + loud warn). Precedence at the core:
+ *   provision > plugin with NO runtime fallback;
+ * - `plugin` (v1.1, deprecated by v1.2): we no longer WRITE it — holding
+ *   both blocks would make an old core re-install the plugin we swept
+ *   (agreed 11.06). An old core reads our v1.2 slot as «provider without a
+ *   plugin» and honestly skips the birth install; the newborn is picked up
+ *   by the verify --repair sweep. RELEASE ORDER closes even that window on
+ *   this host: the core ships its v1.2 parser FIRST, our release follows.
+ *   The type keeps the field so uninstall/update can MIGRATE old slots
+ *   (plugin off --all while the block is still readable).
  */
 
 import fs from "node:fs";
 import path from "node:path";
+import { IAPEER_BIN, type Egress } from "./egress.js";
+import { guardedWriteFileSync, guardedUnlinkSync } from "@agfpd/iapeer-memory-core";
 
 export const SLOT_PROVIDER = "iapeer-memory";
 export const SLOT_PACKAGE = "@agfpd/iapeer-memory";
 
-/** Mirror of iapeer's MemoryProviderPlugin (src/status/index.ts). */
+/** Mirror of iapeer's MemoryProviderPlugin (src/status/index.ts). v1.1
+ *  legacy: READ-only here (migration off-path); v1.2 slots no longer carry it. */
 export type MemoryProviderPlugin = {
   /** Plugin id in the marketplace (forms `<name>@<marketplace>`). */
   name: string;
@@ -38,19 +48,54 @@ export type MemoryProviderPlugin = {
   marketplaceRef: string;
 };
 
-export const SLOT_PLUGIN: MemoryProviderPlugin = {
-  name: "iapeer-memory",
-  marketplace: "agfpd",
-  marketplaceRef: "agfpd/agfpd-marketplace",
+/** v1.2 provision command block — argv form (§7 req 1: per-argument
+ *  placeholder substitution, spawn without a shell). */
+export type MemoryProviderCommand = {
+  /** Absolute path (§7 req 2: birth-hooks live in a minimal launchd PATH). */
+  command: string;
+  args: string[];
 };
 
+/** The provision/unprovision blocks of OUR slot — built around the stable
+ *  installed binary (the same path the hooks/watcher rely on). */
+export function slotProvisionBlocks(binaryPath: string): {
+  provision: MemoryProviderCommand;
+  unprovision: MemoryProviderCommand;
+} {
+  return {
+    provision: {
+      command: binaryPath,
+      args: [
+        "provision-peer",
+        "--cwd", "{cwd}",
+        "--runtime", "{runtime}",
+        "--personality", "{personality}",
+        "--occasion", "{occasion}",
+      ],
+    },
+    unprovision: {
+      command: binaryPath,
+      args: [
+        "unprovision-peer",
+        "--cwd", "{cwd}",
+        "--runtime", "{runtime}",
+        "--occasion", "{occasion}",
+      ],
+    },
+  };
+}
+
 export type MemoryProviderSlot = {
   provider: string;
   package: string;
   version: string;
   registeredAt: string;
   heartbeat?: string;
+  /** v1.1 legacy (read for migration; never written by v1.2 code). */
   plugin?: MemoryProviderPlugin;
+  /** v1.2 (ADR-009 v1.2). */
+  provision?: MemoryProviderCommand;
+  unprovision?: MemoryProviderCommand;
 };
 
 /** Never throws: missing / unreadable / malformed → null (empty slot). */
@@ -72,6 +117,8 @@ export type SlotWriteResult = {
 export function writeSlot(opts: {
   slotPath: string;
   version: string;
+  /** Absolute path of the installed binary — the provision command carrier. */
+  binaryPath: string;
   heartbeat?: string;
   /** Injectable for tests. */
   nowIso?: string;
@@ -80,15 +127,15 @@ export function writeSlot(opts: {
   if (existing && existing.provider !== SLOT_PROVIDER) {
     return { action: "refused-foreign", existing };
   }
+  const blocks = slotProvisionBlocks(opts.binaryPath);
   if (
     existing &&
     existing.version === opts.version &&
     existing.heartbeat === opts.heartbeat &&
     existing.package === SLOT_PACKAGE &&
-    existing.plugin &&
-    existing.plugin.name === SLOT_PLUGIN.name &&
-    existing.plugin.marketplace === SLOT_PLUGIN.marketplace &&
-    existing.plugin.marketplaceRef === SLOT_PLUGIN.marketplaceRef
+    existing.plugin === undefined && // a v1.1 slot (plugin block) must MIGRATE to the v1.2 form
+    JSON.stringify(existing.provision) === JSON.stringify(blocks.provision) &&
+    JSON.stringify(existing.unprovision) === JSON.stringify(blocks.unprovision)
   ) {
     return { action: "identical", existing }; // idempotent re-init: no churn
   }
@@ -98,11 +145,11 @@ export function writeSlot(opts: {
     version: opts.version,
     registeredAt: opts.nowIso ?? new Date().toISOString(),
     ...(opts.heartbeat ? { heartbeat: opts.heartbeat } : {}),
-    plugin: SLOT_PLUGIN,
+    ...blocks,
   };
   fs.mkdirSync(path.dirname(opts.slotPath), { recursive: true });
   const tmp = `${opts.slotPath}.tmp`;
-  fs.writeFileSync(tmp, JSON.stringify(slot, null, 2) + "\n", "utf-8");
+  guardedWriteFileSync(tmp, JSON.stringify(slot, null, 2) + "\n", "utf-8");
   fs.renameSync(tmp, opts.slotPath);
   return { action: "written", existing };
 }
@@ -114,7 +161,7 @@ export function removeSlot(slotPath: string): SlotRemoveResult {
   const existing = readSlot(slotPath);
   if (!existing) return "absent";
   if (existing.provider !== SLOT_PROVIDER) return "refused-foreign";
-  fs.unlinkSync(slotPath);
+  guardedUnlinkSync(slotPath);
   return "removed";
 }
 
@@ -134,40 +181,38 @@ export type MemoryPluginApplyResult = {
  * and `off` runs BEFORE removeSlot (agreed order, auto-removal: a dead
  * provider's plugin must not keep injecting).
  *
- * Hard fuse first (same class as iapSend, incident 10.06): `on --all`
- * mutates the HOST fleet — no sandbox env contains it, tests must never
- * reach the live core. Both belts honoured.
+ * The hard fuse of incident 10.06 (`on --all` mutates the HOST fleet — no
+ * sandbox env contains it) lives in the egress constructor now
+ * (deny-by-default §4): a refusing handle blocks the spawn here.
  */
-export function applyMemoryPlugin(opts: {
-  mode: "on" | "off";
-  iapeerBin?: string;
-}): MemoryPluginApplyResult {
-  if (
-    process.env.IAPEER_MEMORY_SUPPRESS_IAP_SEND === "1" ||
-    process.env.IAPEER_TEST_SANDBOX === "1"
-  ) {
+export function applyMemoryPlugin(
+  egress: Egress,
+  opts: {
+    mode: "on" | "off";
+    iapeerBin?: string;
+  },
+): MemoryPluginApplyResult {
+  const bin = opts.iapeerBin ?? IAPEER_BIN;
+  const proc = egress.spawnSync([bin, "memory-plugin", opts.mode, "--all"], {
+    explicitBin: opts.iapeerBin !== undefined,
+  });
+  if (proc.refused) {
     return {
       ok: false,
       suppressed: true,
       detail: "memory-plugin call suppressed (test sandbox)",
     };
   }
-  const bin = opts.iapeerBin ?? "iapeer";
-  try {
-    const proc = Bun.spawnSync([bin, "memory-plugin", opts.mode, "--all"], {
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-    if (proc.exitCode !== 0) {
-      return {
-        ok: false,
-        detail:
-          (proc.stderr.toString().trim() || proc.stdout.toString().trim() || "").slice(0, 200) ||
-          `iapeer memory-plugin exited ${proc.exitCode}`,
-      };
-    }
-    return { ok: true, detail: proc.stdout.toString().trim() };
-  } catch (err) {
-    return { ok: false, detail: `${bin} unavailable: ${String(err)}` };
+  if (proc.spawnError) {
+    return { ok: false, detail: `${bin} unavailable: ${proc.spawnError}` };
+  }
+  if (proc.exitCode !== 0) {
+    return {
+      ok: false,
+      detail:
+        (proc.stderr.trim() || proc.stdout.trim() || "").slice(0, 200) ||
+        `iapeer memory-plugin exited ${proc.exitCode}`,
+    };
   }
+  return { ok: true, detail: proc.stdout.trim() };
 }