@agfpd/iapeer-memory 0.1.13 → 0.2.1

package/src/commands/update.ts

@@ -12,14 +12,20 @@
  *   3. doctrines  — re-render every role from the roles manifest with the
  *                   fresh version marker; roles pick it up on their next
  *                   cold wake (ADR-007), no restarts;
- *   4. slot       — re-declare with the new version (contract obligation);
- *   5. launcher   — regenerate (in case the binary path moved);
- *   6. memoryd    — MANAGED restart: verified SIGTERM via the pid file →
+ *   4. fleet      — re-write the fleet map from `iapeer list --json`;
+ *   5. surfaces   — direct per-peer session surfaces sweep over the map
+ *                   (ADR-009 v1.2: the «всё на местах у подключённых пиров»
+ *                   duty — both runtimes, idempotent, repairs drift);
+ *   6. plugin-off — v1.1→v1.2 migration: when the on-disk slot still
+ *                   carries a plugin block, sweep the legacy plugin off the
+ *                   fleet (while the old declaration is STILL readable by
+ *                   the core verb) — only after surfaces landed cleanly;
+ *   7. slot       — re-declare in the v1.2 form (provision command blocks,
+ *                   new version — contract obligation);
+ *   8. launcher + triggers + guide — regenerate;
+ *   9. memoryd    — MANAGED restart: verified SIGTERM via the pid file →
  *                   the notifier watcher relaunches through the launcher
- *                   with the NEW binary (exit-detect is unconditional —
- *                   notifier fact). Not running → nothing to do;
- *   7. plugin     — the harness's native plugin update flow (printed hint;
- *                   the package never reaches into harness internals).
+ *                   with the NEW binary. Not running → nothing to do.
  *
  * Idempotent: same version re-run → identical/no-op on every surface.
  */
@@ -34,10 +40,14 @@ import {
   type LocaleId,
 } from "@agfpd/iapeer-memory-core";
 import { installBinary } from "../binary.js";
-import { writeFleetMap } from "../fleet.js";
+import type { Egress } from "../egress.js";
+import { readFleetMap, writeFleetMap } from "../fleet.js";
 import { memoryPaths } from "../paths.js";
 import { readRolesManifest } from "../roles.js";
