@agfpd/iapeer-memory 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer-memory",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "iapeer-memory — peer memory for the iapeer ecosystem: vault, memoryd (index/search/MCP-http), layer-5 context fragments, role doctrines. The package IS the system; the claude/codex plugins are thin session sockets (docs/10-distribution.md, ADR-009).",
   "license": "MIT",
   "type": "module",
@@ -27,7 +27,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@agfpd/iapeer-memory-core": "0.1.2"
+    "@agfpd/iapeer-memory-core": "0.1.3"
   },
   "devDependencies": {
     "@types/bun": "^1.2.0",

package/src/binary.ts

@@ -23,13 +23,14 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import { signInstalledBinary, type SigningOutcome } from "./signing.js";
 
 export function isCompiledRuntime(): boolean {
   return import.meta.url.includes("/$bunfs/");
 }
 
 export type InstallBinaryOutcome =
-  | { action: "compiled"; outPath: string; bytes: number }
+  | { action: "compiled"; outPath: string; bytes: number; signing: SigningOutcome }
   | { action: "skipped-compiled"; outPath: string }
   | { action: "failed"; outPath: string; detail: string };
 
@@ -65,7 +66,10 @@ export function installBinary(opts: { outPath: string }): InstallBinaryOutcome {
 
   fs.chmodSync(tmp, 0o755);
   fs.renameSync(tmp, outPath); // atomic swap — safe over a running binary on macOS
-  return { action: "compiled", outPath, bytes: fs.statSync(outPath).size };
+  // Stable-identity re-sign on EVERY compile path (TCC grants survive
+  // updates — contract with iapeer, see signing.ts). Soft-fail by design.
+  const signing = signInstalledBinary(outPath);
+  return { action: "compiled", outPath, bytes: fs.statSync(outPath).size, signing };
 }
 
 export function removeBinary(outPath: string): "removed" | "absent" {

package/src/commands/init.ts

@@ -41,7 +41,15 @@ import {
   ROLE_NAMES,
 } from "../templates/index.js";
 import { packageVersion } from "../version.js";
-import { registerWatcher, writeLauncherScript } from "../watcher.js";
+import {
+  dreamTimerMessage,
+  patchWakePolicyEphemeral,
+  registerTimer,
+  registerWatcher,
+  sweepTimerMessage,
+  writeLauncherScript,
+  writeStaleCheckScript,
+} from "../watcher.js";
 
 type InitFlags = {
   vault?: string;
@@ -241,7 +249,9 @@ export async function cmdInit(argv: string[]): Promise<number> {
     step(
       "binary",
       bin.action === "compiled"
-        ? `${bin.outPath} (${Math.round(bin.bytes / 1024 / 1024)}MB)`
+        ? `${bin.outPath} (${Math.round(bin.bytes / 1024 / 1024)}MB; signing: ${bin.signing.state}` +
+          `${bin.signing.state === "signed-new-identity" ? " — the one install-time keychain event" : ""}` +
+          `${bin.signing.state === "failed-soft" ? ` — ${bin.signing.detail}` : ""})`
         : bin.action === "skipped-compiled"
           ? `kept existing ${bin.outPath} (running from the installed binary)`
           : `compile failed — ${bin.detail}`,
@@ -291,17 +301,26 @@ export async function cmdInit(argv: string[]): Promise<number> {
       roleEntries.push({ role, peerCwd, template });
     }
     writeRolesManifest({ rolesManifestPath: paths.rolesManifestPath, roles: roleEntries });
+    // The copywriter is the inverted pipeline's first receiver — an
+    // EPHEMERAL worker (clean window per delivery, ADR-015): patch one key
+    // into its core-owned profile, no-clobber.
+    const cwEntry = roleEntries.find((r) => r.role === "copywriter");
+    const wakePolicy = cwEntry ? patchWakePolicyEphemeral(cwEntry.peerCwd) : "missing-profile";
     step(
       "roles",
-      `${roleEntries.map((r) => r.role).join(", ")} (doctrines v${version}, manifest ${paths.rolesManifestPath})`,
-      rolesOk && roleEntries.length === ROLE_NAMES.length,
+      `${roleEntries.map((r) => r.role).join(", ")} (doctrines v${version}, ` +
+        `copywriter wake_policy: ${wakePolicy}, manifest ${paths.rolesManifestPath})`,
+      rolesOk && roleEntries.length === ROLE_NAMES.length && wakePolicy !== "missing-profile",
     );
   }
 
-  // 7. watcher registration (registrant = index; reply goes to the index
-  // session — confirmation is the durable profile, checked by verify)
+  // 7. notifier wiring (ADR-015, инверсия): the EVENT trigger targets the
+  // COPYWRITER (first receiver); two TIMERS target the index — weekly
+  // DREAM_TICK and the check-gated fail-open sweep. Registrant = index for
+  // all three (one durable profile to verify); same-id re-send = replace.
   if (flags.skipEcosystem) {
     step("watcher", "skipped (--skip-ecosystem)");
+    step("timers", "skipped (--skip-ecosystem)");
   } else {
     writeLauncherScript({ launcherPath: paths.launcherPath, binaryPath: paths.binaryPath });
     const sent = registerWatcher({
@@ -310,10 +329,36 @@ export async function cmdInit(argv: string[]): Promise<number> {
     });
     step(
       "watcher",
-      sent.ok
-        ? `registration sent (${paths.launcherPath} → target index); confirm: iapeer-memory verify`
-        : `registration failed — ${sent.detail}`,
-      sent.ok,
+      sent.suppressed
+        ? "skipped (test sandbox — sends suppressed)"
+        : sent.ok
+          ? `registration sent (${paths.launcherPath} → target copywriter); confirm: iapeer-memory verify`
+          : `registration failed — ${sent.detail}`,
+      sent.ok || Boolean(sent.suppressed),
+    );
+
+    writeStaleCheckScript({
+      checkScriptPath: paths.checkScriptPath,
+      vaultPath: vault,
+      inboxFolders: [getTaxonomy(locale).folders.inbox, getTaxonomy(locale).folders.inboxHuman],
+    });
+    const sweep = registerTimer({
+      message: sweepTimerMessage({ checkScriptPath: paths.checkScriptPath }),
+      iapeerBin: flags.iapeerBin,
+    });
+    const dream = registerTimer({
+      message: dreamTimerMessage(),
+      iapeerBin: flags.iapeerBin,
+    });
+    const timersSandboxed = sweep.suppressed && dream.suppressed;
+    step(
+      "timers",
+      timersSandboxed
+        ? "skipped (test sandbox — sends suppressed)"
+        : sweep.ok && dream.ok
+          ? `sweep (@every 1h, check ${paths.checkScriptPath}) + dream-tick (weekly) → target index`
+          : `sweep: ${sweep.ok ? "sent" : sweep.detail}; dream: ${dream.ok ? "sent" : dream.detail}`,
+      Boolean(timersSandboxed) || (sweep.ok && dream.ok),
     );
   }
 

package/src/commands/install-binary.ts

@@ -28,7 +28,8 @@ export function cmdInstallBinary(argv: string[]): number {
   switch (outcome.action) {
     case "compiled":
       console.log(
-        `install-binary: compiled ${outcome.outPath} (${Math.round(outcome.bytes / 1024 / 1024)}MB)`,
+        `install-binary: compiled ${outcome.outPath} (${Math.round(outcome.bytes / 1024 / 1024)}MB; ` +
+          `signing: ${outcome.signing.state}${outcome.signing.state === "failed-soft" ? ` — ${outcome.signing.detail}` : ""})`,
       );
       return 0;
     case "skipped-compiled":

package/src/commands/status.ts

@@ -147,7 +147,9 @@ export async function cmdStatus(argv: string[]): Promise<number> {
     }
     console.log(
       `      ${"inbox".padEnd(width)}  ` +
-        (count < 0 ? `folder missing (${inboxDir})` : `${count} draft(s) awaiting the Index`),
+        (count < 0
+          ? `folder missing (${inboxDir})`
+          : `${count} draft(s) awaiting the pipeline (a growing pile = the copywriter thread is stuck; the sweep places stale drafts unvetted)`),
     );
   }
 

package/src/commands/uninstall.ts

@@ -19,7 +19,13 @@ import fs from "node:fs";
 import { memoryPaths } from "../paths.js";
 import { removeBinary } from "../binary.js";
 import { removeSlot } from "../slot.js";
-import { unregisterWatcher, WATCHER_TRIGGER_ID } from "../watcher.js";
+import {
+  DREAM_TRIGGER_ID,
+  SWEEP_TRIGGER_ID,
+  unregisterTimer,
+  unregisterWatcher,
+  WATCHER_TRIGGER_ID,
+} from "../watcher.js";
 
 /**
  * Owner verification before signalling: the process command line must look
@@ -97,8 +103,8 @@ export function cmdUninstall(argv: string[]): number {
     console.log(`slot      : ${slot === "removed" ? "declaration removed" : "already absent"}`);
   }
 
-  // watcher: best-effort unregister (not-found is soft on the notifier side;
-  // the teaching reply goes to the index session, not here).
+  // 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 });
   console.log(
     `watcher   : ${
@@ -107,6 +113,16 @@ export function cmdUninstall(argv: string[]): number {
         : `unregister not sent (${unreg.detail}) — remove the trigger manually via the watcher peer`
     }`,
   );
+  for (const id of [SWEEP_TRIGGER_ID, DREAM_TRIGGER_ID]) {
+    const t = unregisterTimer({ id, iapeerBin });
+    console.log(
+      `timer     : ${
+        t.ok
+          ? `unregister sent for ${id}`
+          : `unregister not sent for ${id} (${t.detail}) — remove manually via the timer peer`
+      }`,
+    );
+  }
 
   console.log(`memoryd   : ${stopMemorydByPidFile(paths.pidPath)}`);
 

package/src/commands/update.ts

@@ -25,6 +25,7 @@
  */
 
 import {
+  configFromEnv,
   isLocaleId,
   renderDoctrine,
   type LocaleId,
@@ -35,7 +36,14 @@ import { readRolesManifest } from "../roles.js";
 import { writeSlot } from "../slot.js";
 import { materialiseTemplates } from "../templates/index.js";
 import { packageVersion } from "../version.js";
-import { writeLauncherScript } from "../watcher.js";
+import {
+  dreamTimerMessage,
+  registerTimer,
+  registerWatcher,
+  sweepTimerMessage,
+  writeLauncherScript,
+  writeStaleCheckScript,
+} from "../watcher.js";
 import { stopMemorydByPidFile } from "./uninstall.js";
 
 export function cmdUpdate(argv: string[]): number {
@@ -72,7 +80,8 @@ export function cmdUpdate(argv: string[]): number {
     step(
       "binary",
       bin.action === "compiled"
-        ? `recompiled ${bin.outPath} (${Math.round(bin.bytes / 1024 / 1024)}MB)`
+        ? `recompiled ${bin.outPath} (${Math.round(bin.bytes / 1024 / 1024)}MB; signing: ${bin.signing.state}` +
+          `${bin.signing.state === "failed-soft" ? ` — ${bin.signing.detail}` : ""})`
         : bin.action === "skipped-compiled"
           ? "running FROM the installed binary — recompile via: npx @agfpd/iapeer-memory@latest update"
           : `compile failed — ${bin.detail}`,
@@ -120,6 +129,39 @@ export function cmdUpdate(argv: string[]): number {
   // 5. launcher
   step("launcher", writeLauncherScript({ launcherPath: paths.launcherPath, binaryPath: paths.binaryPath }));
 
+  // 5b. notifier wiring (ADR-015): same-id re-send REPLACES the trigger —
+  // the idempotent re-target path (old hosts with target=index migrate to
+  // target=copywriter by this very step).
+  {
+    let inboxFolders: string[] | null = null;
+    try {
+      const config = configFromEnv();
+      inboxFolders = [config.taxonomy.folders.inbox, config.taxonomy.folders.inboxHuman];
+      writeStaleCheckScript({
+        checkScriptPath: paths.checkScriptPath,
+        vaultPath: config.vaultPath,
+        inboxFolders,
+      });
+    } catch {
+      // unprovisioned env — registrations below still re-target
+    }
+    const w = registerWatcher({ launcherPath: paths.launcherPath });
+    const s = registerTimer({
+      message: sweepTimerMessage({ checkScriptPath: paths.checkScriptPath }),
+    });
+    const d = registerTimer({ message: dreamTimerMessage() });
+    const sandboxed = w.suppressed && s.suppressed && d.suppressed;
+    step(
+      "triggers",
+      sandboxed
+        ? "skipped (test sandbox — sends suppressed)"
+        : w.ok && s.ok && d.ok
+          ? `re-sent: event→copywriter, sweep+dream→index (same id = replace); confirm: verify`
+          : `event: ${w.ok ? "sent" : w.detail}; sweep: ${s.ok ? "sent" : s.detail}; dream: ${d.ok ? "sent" : d.detail}`,
+      Boolean(sandboxed) || (w.ok && s.ok && d.ok),
+    );
+  }
+
   // 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`);
 

package/src/commands/verify.ts

@@ -30,9 +30,16 @@ import { readRolesManifest } from "../roles.js";
 import { readSlot, writeSlot, SLOT_PROVIDER } from "../slot.js";
 import { packageVersion } from "../version.js";
 import {
+  dreamTimerMessage,
+  DEFAULT_EVENT_TARGET,
+  DREAM_TRIGGER_ID,
   readWatcherTrigger,
+  registerTimer,
   registerWatcher,
+  sweepTimerMessage,
+  SWEEP_TRIGGER_ID,
   writeLauncherScript,
+  writeStaleCheckScript,
   WATCHER_TRIGGER_ID,
 } from "../watcher.js";
 
@@ -49,6 +56,8 @@ export type VerifyOptions = {
   staleMs?: number;
   /** Injectable for tests. */
   nowMs?: number;
+  /** Injectable for tests — repair MUST NOT reach the live notifier. */
+  iapeerBin?: string;
 };
 
 type RolesManifest = {
@@ -149,56 +158,123 @@ export function runVerify(opts: VerifyOptions = {}): CheckResult[] {
     });
   }
 
-  // 3. notifier watcher registration. The durable trigger lives in the
-  // REGISTRANT's peer profile (canonical storage contract — notifier-runtime
-  // fact, topic memoryd-watcher): registrant = index, whose cwd we know
-  // from the roles manifest. Re-registration is ASYNC (the watcher session
-  // writes the profile on message receipt) — repair reports "sent", a
-  // re-run confirms.
+  // 3. notifier wiring (ADR-015). Durable triggers live in the REGISTRANT's
+  // peer profile (canonical storage contract): registrant = index for all
+  // three — the EVENT trigger (target=copywriter, inverted pipeline), the
+  // sweep timer and the dream timer (both target=index). Re-registration is
+  // ASYNC (same id = replace) — repair reports "sent", a re-run confirms.
   {
     const manifest = readRolesManifest(paths.rolesManifestPath);
     const indexEntry = manifest?.roles.find((r) => r.role === "index") ?? null;
     if (!indexEntry) {
-      results.push({
-        name: "notifier-watcher",
-        status: "skip",
-        detail: "roles manifest has no index peer — init has not run",
-      });
-    } else {
-      const trigger = readWatcherTrigger({ registrantCwd: indexEntry.peerCwd });
-      const scriptOk = trigger?.script === paths.launcherPath;
-      if (trigger && scriptOk) {
+      for (const name of ["notifier-watcher", "sweep-timer", "dream-timer"]) {
         results.push({
-          name: "notifier-watcher",
-          status: "ok",
-          detail: `trigger ${WATCHER_TRIGGER_ID} in index profile → target ${trigger.target ?? "?"}`,
+          name,
+          status: "skip",
+          detail: "roles manifest has no index peer — init has not run",
         });
-      } else {
+      }
+    } else {
+      const registrantCwd = indexEntry.peerCwd;
+      const checks: Array<{
+        name: string;
+        id: string;
+        role: "event" | "time";
+        expect: (t: NonNullable<ReturnType<typeof readWatcherTrigger>>) => string | null;
+        repairSend: () => { ok: boolean; detail: string };
+      }> = [
+        {
+          name: "notifier-watcher",
+          id: WATCHER_TRIGGER_ID,
+          role: "event",
+          expect: (t) =>
+            t.script !== paths.launcherPath
+              ? `script is ${t.script}, expected ${paths.launcherPath}`
+              : t.target !== DEFAULT_EVENT_TARGET
+                ? `target is ${t.target ?? "?"}, expected ${DEFAULT_EVENT_TARGET} (inverted pipeline)`
+                : null,
+          repairSend: () => {
+            writeLauncherScript({
+              launcherPath: paths.launcherPath,
+              binaryPath: paths.binaryPath,
+            });
+            return registerWatcher({
+              launcherPath: paths.launcherPath,
+              iapeerBin: opts.iapeerBin,
+            });
+          },
+        },
+        {
+          name: "sweep-timer",
+          id: SWEEP_TRIGGER_ID,
+          role: "time",
+          expect: (t) =>
+            (t as { check?: string }).check !== paths.checkScriptPath
+              ? `check is ${(t as { check?: string }).check ?? "?"}, expected ${paths.checkScriptPath}`
+              : t.target !== "index"
+                ? `target is ${t.target ?? "?"}, expected index`
+                : null,
+          repairSend: () => {
+            try {
+              const config = configFromEnv();
+              writeStaleCheckScript({
+                checkScriptPath: paths.checkScriptPath,
+                vaultPath: config.vaultPath,
+                inboxFolders: [
+                  config.taxonomy.folders.inbox,
+                  config.taxonomy.folders.inboxHuman,
+                ],
+              });
+            } catch {
+              // unprovisioned env — the registration alone still heals the trigger
+            }
+            return registerTimer({
+              message: sweepTimerMessage({ checkScriptPath: paths.checkScriptPath }),
+              iapeerBin: opts.iapeerBin,
+            });
+          },
+        },
+        {
+          name: "dream-timer",
+          id: DREAM_TRIGGER_ID,
+          role: "time",
+          expect: (t) =>
+            t.target !== "index" ? `target is ${t.target ?? "?"}, expected index` : null,
+          repairSend: () =>
+            registerTimer({ message: dreamTimerMessage(), iapeerBin: opts.iapeerBin }),
+        },
+      ];
+      for (const c of checks) {
+        const trigger = readWatcherTrigger({ registrantCwd, id: c.id, role: c.role });
         const problem = trigger
-          ? `trigger script is ${trigger.script}, expected ${paths.launcherPath}`
-          : `no ${WATCHER_TRIGGER_ID} trigger in ${indexEntry.peerCwd}/.iapeer/peer-profile.json`;
-        if (!repair) {
-          results.push({ name: "notifier-watcher", status: "fail", detail: problem });
-        } else {
-          writeLauncherScript({
-            launcherPath: paths.launcherPath,
-            binaryPath: paths.binaryPath,
+          ? c.expect(trigger)
+          : `no ${c.id} trigger in ${registrantCwd}/.iapeer/peer-profile.json`;
+        if (problem === null) {
+          results.push({
+            name: c.name,
+            status: "ok",
+            detail: `trigger ${c.id} in index profile → target ${trigger!.target ?? "?"}`,
           });
-          const sent = registerWatcher({ launcherPath: paths.launcherPath });
-          results.push(
-            sent.ok
-              ? {
-                  name: "notifier-watcher",
-                  status: "repaired",
-                  detail: `${problem} — re-registration sent (async; re-run verify to confirm)`,
-                }
-              : {
-                  name: "notifier-watcher",
-                  status: "fail",
-                  detail: `${problem}; re-registration failed — ${sent.detail}`,
-                },
-          );
+          continue;
         }
+        if (!repair) {
+          results.push({ name: c.name, status: "fail", detail: problem });
+          continue;
+        }
+        const sent = c.repairSend();
+        results.push(
+          sent.ok
+            ? {
+                name: c.name,
+                status: "repaired",
+                detail: `${problem} — re-registration sent (async; re-run verify to confirm)`,
+              }
+            : {
+                name: c.name,
+                status: "fail",
+                detail: `${problem}; re-registration failed — ${sent.detail}`,
+              },
+        );
       }
     }
   }

package/src/paths.ts

@@ -50,6 +50,8 @@ export type MemoryPaths = {
   templatesDir: 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). */
+  checkScriptPath: string;
 };
 
 export function memoryPaths(
@@ -87,6 +89,7 @@ export function memoryPaths(
       env.IAPEER_MEMORY_BINARY_PATH || path.join(home, ".local", "bin", "iapeer-memory"),
     templatesDir: path.join(path.dirname(configFile), "templates"),
     launcherPath: path.join(path.dirname(configFile), "memoryd-launcher.sh"),
+    checkScriptPath: path.join(path.dirname(configFile), "inbox-stale-check.sh"),
   };
 }
 

package/src/signing.ts

@@ -0,0 +1,168 @@
+/**
+ * Stable code-signing for the compiled binary — TCC grants must SURVIVE
+ * updates. Port of the iapeer reference (their signing.ts, 0079106): the
+ * bun-compiled binary is ad-hoc linker-signed (CDHash-only requirement) —
+ * every update is a NEW TCC subject → re-prompts. On THIS product the
+ * stake is higher: the vault lives in iCloud Drive (~/Library/Mobile
+ * Documents — TCC-protected), memoryd touches it on every index pass.
+ *
+ * CONTRACT with iapeer (topic memory-slot, 10.06, fixed on both sides —
+ * their comment block over SIGNING_IDENTITY_CN, b3f5dd4):
+ * - SHARED CN «iapeer Local Codesign» — one keychain identity per host for
+ *   the whole stack; PER-PRODUCT identifier (ours: com.agfpd.iapeer-memory)
+ *   → designated requirements differ per product, TCC subjects stay
+ *   separate, ONE keychain prompt per host.
+ * - first-needs-creates with the IDENTICAL profile (EKU codeSigning,
+ *   system LibreSSL p12, `security import -T /usr/bin/codesign`).
+ *   Changing the CN or the profile — only by mutual agreement.
+ * - Footnote 1 (race): two installers first-creating the identity
+ *   simultaneously → duplicate CN → codesign "ambiguous identity".
+ *   Residual accepted: installs are operator-sequential; we never sign
+ *   from parallel sweeps.
+ * - Footnote 2 (blast radius): deleting/re-creating the identity changes
+ *   the cert leaf → every product of the stack re-prompts once. The
+ *   accepted price of one shared key.
+ * - Footnote 3 (expiry): the cert lives 3650 days (~2036); expiry =
+ *   re-creation = footnote 2.
+ *
+ * ONE binary = ONE identifier: memoryd is the same Mach-O
+ * (`launcher → exec binary memoryd`), so a single TCC subject covers the
+ * CLI and the daemon.
+ *
+ * Failure policy: SOFT — the binary works ad-hoc-signed exactly as before;
+ * a signing hiccup must never break install/update (reported loud: the
+ * operator learns TCC prompts will re-appear). 90 s ceiling so an
+ * unanswered keychain prompt can't wedge an unattended update.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const SIGNING_IDENTITY_CN = "iapeer Local Codesign";
+export const SIGNING_IDENTIFIER = "com.agfpd.iapeer-memory";
+
+/** System LibreSSL — always present on macOS; its pkcs12 output imports
+ *  into the keychain directly (homebrew OpenSSL 3.x p12 needs -legacy —
+ *  live-caught by the iapeer experiment; pinning the system binary removes
+ *  the PATH-dependent branch). */
+const SYSTEM_OPENSSL = "/usr/bin/openssl";
+
+export type SigningRunner = (
+  cmd: string,
+  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) };
+  }
+};
+
+export type SigningOutcome = {
+  state:
+    | "signed" // re-signed with the existing identity
+    | "signed-new-identity" // identity created this run (the ONE install-time event)
+    | "skipped-sandbox" // tests never touch the real keychain
+    | "failed-soft"; // binary stays ad-hoc (works; TCC prompts return)
+  detail?: string;
+};
+
+/** Deliberately NOT `-v` (valid-only): the self-signed cert reads
+ *  CSSMERR_TP_NOT_TRUSTED, which is fine for signing — `-v` would hide it
+ *  and re-create endlessly (iapeer reference fact). */
+function identityPresent(run: SigningRunner): boolean {
+  const r = run("security", ["find-identity", "-p", "codesigning"]);
+  return r.status === 0 && r.stdout.includes(`"${SIGNING_IDENTITY_CN}"`);
+}
+
+function createIdentity(run: SigningRunner): { ok: boolean; detail?: string } {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "iapeer-memory-signing-"));
+  const key = path.join(dir, "key.pem");
+  const cert = path.join(dir, "cert.pem");
+  const p12 = path.join(dir, "id.p12");
+  // Throwaway transport password — lives seconds inside a 0700 tmp dir.
+  const pass = `iapeer-memory-${process.pid}-${Math.floor(Math.random() * 1e9)}`;
+  try {
+    const req = run(SYSTEM_OPENSSL, [
+      "req", "-x509", "-newkey", "rsa:2048", "-keyout", key, "-out", cert,
+      "-days", "3650", "-nodes", "-subj", `/CN=${SIGNING_IDENTITY_CN}`,
+      "-addext", "keyUsage=digitalSignature",
+      "-addext", "extendedKeyUsage=codeSigning",
+    ]);
+    if (req.status !== 0) {
+      return { ok: false, detail: `openssl req failed: ${req.stderr.trim().split("\n")[0] ?? ""}` };
+    }
+    const exp = run(SYSTEM_OPENSSL, [
+      "pkcs12", "-export", "-inkey", key, "-in", cert, "-out", p12,
+      "-passout", `pass:${pass}`, "-name", SIGNING_IDENTITY_CN,
+    ]);
+    if (exp.status !== 0) {
+      return { ok: false, detail: `openssl pkcs12 failed: ${exp.stderr.trim().split("\n")[0] ?? ""}` };
+    }
+    // -T pre-authorizes codesign in the key's ACL — at most ONE keychain
+    // confirmation at the very first signing (the install-time event).
+    const imp = run("security", ["import", p12, "-P", pass, "-T", "/usr/bin/codesign"]);
+    if (imp.status !== 0) {
+      return { ok: false, detail: `security import failed: ${imp.stderr.trim().split("\n")[0] ?? ""}` };
+    }
+    return { ok: true };
+  } finally {
+    try {
+      fs.rmSync(dir, { recursive: true, force: true });
+    } catch {
+      // best-effort cleanup of the throwaway key material
+    }
+  }
+}
+
+/**
+ * Re-sign the installed binary with the stable local identity (creating it
+ * on first use). Called by installBinary after the atomic rename — every
+ * install/update path — so the designated requirement (and every TCC
+ * grant) stays constant while the bytes change.
+ */
+export function signInstalledBinary(
+  binPath: string,
+  run: SigningRunner = defaultRunner,
+): 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"
+  ) {
+    return { state: "skipped-sandbox", detail: "test sandbox — not touching the real keychain" };
+  }
+  let created = false;
+  if (!identityPresent(run)) {
+    const c = createIdentity(run);
+    if (!c.ok) {
+      return {
+        state: "failed-soft",
+        detail: `${c.detail} — binary stays ad-hoc-signed (works, but TCC prompts will re-appear after updates)`,
+      };
+    }
+    created = true;
+  }
+  const sign = run("codesign", [
+    "-f", "-s", SIGNING_IDENTITY_CN, "--identifier", SIGNING_IDENTIFIER, binPath,
+  ]);
+  if (sign.status !== 0) {
+    return {
+      state: "failed-soft",
+      detail: `codesign failed: ${sign.stderr.trim().split("\n")[0] ?? `exit ${sign.status}`} — binary stays ad-hoc-signed (works, but TCC prompts will re-appear after updates)`,
+    };
+  }
+  return created ? { state: "signed-new-identity" } : { state: "signed" };
+}