@agfpd/iapeer-memory 0.1.13 → 0.2.1

package/src/commands/provision-peer.ts

@@ -0,0 +1,172 @@
+/**
+ * `iapeer-memory provision-peer|unprovision-peer --cwd <abs> --runtime <r>
+ * --personality <p> [--occasion <o>]` — the provider half of the iapeer
+ * v1.2 slot contract
+ * (ADR-009 v1.2: direct per-peer surfaces; the core shells into THIS command
+ * at peer birth/sweeps and never learns the surface forms).
+ *
+ * Contract obligations (§7, agreed with the iapeer core 10.06):
+ *   - argv form, absolute paths, no shell — the core spawns us directly;
+ *   - IDEMPOTENT: re-running repairs, never corrupts (every surface is a
+ *     read-merge-write of our own keys only, atomic);
+ *   - tolerant of PARALLEL calls — the host-wide provision lock serialises
+ *     bodies (lock.ts);
+ *   - {occasion} dictionary: birth | sweep-on | off-peer | off-all | remove.
+ *     We have NO host-global surfaces (требование Артура №3 «глобально не
+ *     класть» — even the codex MCP form is project-local), so the ref-count
+ *     distinction off-peer vs off-all is moot here: every occasion of the
+ *     un-verb means «strip this peer's surfaces». Validated, logged, not
+ *     branched on.
+ *
+ * Runtime forms: claude — hooks + mcp + skills (surfaces/claude.ts);
+ * codex — per-peer MCP via `<cwd>/.codex/config.toml` (surfaces/codex.ts;
+ * hooks/skills are the P5 experiment). Exit: 0 ok, 1 a surface failed,
+ * 2 usage.
+ */
+
+import fs from "node:fs";
+import { memoryPaths } from "../paths.js";
+import {
+  provisionClaudePeer,
+  unprovisionClaudePeer,
+  type SurfaceOutcome,
+} from "../surfaces/claude.js";
+import { provisionCodexPeer, unprovisionCodexPeer } from "../surfaces/codex.js";
+import { withProvisionLock } from "../surfaces/lock.js";
+
+/** The memoryd MCP port FACT of this host (config.env is already loaded into
+ *  the process env by the CLI boot) — baked literally into both MCP surface
+ *  forms (no env substitution in either, D2 decision). Shared by the verbs
+ *  here and the fleet sweeps in init/update/verify. Same resolution as
+ *  status.ts. */
+export function mcpPort(): number {
+  return Number(process.env.IAPEER_MEMORY_MCP_PORT || "") || 8766;
+}
+
+export const OCCASIONS = ["birth", "sweep-on", "off-peer", "off-all", "remove"] as const;
+export type Occasion = (typeof OCCASIONS)[number];
+
+const RUNTIMES = ["claude", "codex"] as const;
+
+type Flags = {
+  cwd: string;
+  runtime: (typeof RUNTIMES)[number];
+  occasion: Occasion;
+  personality: string;
+};
+
+function parseFlags(
+  verb: "provision-peer" | "unprovision-peer",
+  argv: string[],
+  defaultOccasion: Occasion,
+): Flags | null {
+  let cwd = "";
+  let runtime = "";
+  let occasion: string = defaultOccasion;
+  let personality = "";
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    switch (a) {
+      case "--cwd": cwd = argv[++i] ?? ""; break;
+      case "--runtime": runtime = argv[++i] ?? ""; break;
+      case "--occasion": occasion = argv[++i] ?? ""; break;
+      case "--personality": personality = argv[++i] ?? ""; break;
+      default:
+        console.error(`iapeer-memory ${verb}: unknown flag: ${a}`);
+        return null;
+    }
+  }
+  if (!cwd || !cwd.startsWith("/")) {
+    console.error(`iapeer-memory ${verb}: --cwd must be an absolute path (got "${cwd}")`);
+    return null;
+  }
+  if (!(RUNTIMES as readonly string[]).includes(runtime)) {
+    console.error(`iapeer-memory ${verb}: --runtime must be one of ${RUNTIMES.join("|")} (got "${runtime}")`);
+    return null;
+  }
+  if (!(OCCASIONS as readonly string[]).includes(occasion)) {
+    console.error(`iapeer-memory ${verb}: --occasion must be one of ${OCCASIONS.join("|")} (got "${occasion}")`);
+    return null;
+  }
+  // claude provision bakes the LITERAL identity header (battle form of the
+  // core's own .mcp.json) — without the personality there is nothing honest
+  // to bake. The core's executor supports the {personality} placeholder
+  // (agreed 11.06); the package sweep reads it from fleet.json. The un-verb
+  // needs no identity: removal matches our key/marks, not the header value.
+  if (verb === "provision-peer" && runtime === "claude" && !personality) {
+    console.error(
+      "iapeer-memory provision-peer: --personality is required for --runtime claude " +
+        "(the literal MCP identity header is baked at provision time)",
+    );
+    return null;
+  }
+  return {
+    cwd,
+    runtime: runtime as Flags["runtime"],
+    occasion: occasion as Occasion,
+    personality,
+  };
+}
+
+function report(verb: string, flags: Flags, outcomes: SurfaceOutcome[]): number {
+  let failed = false;
+  for (const o of outcomes) {
+    if (o.action === "failed") failed = true;
+    console.log(
+      `${o.action === "failed" ? "FAIL" : "ok  "}  ${o.surface.padEnd(7)} ${o.action}${o.detail ? ` — ${o.detail}` : ""} (${o.path})`,
+    );
+  }
+  console.log(
+    `${verb}: ${flags.runtime} peer at ${flags.cwd} (occasion: ${flags.occasion})` +
+      (failed ? " — FAILED; re-run is the repair path (idempotent)" : "") +
+      "\npickup: surfaces apply on the peer's NEXT session start (live sessions do not re-read them)",
+  );
+  return failed ? 1 : 0;
+}
+
+export function cmdProvisionPeer(argv: string[]): number {
+  const flags = parseFlags("provision-peer", argv, "sweep-on");
+  if (!flags) return 2;
+  if (!fs.existsSync(flags.cwd)) {
+    console.error(`iapeer-memory provision-peer: cwd does not exist: ${flags.cwd}`);
+    return 1;
+  }
+  const paths = memoryPaths();
+  const locked = withProvisionLock({
+    stateDir: paths.stateDir,
+    fn: () =>
+      flags.runtime === "codex"
+        ? provisionCodexPeer({ cwd: flags.cwd, port: mcpPort() })
+        : provisionClaudePeer({
+            cwd: flags.cwd,
+            hooksDir: paths.hooksDir,
+            port: mcpPort(),
+            personality: flags.personality,
+          }),
+  });
+  if (!locked.acquired) {
+    console.error(`iapeer-memory provision-peer: ${locked.detail}`);
+    return 1;
+  }
+  return report("provision-peer", flags, locked.result);
+}
+
+export function cmdUnprovisionPeer(argv: string[]): number {
+  const flags = parseFlags("unprovision-peer", argv, "off-peer");
+  if (!flags) return 2;
+  // a vanished cwd is a VALID un-provision target (occasion=remove races the
+  // peer directory removal) — every surface simply reports `absent`
+  const paths = memoryPaths();
+  const locked = withProvisionLock({
+    stateDir: paths.stateDir,
+    fn: () =>
+      flags.runtime === "codex"
+        ? unprovisionCodexPeer({ cwd: flags.cwd })
+        : unprovisionClaudePeer({ cwd: flags.cwd }),
+  });
+  if (!locked.acquired) {
+    console.error(`iapeer-memory unprovision-peer: ${locked.detail}`);
+    return 1;
+  }
+  return report("unprovision-peer", flags, locked.result);
+}