-import { writeSlot } from "../slot.js";
+import { applyMemoryPlugin, readSlot, writeSlot, SLOT_PROVIDER } from "../slot.js";
+import { withProvisionLock } from "../surfaces/lock.js";
+import { sweepProvision } from "../surfaces/sweep.js";
+import { mcpPort } from "./provision-peer.js";
 import { guideText, materialiseTemplates } from "../templates/index.js";
 import { packageVersion } from "../version.js";
 import {
@@ -50,10 +60,13 @@ import {
 } from "../watcher.js";
 import { stopMemorydByPidFile } from "./uninstall.js";
 
-export function cmdUpdate(argv: string[]): number {
+export function cmdUpdate(argv: string[], egress: Egress): number {
   let skipBinary = false;
-  for (const a of argv) {
+  let iapeerBin: string | undefined;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
     if (a === "--skip-binary") skipBinary = true;
+    else if (a === "--iapeer-bin") iapeerBin = argv[++i];
     else {
       console.error(`iapeer-memory update: unknown flag: ${a}`);
       return 2;
@@ -80,7 +93,7 @@ export function cmdUpdate(argv: string[]): number {
   if (skipBinary) {
     step("binary", "skipped (--skip-binary)");
   } else {
-    const bin = installBinary({ outPath: paths.binaryPath });
+    const bin = installBinary(egress, { outPath: paths.binaryPath });
     step(
       "binary",
       bin.action === "compiled"
@@ -123,24 +136,103 @@ export function cmdUpdate(argv: string[]): number {
     );
   }
 
-  // 4. slot version (contract obligation)
-  const slot = writeSlot({
-    slotPath: paths.slotPath,
-    version,
-    heartbeat: paths.heartbeatPath,
-  });
-  step(
-    "slot",
-    slot.action === "refused-foreign"
-      ? `slot held by foreign provider "${slot.existing?.provider}" — not ours to update`
-      : `${slot.action} (v${version})`,
-    slot.action !== "refused-foreign",
-  );
+  // 4. fleet map — personality → cwd × runtimes (the joint of the surfaces
+  // sweep below AND memoryd's fragment renderer, docs/05). BEFORE surfaces
+  // and BEFORE the memoryd restart: both consume the fresh map.
+  {
+    const fleet = writeFleetMap(egress, { fleetMapPath: paths.fleetMapPath, iapeerBin });
+    step(
+      "fleet",
+      fleet.action === "written"
+        ? fleet.detail
+        : `fleet map not written (${fleet.detail}) — surfaces sweep runs on the LAST map; fragments stay stale until verify --repair`,
+      fleet.action === "written",
+    );
+  }
 
-  // 5. launcher
+  // 5. direct session surfaces sweep (ADR-009 v1.2) — the update duty:
+  // «всё на местах у подключённых пиров, что codex, что claude».
+  const existingSlot = readSlot(paths.slotPath);
+  const slotForeign = existingSlot !== null && existingSlot.provider !== SLOT_PROVIDER;
+  let surfacesOk = false;
+  if (slotForeign) {
+    step("surfaces", "skipped (foreign slot — not our host)");
+  } else {
+    const fleet = readFleetMap(paths.fleetMapPath) ?? [];
+    const locked = withProvisionLock({
+      stateDir: paths.stateDir,
+      fn: () => sweepProvision({ fleet, hooksDir: paths.hooksDir, port: mcpPort() }),
+    });
+    if (!locked.acquired) {
+      step("surfaces", locked.detail, false);
+    } else {
+      const { results, skipped } = locked.result;
+      const failed = results.filter((r) => !r.ok);
+      surfacesOk = failed.length === 0;
+      step(
+        "surfaces",
+        `${results.length - failed.length}/${results.length} peer-runtime(s) in place` +
+          (skipped.length ? `, ${skipped.length} skipped` : "") +
+          " — live sessions pick changes up on next restart",
+        surfacesOk,
+      );
+      for (const f of failed) {
+        console.log(
+          `      surfaces    FAIL ${f.personality}:${f.runtime} — ${f.outcomes
+            .filter((o) => o.action === "failed")
+            .map((o) => `${o.surface}: ${o.detail ?? "failed"}`)
+            .join("; ")}`,
+        );
+      }
+    }
+  }
+
+  // 6. v1.1 → v1.2 migration (one-shot per host): the on-disk slot still
+  // carries a plugin block — sweep the legacy plugin off the fleet WHILE the
+  // old declaration is still readable (the core verb derives the identity
+  // from it), and ONLY after the direct surfaces landed cleanly.
+  let migrationBlocked = false;
+  if (!slotForeign && existingSlot?.plugin) {
+    if (!surfacesOk) {
+      migrationBlocked = true;
+      step(
+        "plugin-off",
+        "POSTPONED: direct surfaces did not land cleanly — legacy plugin and v1.1 slot kept (fix and re-run update)",
+        false,
+      );
+    } else {
+      const off = applyMemoryPlugin(egress, { mode: "off" });
+      step(
+        "plugin-off",
+        off.suppressed
+          ? "skipped (test sandbox — core calls suppressed)"
+          : off.ok
+            ? "legacy v1.1 session plugin swept off the fleet (memory-plugin off --all)"
+            : `legacy plugin off failed (${off.detail.slice(0, 120)}) — manual: iapeer memory-plugin off --all`,
+      );
+    }
+  }
+
+  // 7. slot version + v1.2 form (contract obligation). Kept v1.1 while the
+  // migration is blocked — the legacy channel stays derivable.
+  if (slotForeign) {
+    step("slot", `slot held by foreign provider "${existingSlot?.provider}" — not ours to update`, false);
+  } else if (migrationBlocked) {
+    step("slot", "kept v1.1 declaration (migration postponed — see plugin-off)", false);
+  } else {
+    const slot = writeSlot({
+      slotPath: paths.slotPath,
+      version,
+      binaryPath: paths.binaryPath,
+      heartbeat: paths.heartbeatPath,
+    });
+    step("slot", `${slot.action} (v${version}, provision-command declared)`, slot.action !== "refused-foreign");
+  }
+
+  // 8. launcher
   step("launcher", writeLauncherScript({ launcherPath: paths.launcherPath, binaryPath: paths.binaryPath }));
 
-  // 5b. notifier wiring (ADR-015): same-id re-send REPLACES the trigger —
+  // 8b. notifier wiring (ADR-015): same-id re-send REPLACES the trigger —
   // the idempotent re-target path (old hosts with target=index migrate to
   // target=scriber by this very step).
   {
@@ -156,11 +248,11 @@ export function cmdUpdate(argv: string[]): number {
     } catch {
       // unprovisioned env — registrations below still re-target
     }
-    const w = registerWatcher({ launcherPath: paths.launcherPath });
-    const s = registerTimer({
+    const w = registerWatcher(egress, { launcherPath: paths.launcherPath });
+    const s = registerTimer(egress, {
       message: sweepTimerMessage({ checkScriptPath: paths.checkScriptPath }),
     });
-    const d = registerTimer({ message: dreamTimerMessage() });
+    const d = registerTimer(egress, { message: dreamTimerMessage() });
     const sandboxed = w.suppressed && s.suppressed && d.suppressed;
     step(
       "triggers",
@@ -173,7 +265,7 @@ export function cmdUpdate(argv: string[]): number {
     );
   }
 
-  // 5c. host-wide guide — update an ALREADY-ROLLED-OUT guide only
+  // 8c. host-wide guide — update an ALREADY-ROLLED-OUT guide only
   // (presence = the rollout sanction; init --skip-guide hosts stay
   // untouched). Vault substituted into {{VAULT_PATH}} (дыра 10.06: the
   // literal placeholder left peers without the write path).
@@ -190,28 +282,8 @@ export function cmdUpdate(argv: string[]): number {
     }
   }
 
-  // 5d. fleet map — personality → cwd for memoryd's fragment renderer
-  // (docs/05; дыра 10.06). BEFORE the memoryd restart below: the fresh
-  // daemon renders the whole fleet at startup from this very map.
-  {
-    const fleet = writeFleetMap({ fleetMapPath: paths.fleetMapPath });
-    step(
-      "fleet",
-      fleet.action === "written"
-        ? fleet.detail
-        : `fleet map not written (${fleet.detail}) — fragments stay stale until verify --repair`,
-      fleet.action === "written",
-    );
-  }
-
-  // 6. memoryd managed restart (the watcher relaunches with the new binary)
-  step("memoryd", `${stopMemorydByPidFile(paths.pidPath)} — the notifier watcher relaunches it with the new binary`);
-
-  // 7. plugin — harness-owned surface
-  console.log(
-    "      plugin      update via the harness's native plugin flow " +
-      "(claude/codex plugin manager); the package never reaches into harness internals",
-  );
+  // 9. memoryd managed restart (the watcher relaunches with the new binary)
+  step("memoryd", `${stopMemorydByPidFile(egress, paths.pidPath)} — the notifier watcher relaunches it with the new binary`);
 
   console.log(
     failures

package/src/commands/verify.ts

@@ -25,10 +25,14 @@ import {
   renderDoctrine,
   renderedVersion,
 } from "@agfpd/iapeer-memory-core";
-import { writeFleetMap } from "../fleet.js";
+import type { Egress } from "../egress.js";
+import { readFleetMap, writeFleetMap } from "../fleet.js";
 import { memoryPaths, type MemoryPaths } from "../paths.js";
 import { readRolesManifest } from "../roles.js";
-import { readSlot, writeSlot, SLOT_PROVIDER } from "../slot.js";
+import { readSlot, slotProvisionBlocks, writeSlot, SLOT_PROVIDER } from "../slot.js";
+import { withProvisionLock } from "../surfaces/lock.js";
+import { checkFleetSurfaces, sweepProvision } from "../surfaces/sweep.js";
+import { mcpPort } from "./provision-peer.js";
 import { packageVersion } from "../version.js";
 import {
   dreamTimerMessage,
@@ -65,7 +69,7 @@ type RolesManifest = {
   roles: Array<{ role: string; peerCwd: string; template: string }>;
 };
 
-export function runVerify(opts: VerifyOptions = {}): CheckResult[] {
+export function runVerify(egress: Egress, opts: VerifyOptions = {}): CheckResult[] {
   const repair = opts.repair ?? false;
   const paths = opts.paths ?? memoryPaths();
   const version = opts.version ?? packageVersion();
@@ -95,6 +99,11 @@ export function runVerify(opts: VerifyOptions = {}): CheckResult[] {
 
   // 1b. memory-provider slot (iapeer memory-slot contract): a provisioned
   // host must declare the slot; a FOREIGN slot is never repaired over.
+  // A v1.1 slot (plugin block) is NEVER migrated here — the migration is
+  // update's job (plugin off --all must run while the old declaration is
+  // readable; a SessionStart-kicked repair racing ahead of update would
+  // strand the legacy plugin on the whole fleet).
+  let slotIsLegacyV11 = false;
   if (!configOk) {
     results.push({
       name: "memory-slot",
@@ -103,17 +112,37 @@ export function runVerify(opts: VerifyOptions = {}): CheckResult[] {
     });
   } else {
     const slot = readSlot(paths.slotPath);
+    const expectedBlocks = slotProvisionBlocks(paths.binaryPath);
+    const formOk =
+      slot !== null &&
+      slot.plugin === undefined &&
+      JSON.stringify(slot.provision) === JSON.stringify(expectedBlocks.provision) &&
+      JSON.stringify(slot.unprovision) === JSON.stringify(expectedBlocks.unprovision);
     if (slot && slot.provider !== SLOT_PROVIDER) {
       results.push({
         name: "memory-slot",
         status: "fail",
         detail: `slot held by foreign provider "${slot.provider}" — refusing to touch (uninstall it first)`,
       });
-    } else if (slot && slot.version === version) {
-      results.push({ name: "memory-slot", status: "ok", detail: `declared v${slot.version}` });
+    } else if (slot?.plugin) {
+      slotIsLegacyV11 = true;
+      results.push({
+        name: "memory-slot",
+        status: "fail",
+        detail:
+          "slot is the legacy v1.1 form (plugin block) — migrate via `iapeer-memory update` (verify never migrates: the plugin-off order is update's duty)",
+      });
+    } else if (slot && slot.version === version && formOk) {
+      results.push({
+        name: "memory-slot",
+        status: "ok",
+        detail: `declared v${slot.version}, provision-command in place`,
+      });
     } else {
       const problem = slot
-        ? `slot declares v${slot.version}, package is v${version}`
+        ? slot.version !== version
+          ? `slot declares v${slot.version}, package is v${version}`
+          : "provision-command block missing/drifted"
         : `slot declaration missing at ${paths.slotPath}`;
       if (!repair) {
         results.push({ name: "memory-slot", status: "fail", detail: problem });
@@ -121,6 +150,7 @@ export function runVerify(opts: VerifyOptions = {}): CheckResult[] {
         const w = writeSlot({
           slotPath: paths.slotPath,
           version,
+          binaryPath: paths.binaryPath,
           heartbeat: paths.heartbeatPath,
         });
         results.push(
@@ -159,7 +189,7 @@ export function runVerify(opts: VerifyOptions = {}): CheckResult[] {
       if (!repair) {
         results.push({ name: "fleet-map", status: "fail", detail: problem });
       } else {
-        const w = writeFleetMap({ fleetMapPath: paths.fleetMapPath, iapeerBin: opts.iapeerBin });
+        const w = writeFleetMap(egress, { fleetMapPath: paths.fleetMapPath, iapeerBin: opts.iapeerBin });
         results.push(
           w.action === "written"
             ? { name: "fleet-map", status: "repaired", detail: `${problem} — ${w.detail}` }
@@ -169,6 +199,82 @@ export function runVerify(opts: VerifyOptions = {}): CheckResult[] {
     }
   }
 
+  // 1d. direct per-peer session surfaces (ADR-009 v1.2) across the fleet
+  // map — the self-healing loop for newborns on hosts where the core's
+  // birth-hook lagged AND the drift-repair duty (требование №2). Skipped on
+  // a legacy v1.1 host: the plugin is still the live channel there, direct
+  // surfaces land via update's migration.
+  if (!configOk) {
+    results.push({ name: "peer-surfaces", status: "skip", detail: "not provisioned (config check failed)" });
+  } else if (slotIsLegacyV11) {
+    results.push({
+      name: "peer-surfaces",
+      status: "skip",
+      detail: "legacy v1.1 host (plugin channel) — direct surfaces land via `iapeer-memory update`",
+    });
+  } else {
+    const fleet = readFleetMap(paths.fleetMapPath);
+    if (!fleet) {
+      results.push({
+        name: "peer-surfaces",
+        status: "skip",
+        detail: "fleet map unreadable — see fleet-map check",
+      });
+    } else {
+      const { checks, skipped } = checkFleetSurfaces({
+        fleet,
+        hooksDir: paths.hooksDir,
+        port: mcpPort(),
+      });
+      const bad = checks.filter((c) => !c.ok);
+      if (bad.length === 0) {
+        results.push({
+          name: "peer-surfaces",
+          status: "ok",
+          detail:
+            `${checks.length} peer-runtime(s) in place` +
+            (skipped.length ? ` (${skipped.length} skipped: no session runtime / missing cwd)` : ""),
+        });
+      } else if (!repair) {
+        for (const b of bad) {
+          results.push({
+            name: `peer-surfaces[${b.personality}:${b.runtime}]`,
+            status: "fail",
+            detail: b.problems.join("; "),
+          });
+        }
+      } else {
+        const badPeers = fleet.filter((p) => bad.some((b) => b.cwd === p.cwd));
+        const locked = withProvisionLock({
+          stateDir: paths.stateDir,
+          fn: () => sweepProvision({ fleet: badPeers, hooksDir: paths.hooksDir, port: mcpPort() }),
+        });
+        if (!locked.acquired) {
+          results.push({ name: "peer-surfaces", status: "fail", detail: locked.detail });
+        } else {
+          const stillBad = locked.result.results.filter((r) => !r.ok);
+          results.push(
+            stillBad.length === 0
+              ? {
+                  name: "peer-surfaces",
+                  status: "repaired",
+                  detail: `${bad.length} drifted peer-runtime(s) re-provisioned (${bad
+                    .map((b) => `${b.personality}:${b.runtime}`)
+                    .join(", ")})`,
+                }
+              : {
+                  name: "peer-surfaces",
+                  status: "fail",
+                  detail: `repair failed for ${stillBad
+                    .map((r) => `${r.personality}:${r.runtime}`)
+                    .join(", ")}`,
+                },
+          );
+        }
+      }
+    }
+  }
+
   // 2. memoryd heartbeat
   try {
     const stat = fs.statSync(paths.heartbeatPath);
@@ -238,7 +344,7 @@ export function runVerify(opts: VerifyOptions = {}): CheckResult[] {
               launcherPath: paths.launcherPath,
               binaryPath: paths.binaryPath,
             });
-            return registerWatcher({
+            return registerWatcher(egress, {
               launcherPath: paths.launcherPath,
               iapeerBin: opts.iapeerBin,
             });
@@ -268,7 +374,7 @@ export function runVerify(opts: VerifyOptions = {}): CheckResult[] {
             } catch {
               // unprovisioned env — the registration alone still heals the trigger
             }
-            return registerTimer({
+            return registerTimer(egress, {
               message: sweepTimerMessage({ checkScriptPath: paths.checkScriptPath }),
               iapeerBin: opts.iapeerBin,
             });
@@ -281,7 +387,7 @@ export function runVerify(opts: VerifyOptions = {}): CheckResult[] {
           expect: (t) =>
             t.target !== "index" ? `target is ${t.target ?? "?"}, expected index` : null,
           repairSend: () =>
-            registerTimer({ message: dreamTimerMessage(), iapeerBin: opts.iapeerBin }),
+            registerTimer(egress, { message: dreamTimerMessage(), iapeerBin: opts.iapeerBin }),
         },
       ];
       for (const c of checks) {
@@ -394,17 +500,23 @@ export function runVerify(opts: VerifyOptions = {}): CheckResult[] {
   return results;
 }
 
-export function cmdVerify(argv: string[]): number {
+export function cmdVerify(argv: string[], egress: Egress): number {
   let repair = false;
-  for (const a of argv) {
+  let iapeerBin: string | undefined;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
     if (a === "--repair") repair = true;
+    // Mirror of `update --iapeer-bin` (fb662ed): the hermetic CLI test class
+    // needs an explicitly named core binary — the egress explicit-bin
+    // allowance keys on it.
+    else if (a === "--iapeer-bin") iapeerBin = argv[++i];
     else {
       console.error(`iapeer-memory verify: unknown flag: ${a}`);
       return 2;
     }
   }
 
-  const results = runVerify({ repair });
+  const results = runVerify(egress, { repair, iapeerBin });
   const width = Math.max(...results.map((r) => r.name.length));
   for (const r of results) {
     const mark =

package/src/egress.ts

@@ -0,0 +1,181 @@
+/**
+ * Egress hub — the ONE doorway from this package to the live host
+ * (docs/_planning/DENY_BY_DEFAULT_DESIGN.md §4, accepted by boris 11.06).
+ *
+ * Topology, not another fuse: four incidents («тест дотянулся до прода»)
+ * shared one root — outbound channels were allowed by default and refused
+ * only under a test flag each call site had to remember. This module
+ * inverts the default. Modules never spawn/kill/probe the host themselves
+ * and never PATH-resolve an external binary — they take an explicit
+ * {@link Egress} handle. The single live constructor, {@link liveEgress},
+ * is called from `cli.ts main()`; while a test-sandbox env is armed it
+ * hands back a REFUSING handle instead, and every channel reports refusal
+ * (callers map it to their SKIP semantics — the iapeer `skipped-sandbox`
+ * precedent). A module imported directly by a test has no doorway to the
+ * host by construction: there is nothing to forget.
+ *
+ * The grep invariant (И3) pins the topology: no `Bun.spawn*`/`process.kill`
+ * outside this file in src/.
+ *
+ * EXPLICIT ALLOWANCES of the refusing handle — each narrow, each here, all
+ * in one place (deny by DEFAULT, authorized consciously):
+ *
+ * 1. `explicitBin` spawns — argv[0] was NAMED by the operator/test via a
+ *    flag (`--iapeer-bin <path>`). Same safety class as the sanctioned
+ *    fake-bin test pattern: a consciously named binary is an authorization,
+ *    a PATH-resolved default is not. (Closes the old env-juggling dance:
+ *    fake-bin tests no longer clear the sandbox vars.)
+ * 2. Self-runtime spawns — argv[0] === process.execPath (bun): the binary
+ *    compile (`bun build --compile` to a path-conventioned target) and the
+ *    hook kick (self `verify --repair`). A child process re-enters through
+ *    its OWN main() and inherits the sandbox env → its egress refuses too;
+ *    nothing transitively reaches the host.
+ * 3. `ps` probes — read-only process-table lookup feeding the verified-kill
+ *    guard (`pidLooksLikeOurs`). Refusing it would break the guard whose
+ *    whole job is to make kill() safe.
+ * 4. Loopback fetch — status' own-daemon probes in sandboxed e2e. The
+ *    host-daemon collision is closed by test port isolation (И3), not by
+ *    refusing the probe. Non-loopback fetch refuses.
+ *
+ * kill() stays guarded by the verified-kill contract (owner verification
+ * before signalling — accepted at the P3c review), not by refusal: the pid
+ * PROVENANCE (sandbox pid file vs prod pid file) is the FS-belt's question
+ * (И2), and refusing kill would orphan sandbox daemons in e2e.
+ */
+
+export type EgressSpawnResult = {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  /** Set when the spawn itself failed (binary missing) or the egress
+   *  refused the channel — exitCode is 127 by convention then. */
+  spawnError?: string;
+  /** True when the refusing egress (test sandbox) blocked the channel. */
+  refused?: boolean;
+};
+
+export type EgressSpawnOpts = {
+  timeoutMs?: number;
+  /** argv[0] was explicitly named by the operator/test (a `--*-bin` flag) —
+   *  allowance 1 of the refusing handle. */
+  explicitBin?: boolean;
+};
+
+export interface Egress {
+  /** True for the refusing handle — callers may report a SKIP up front. */
+  readonly refused: boolean;
+  /** External binary, synchronous (iapeer, ps, openssl, security, codesign,
+   *  bun). Never throws — a missing binary is a result, not a crash. */
+  spawnSync(argv: string[], opts?: EgressSpawnOpts): EgressSpawnResult;
+  /** Fire-and-forget detached spawn (hook kick → self `verify --repair`). */
+  spawnDetached(argv: string[]): { started: boolean; detail?: string };
+  /** Signal a live process. Never throws; `delivered: false` = process gone. */
+  kill(pid: number, signal: NodeJS.Signals): { delivered: boolean };
+  /** HTTP probe (status' loopback checks) — read-as-egress (П5). */
+  fetch(url: string, init?: RequestInit): Promise<Response>;
+}
+
+/** Default name of the ecosystem CLI — the ONE place it lives (П2: no
+ *  scattered `?? "iapeer"` defaults; the danger moved into the handle). */
+export const IAPEER_BIN = "iapeer";
+
+/** The ONE definition of the sandbox-env check lives in core's fs-guard
+ *  (the FS belt uses it too) — re-exported here for the constructor and
+ *  its tests. */
+import { sandboxEnvArmed } from "@agfpd/iapeer-memory-core";
+export { sandboxEnvArmed };
+
+function rawSpawnSync(argv: string[], opts?: EgressSpawnOpts): EgressSpawnResult {
+  try {
+    const proc = Bun.spawnSync(argv, {
+      stdout: "pipe",
+      stderr: "pipe",
+      ...(opts?.timeoutMs !== undefined ? { timeout: opts.timeoutMs } : {}),
+    });
+    return {
+      exitCode: proc.exitCode,
+      stdout: proc.stdout.toString(),
+      stderr: proc.stderr.toString(),
+    };
+  } catch (err) {
+    return { exitCode: 127, stdout: "", stderr: "", spawnError: String(err) };
+  }
+}
+
+function rawSpawnDetached(argv: string[]): { started: boolean; detail?: string } {
+  try {
+    const proc = Bun.spawn(argv, {
+      stdout: "ignore",
+      stderr: "ignore",
+      stdin: "ignore",
+    });
+    proc.unref();
+    return { started: true };
+  } catch (err) {
+    return { started: false, detail: String(err) };
+  }
+}
+
+function rawKill(pid: number, signal: NodeJS.Signals): { delivered: boolean } {
+  try {
+    process.kill(pid, signal);
+    return { delivered: true };
+  } catch {
+    return { delivered: false };
+  }
+}
+
+function isLoopback(url: string): boolean {
+  try {
+    const host = new URL(url).hostname;
+    return host === "127.0.0.1" || host === "localhost" || host === "::1";
+  } catch {
+    return false;
+  }
+}
+
+const REFUSAL = "egress refused (test sandbox) — pass a fake egress";
+
+function refusedResult(): EgressSpawnResult {
+  return { exitCode: 127, stdout: "", stderr: "", spawnError: REFUSAL, refused: true };
+}
+
+function refusingEgress(): Egress {
+  return {
+    refused: true,
+    spawnSync(argv, opts) {
+      if (opts?.explicitBin) return rawSpawnSync(argv, opts); // allowance 1
+      if (argv[0] === process.execPath) return rawSpawnSync(argv, opts); // allowance 2
+      if (argv[0] === "ps") return rawSpawnSync(argv, opts); // allowance 3
+      return refusedResult();
+    },
+    spawnDetached(argv) {
+      if (argv[0] === process.execPath) return rawSpawnDetached(argv); // allowance 2
+      return { started: false, detail: REFUSAL };
+    },
+    kill: rawKill, // verified-kill contract guards this, not refusal (header)
+    fetch(url, init) {
+      if (isLoopback(url)) return fetch(url, init); // allowance 4
+      return Promise.reject(new Error(REFUSAL));
+    },
+  };
+}
+
+function realEgress(): Egress {
+  return {
+    refused: false,
+    spawnSync: rawSpawnSync,
+    spawnDetached: rawSpawnDetached,
+    kill: rawKill,
+    fetch: (url, init) => fetch(url, init),
+  };
+}
+
+/**
+ * The ONE live constructor — called from `cli.ts main()` only. Refuses
+ * (hands back the refusing handle) while a test-sandbox env is armed; the
+ * decision is taken ONCE here, never re-checked at call sites.
+ */
+export function liveEgress(): Egress {
+  return sandboxEnvArmed() ? refusingEgress() : realEgress();
+}