package/src/commands/status.ts

@@ -14,6 +14,7 @@ import {
   isLocaleId,
   prepareSqliteRuntime,
 } from "@agfpd/iapeer-memory-core";
+import type { Egress } from "../egress.js";
 import { memoryPaths } from "../paths.js";
 import { readSlot } from "../slot.js";
 import { packageVersion } from "../version.js";
@@ -50,10 +51,13 @@ export function searchPipelineLine(env: Record<string, string | undefined>): str
 
 /** Live pipeline from the running memoryd — the same per-component statuses
  * every vault_search returns. Null when memoryd is unreachable. */
-export async function probeSearchPipeline(port: number): Promise<string | null> {
+export async function probeSearchPipeline(
+  egress: Egress,
+  port: number,
+): Promise<string | null> {
   ensureLoopbackNotProxied(); // fleet-class: proxy-env lies about live loopback ports
   try {
-    const res = await fetch(`http://127.0.0.1:${port}/mcp`, {
+    const res = await egress.fetch(`http://127.0.0.1:${port}/mcp`, {
       method: "POST",
       headers: {
         "content-type": "application/json",
@@ -85,10 +89,13 @@ export async function probeSearchPipeline(port: number): Promise<string | null>
   }
 }
 
-async function probeMcp(port: number): Promise<{ line: string; alive: boolean }> {
+async function probeMcp(
+  egress: Egress,
+  port: number,
+): Promise<{ line: string; alive: boolean }> {
   ensureLoopbackNotProxied(); // fleet-class: proxy-env lies about live loopback ports
   try {
-    const res = await fetch(`http://127.0.0.1:${port}/mcp`, {
+    const res = await egress.fetch(`http://127.0.0.1:${port}/mcp`, {
       method: "POST",
       headers: { "content-type": "application/json" },
       body: "{}",
@@ -102,7 +109,7 @@ async function probeMcp(port: number): Promise<{ line: string; alive: boolean }>
   }
 }
 
-export async function cmdStatus(argv: string[]): Promise<number> {
+export async function cmdStatus(argv: string[], egress: Egress): Promise<number> {
   if (argv.length) {
     console.error(`iapeer-memory status: unknown flag: ${argv[0]}`);
     return 2;
@@ -111,7 +118,7 @@ export async function cmdStatus(argv: string[]): Promise<number> {
   const version = packageVersion();
   console.log(`iapeer-memory v${version}`);
 
-  const results = runVerify({ repair: false });
+  const results = runVerify(egress, { repair: false });
   const width = Math.max(...results.map((r) => r.name.length), 12);
   for (const r of results) {
     const mark =
@@ -128,11 +135,11 @@ export async function cmdStatus(argv: string[]): Promise<number> {
   );
 
   const port = Number(process.env.IAPEER_MEMORY_MCP_PORT || "") || 8766;
-  const mcp = await probeMcp(port);
+  const mcp = await probeMcp(egress, port);
   console.log(`      ${"mcp-endpoint".padEnd(width)}  ${mcp.line}`);
   // The live pipeline is only probed when the endpoint is alive — a dead
   // port already told us everything (and the static view says the rest).
-  const livePipeline = mcp.alive ? await probeSearchPipeline(port) : null;
+  const livePipeline = mcp.alive ? await probeSearchPipeline(egress, port) : null;
   console.log(
     `      ${"search".padEnd(width)}  ` +
       (livePipeline ?? `${searchPipelineLine(process.env)} (memoryd down — static view)`),

package/src/commands/uninstall.ts

@@ -3,11 +3,12 @@
  * host. SYMMETRY OBLIGATION of the memory-slot contract: the provider that
  * writes the slot declaration removes it.
  *
- * What it removes: slot declaration (own only — a foreign slot is refused),
- * the compiled binary. What it deliberately KEEPS: the vault (user data),
- * the package config (operator-owned), state/cache (cheap to rebuild, may
- * hold migrate backups!). What lands in P3c: notifier deregistration +
- * memoryd stop (the watcher owns the process lifecycle).
+ * What it removes: direct session surfaces across the fleet (ADR-009 v1.2 —
+ * own entries/keys/dirs only, swept BEFORE the declaration falls), the slot
+ * declaration (own only — a foreign slot is refused), notifier triggers,
+ * memoryd (verified-pid stop), the compiled binary. What it deliberately
+ * KEEPS: the vault (user data), the package config (operator-owned),
+ * state/cache (cheap to rebuild, may hold migrate backups!).
  *
  * Native auto-memory of the fleet is NOT restored (contract decision,
  * c968219): silent re-enabling would quietly resurrect split memory across
@@ -16,9 +17,14 @@
  */
 
 import fs from "node:fs";
+import type { Egress } from "../egress.js";
 import { memoryPaths } from "../paths.js";
 import { removeBinary } from "../binary.js";
+import { readFleetMap } from "../fleet.js";
 import { applyMemoryPlugin, readSlot, removeSlot, SLOT_PROVIDER } from "../slot.js";
+import { withProvisionLock } from "../surfaces/lock.js";
+import { sweepUnprovision } from "../surfaces/sweep.js";
+import { guardedUnlinkSync } from "@agfpd/iapeer-memory-core";
 import {
   DREAM_TRIGGER_ID,
   SWEEP_TRIGGER_ID,
@@ -34,18 +40,12 @@ import {
  * the command closes the "signal a stranger" class. Probe failure → false
  * (never signal on uncertainty).
  */
-export function pidLooksLikeOurs(pid: number): boolean {
-  try {
-    const proc = Bun.spawnSync(["ps", "-o", "command=", "-p", String(pid)], {
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-    if (proc.exitCode !== 0) return false;
-    const command = proc.stdout.toString().trim();
-    return command.includes("memoryd");
-  } catch {
-    return false;
-  }
+export function pidLooksLikeOurs(egress: Egress, pid: number): boolean {
+  // `ps` probe — egress allowance 3 (read-only lookup FEEDING the verified
+  // kill; refusing it would break the guard itself). Never throws.
+  const proc = egress.spawnSync(["ps", "-o", "command=", "-p", String(pid)]);
+  if (proc.spawnError || proc.exitCode !== 0) return false;
+  return proc.stdout.trim().includes("memoryd");
 }
 
 /**
@@ -56,30 +56,27 @@ export function pidLooksLikeOurs(pid: number): boolean {
  * by uninstall (stop) and update (managed restart: SIGTERM → the notifier
  * watcher relaunches via the launcher with the fresh binary, ADR-010).
  */
-export function stopMemorydByPidFile(pidPath: string): string {
+export function stopMemorydByPidFile(egress: Egress, pidPath: string): string {
   let line = "not running (no pid file)";
   try {
     const pid = Number(fs.readFileSync(pidPath, "utf-8").trim());
     if (Number.isInteger(pid) && pid > 1) {
-      if (!pidLooksLikeOurs(pid)) {
+      if (!pidLooksLikeOurs(egress, pid)) {
         line = `pid file points at a non-memoryd process (${pid}) — NOT signalling; stale file removed`;
       } else {
-        try {
-          process.kill(pid, "SIGTERM");
-          line = `SIGTERM sent to pid ${pid} (command verified)`;
-        } catch {
-          line = `stale pid file (process ${pid} gone) — removed`;
-        }
+        line = egress.kill(pid, "SIGTERM").delivered
+          ? `SIGTERM sent to pid ${pid} (command verified)`
+          : `stale pid file (process ${pid} gone) — removed`;
       }
     }
-    fs.unlinkSync(pidPath);
+    guardedUnlinkSync(pidPath);
   } catch {
     // no pid file — nothing to stop
   }
   return line;
 }
 
-export function cmdUninstall(argv: string[]): number {
+export function cmdUninstall(argv: string[], egress: Egress): number {
   let keepBinary = false;
   let iapeerBin = "iapeer";
   for (let i = 0; i < argv.length; i++) {
@@ -95,26 +92,59 @@ export function cmdUninstall(argv: string[]): number {
   const paths = memoryPaths();
   let failed = false;
 
-  // Session plugin OFF across the fleet BEFORE removing the declaration —
-  // the core verb DERIVES the plugin identity from the slot's v1.1 block;
-  // once the declaration is gone there is nothing to derive from (agreed
-  // order with the core, auto-removal: a dead provider's plugin must not
-  // keep injecting). Guard: only when the slot is OURS — running `off`
-  // against a foreign declaration would strip the FOREIGN provider's plugin.
-  // codex nuance: the codex plugin is host-global, so `off` there is always
-  // `--all` semantics; per-peer off on codex answers «use --all».
+  // Direct session surfaces OFF across the fleet BEFORE removing the
+  // declaration (ADR-009 v1.2 mirror symmetry: a dead provider's surfaces
+  // must not keep pointing at a void). Guard: only when the slot is OURS.
   const declared = readSlot(paths.slotPath);
   if (declared && declared.provider === SLOT_PROVIDER) {
-    const off = applyMemoryPlugin({ mode: "off", iapeerBin });
-    console.log(
-      `plugin    : ${
-        off.suppressed
-          ? "skipped (test sandbox — core calls suppressed)"
-          : off.ok
-            ? "session plugin removed across the fleet (memory-plugin off --all; codex side is host-global)"
-            : `off not applied (${off.detail.slice(0, 160)}) — manual fallback (works without the slot): per claude peer \`claude plugin uninstall iapeer-memory@agfpd --scope project\` from its cwd; codex (host-global): \`codex plugin remove iapeer-memory@agfpd\``
-      }`,
-    );
+    const fleet = readFleetMap(paths.fleetMapPath);
+    if (!fleet) {
+      console.log(
+        `surfaces  : fleet map missing/unreadable (${paths.fleetMapPath}) — nothing swept; ` +
+          "manual per peer: iapeer-memory unprovision-peer --cwd <cwd> --runtime <r>",
+      );
+    } else {
+      const locked = withProvisionLock({
+        stateDir: paths.stateDir,
+        fn: () => sweepUnprovision({ fleet }),
+      });
+      if (!locked.acquired) {
+        console.log(`surfaces  : ${locked.detail}`);
+        failed = true;
+      } else {
+        const { results, skipped } = locked.result;
+        const bad = results.filter((r) => !r.ok);
+        console.log(
+          `surfaces  : stripped from ${results.length - bad.length}/${results.length} peer-runtime(s)` +
+            (skipped.length ? ` (${skipped.length} skipped)` : ""),
+        );
+        for (const b of bad) {
+          failed = true;
+          console.log(
+            `surfaces  : FAIL ${b.personality}:${b.runtime} — ${b.outcomes
+              .filter((o) => o.action === "failed")
+              .map((o) => `${o.surface}: ${o.detail ?? "failed"}`)
+              .join("; ")}`,
+          );
+        }
+      }
+    }
+
+    // Legacy v1.1 path: the slot still carries a plugin block — sweep the
+    // session plugin off via the core verb WHILE the declaration is alive
+    // (it derives the identity from it; agreed order, auto-removal).
+    if (declared.plugin) {
+      const off = applyMemoryPlugin(egress, { mode: "off", iapeerBin });
+      console.log(
+        `plugin    : ${
+          off.suppressed
+            ? "skipped (test sandbox — core calls suppressed)"
+            : off.ok
+              ? "legacy session plugin removed across the fleet (memory-plugin off --all; codex side is host-global)"
+              : `off not applied (${off.detail.slice(0, 160)}) — manual fallback (works without the slot): per claude peer \`claude plugin uninstall iapeer-memory@agfpd --scope project\` from its cwd; codex (host-global): \`codex plugin remove iapeer-memory@agfpd\``
+        }`,
+      );
+    }
   }
 
   const slot = removeSlot(paths.slotPath);
@@ -127,7 +157,7 @@ export function cmdUninstall(argv: string[]): number {
 
   // notifier wiring: best-effort unregister of all three triggers (not-found
   // is soft on the notifier side; teaching replies go to the index session).
-  const unreg = unregisterWatcher({ iapeerBin });
+  const unreg = unregisterWatcher(egress, { iapeerBin });
   console.log(
     `watcher   : ${
       unreg.ok
@@ -136,7 +166,7 @@ export function cmdUninstall(argv: string[]): number {
     }`,
   );
   for (const id of [SWEEP_TRIGGER_ID, DREAM_TRIGGER_ID]) {
-    const t = unregisterTimer({ id, iapeerBin });
+    const t = unregisterTimer(egress, { id, iapeerBin });
     console.log(
       `timer     : ${
         t.ok
@@ -146,7 +176,7 @@ export function cmdUninstall(argv: string[]): number {
     );
   }
 
-  console.log(`memoryd   : ${stopMemorydByPidFile(paths.pidPath)}`);
+  console.log(`memoryd   : ${stopMemorydByPidFile(egress, paths.pidPath)}`);
 
   if (keepBinary) {
     console.log(`binary    : kept (${paths.binaryPath})`);