@agfpd/iapeer 0.2.25 → 0.2.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.2.25",
+  "version": "0.2.26",
   "description": "Foundation core for the iapeer multi-agent ecosystem: identity, registry, storage, codec.",
   "type": "module",
   "bin": {

package/src/cli/cli.test.ts

@@ -130,6 +130,17 @@ describe('remove (registry record via the locked writer)', () => {
     expect((await removePeerCli('twice', { env: e })).action).toBe('removed')
     expect((await removePeerCli('twice', { env: e })).action).toBe('absent')
   })
+  test('self-done arms the caller\'s own quiet-reap (non-waking silent finish); refuses without PEER_IDENTITY', async () => {
+    const e = env()
+    // no PEER_IDENTITY → self-call refusal
+    expect(await runCli(['self-done'], e)).toBe(1)
+    // with PEER_IDENTITY → marker set, exit 0, nobody contacted
+    const e2 = { ...e, PEER_IDENTITY: 'claude-silentworker' }
+    expect(await runCli(['self-done'], e2)).toBe(0)
+    const { hasEphemeralArmed } = await import('../lifecycle/index.ts')
+    expect(hasEphemeralArmed(loadLifecycleConfig(e2), 'claude-silentworker')).toBe(true)
+  })
+
   test('purges identity-keyed lifecycle state with the record — a namesake newborn must not inherit a dead peer\'s parking (boris 10.06)', async () => {
     await register('reborn')
     const e = env()

package/src/cli/index.ts

@@ -30,11 +30,13 @@ import {
   clearStopped,
   folderLaunch,
   isLaunchdManaged,
+  isEphemeralPeer,
   isStopped,
   killSession,
   loadLifecycleConfig,
   purgeIdentityState,
   removeSessionState,
+  setEphemeralArmed,
   setIdleReaped,
   setNewEager,
   setStopped,
@@ -348,8 +350,9 @@ export async function sendMessage(
   // unawaited in-process wake would die with it; the daemon's supervise-tick
   // drain scan (≤60 s) picks the queue up — the EXISTING retry path for failed
   // kicks, not a new mechanism.
-  const { makeEphemeralRouteDeps } = await import('../daemon/main.ts')
+  const { makeArmEphemeralOnDelivered, makeEphemeralRouteDeps } = await import('../daemon/main.ts')
   const cfg = loadLifecycleConfig(env)
+  const t0 = Date.now()
   const result = await routeSend(
     caller,
     {
@@ -361,7 +364,39 @@ export async function sendMessage(
     },
     { wake: cliWake, ephemeral: makeEphemeralRouteDeps(cfg, env, () => {}) },
   )
+  // delivery.log sink — CLI-path parity (boris's observability gap 10.06: enqueues
+  // routed through the CLI left to=<peer> at ZERO for the day while real wakes
+  // happened; the daemon tool-path logs, this path was blind). Same fields, plus
+  // path=cli so the two entry points are distinguishable. Both branches logged.
+  const { appendDeliveryEvent } = await import('../daemon/deliverylog.ts')
+  appendDeliveryEvent(cfg.eventLogDir, {
+    ev: 'delivery',
+    path: 'cli',
+    caller: caller.address,
+    to: opts.target,
+    rt: opts.runtime,
+    ok: String(result.ok),
+    via: result.ok ? `${result.value.delivered_to.runtime}-${result.value.delivered_to.personality}` : undefined,
+    woke: result.ok ? String(result.value.woke) : undefined,
+    queued: result.ok && result.value.queued ? 'true' : undefined,
+    qd: result.ok ? result.value.queueDepth : undefined,
+    ms: Date.now() - t0,
+    len: opts.message.length,
+    att: opts.attachments?.length || undefined,
+    topic: opts.topic,
+    err: result.ok ? undefined : result.error.message,
+  })
   if (!result.ok) throw new Error(result.error.message)
+  // M2 arm-on-outbound — CLI-path parity (live gap 10.06: an ephemeral worker's
+  // final reply sent through the CLI fallback — e.g. inside a daemon-restart
+  // window, four deploys that day — never armed, so the worker idled to the
+  // unarmed bound and stalled its FIFO). Same hook the daemon path uses; ONLY on
+  // an ok outcome, errors swallowed (arming is best-effort, never fails the send).
+  try {
+    makeArmEphemeralOnDelivered(cfg)(caller)
+  } catch {
+    /* best-effort */
+  }
   return {
     ok: true,
     delivered_to: result.value.delivered_to,
@@ -432,6 +467,7 @@ const USAGE = `usage: iapeer <verb> [args]
   interrupt <peer> [runtime]                                     interrupt the current turn (Escape) — context intact
   compact <peer> [runtime]                                       compact the peer's context (/compact)
   self-fresh                                                     (agent self-call) mark /new eager-fresh + self-kill — the daemon relaunches fresh
+  self-done                                                      (agent self-call, ephemeral) silent finish: arm own quiet-reap, wake no one
   native-memory <off|on> (--peer <p> | --all)                    gate/restore runtimes' native memory (canonized lever; контракт «Слот памяти»)
   memory-plugin <on|off> (--peer <p> | --all)                    install/remove the slot-declared provider plugin (claude per-peer, codex host-global)
 `
@@ -913,6 +949,37 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         if (!positionals[0] || !positionals[1]) return usage(errOut)
         return await runAlwaysOn(positionals[0], positionals[1], process.cwd())
       }
+      case 'self-done': {
+        // SILENT-FINISH self-call for an ephemeral worker (контракт ЖЦ §wake_policy;
+        // развилка boris 10.06): a worker whose task produced NOTHING to send must
+        // still release its M3 FIFO — but an EMPTY report would violate Артур's
+        // invariant «событие-всё-отфильтровано = тишина» (no empty wakes of the
+        // target). This verb is the non-waking arm: it sets the worker's OWN
+        // .ephemeral-armed (same marker the ok-outbound hook sets), so the quiet
+        // window reaps it within seconds and the drain feeds the next task — nobody
+        // is woken. Doctrine for silent finishers: «нечего отправлять → iapeer
+        // self-done вместо ответа». The unarmed idle bound (ephemeralUnarmedIdleSecs)
+        // remains the backstop for workers that do neither. On a NON-ephemeral peer
+        // the marker is inert (quiet-reap keys on wake_policy) — warn, exit 0.
+        const identity = env.PEER_IDENTITY?.trim()
+        if (!identity) {
+          errOut('self-done: PEER_IDENTITY is not set — this verb is an agent self-call from inside a session\n')
+          return 1
+        }
+        if (!parseSessionName(identity)) {
+          errOut(`self-done: invalid PEER_IDENTITY "${identity}" — expected <runtime>-<personality>\n`)
+          return 1
+        }
+        const cfg = loadLifecycleConfig(env)
+        setEphemeralArmed(cfg, identity)
+        const ephemeral = isEphemeralPeer(process.cwd())
+        out(
+          `self-done: armed ${identity} for the quiet-window reap (no one woken)` +
+            (ephemeral ? '' : ' — NOTE: this peer is not wake_policy:ephemeral, the marker is inert') +
+            '\n',
+        )
+        return 0
+      }
       case 'self-fresh': {
         // /new AGENT-FACING TRIGGER (TARGET redesign). Run BY the agent itself as the
         // FINAL step of a /new graceful wind-down (the owner triggers it via a per-peer

package/src/lifecycle/index.ts

@@ -79,6 +79,16 @@ export interface LifecycleConfig {
    *  transcript mtime is a LIVENESS proxy — "no longer writing" — not a semantic
    *  "done" signal. */
   ephemeralQuietSecs: number
+  /** wake_policy:ephemeral — the UNARMED idle bound (seconds): an ephemeral session
+   *  that never armed (finished silently / lost its arm to a daemon-restart window)
+   *  is reaped after this much activity-proxy silence. Live case (scriber 10.06):
+   *  a worker that ended «тихо» without its final outbound stalled its M3 FIFO for
+   *  the FULL generic idleSecs (1 h) — with serial drain that blocks the whole
+   *  conveyor per silent worker. Bound chosen ≫ the legitimate silent-tool case
+   *  (sleep-180) and ≪ idleSecs. DOCUMENTED RISK: an ephemeral worker whose tool
+   *  stays silent longer than this MID-TASK is reaped and its consumed queue item
+   *  is lost — ephemeral workers must emit activity (or their reply) within it. */
+  ephemeralUnarmedIdleSecs: number
 }
 
 export function loadLifecycleConfig(env: NodeJS.ProcessEnv = process.env): LifecycleConfig {
@@ -102,6 +112,7 @@ export function loadLifecycleConfig(env: NodeJS.ProcessEnv = process.env): Lifec
     crashLoopMax: num(env.IAPEER_CRASHLOOP_MAX, 3),
     crashLoopWindowSecs: num(env.IAPEER_CRASHLOOP_WINDOW_SECS, 300),
     ephemeralQuietSecs: num(env.IAPEER_EPHEMERAL_QUIET_SECS, 20),
+    ephemeralUnarmedIdleSecs: num(env.IAPEER_EPHEMERAL_UNARMED_IDLE_SECS, 600),
   }
 }
 
@@ -1140,6 +1151,30 @@ export function superviseTick(cfg: LifecycleConfig, deps: SuperviseDeps = {}): S
       trace({ identity: s.identity, action: 'reaped-ephemeral', age: `${ageSecs}s`, outcome: 'ephemeral-done' })
       continue
     }
+    // UNARMED ephemeral idle bound (live case scriber 10.06): a worker that ended
+    // SILENTLY (no final outbound → never armed; or its arm was lost to a CLI/
+    // daemon-restart window) used to wait out the FULL generic idleSecs (1 h) —
+    // and the M3 serial drain waits for the session's death, so ONE silent worker
+    // stalled its whole conveyor. This bound is the defense-in-depth backstop:
+    // ≫ the legitimate silent-tool case (sleep-180), ≪ idleSecs. The ШТАТНЫЙ
+    // silent-finish path is `iapeer self-done` (arm without waking anyone —
+    // Артур's invariant «нет пустых пробуждений» stays intact); this branch only
+    // bounds the damage when a worker does neither. Policy reap: NO .idle-reaped
+    // (ephemeral never resumes), NO recordDeath (the ring counts faults).
+    if (isEphemeralPeer(s.cwd) && ageSecs > cfg.ephemeralUnarmedIdleSecs) {
+      killSession(sock, s.identity)
+      clearEphemeralArmed(cfg, s.identity)
+      removeSessionState(cfg, s.identity)
+      out.push({
+        identity: s.identity,
+        action: 'reaped-ephemeral',
+        reason: `unarmed idle ${ageSecs}s (silent-finish backstop; штатный путь — iapeer self-done)`,
+        personality: s.personality,
+        runtime: s.runtime,
+      })
+      trace({ identity: s.identity, action: 'reaped-ephemeral', age: `${ageSecs}s`, outcome: 'ephemeral-unarmed-bound' })
+      continue
+    }
     if (ageSecs > cfg.idleSecs) {
       // THE ONLY place .idle-reaped is written: this is the one death the daemon
       // INITIATES. Its presence on the next wake = the session was parked cleanly =

package/src/lifecycle/lifecycle.test.ts

@@ -802,6 +802,69 @@ describe('superviseTick quiet-reap (M2 die-after-reply, real tmux)', () => {
     },
     30000,
   )
+
+  test.if(tmuxAvailable)(
+    'UNARMED ephemeral past the unarmed idle bound → reaped-ephemeral (silent-finish backstop; live case scriber 10.06)',
+    () => {
+      const root = mkdtempSync(join(tmpdir(), 'iapeer-eu-root-'))
+      const laDir = mkdtempSync(join(tmpdir(), 'iapeer-eu-la-'))
+      const cwd = profileCwd(false, true) // ephemeral worker profile
+      const env = {
+        ...process.env,
+        IAPEER_ROOT: root,
+        IAPEER_LAUNCHAGENTS_DIR: laDir,
+        IAPEER_SOCK_DIR: join(root, 'socks'),
+        IAPEER_EPHEMERAL_UNARMED_IDLE_SECS: '30', // ≪ the 60s age below, ≫ quiet 20s
+      }
+      const cfg = loadLifecycleConfig(env)
+      const identity = 'claude-eu'
+      const sock = join(root, 'socks', 'tmux-iap-claude-eu.sock')
+      const alive = () => spawnSync('tmux', ['-S', sock, 'has-session', '-t', identity]).status === 0
+      try {
+        mkdirSync(join(root, 'socks'), { recursive: true })
+        spawnSync('tmux', ['-S', sock, 'new-session', '-d', '-s', identity, 'sleep', '300'])
+        expect(alive()).toBe(true)
+        mkdirSync(cfg.stateDir, { recursive: true })
+        writeFileSync(
+          join(cfg.stateDir, `${identity}.session`),
+          JSON.stringify({ identity, runtime: 'claude', personality: 'eu', cwd, wokeAt: Date.now() - 60_000 }),
+        )
+        // NOT armed (the worker ended silently) — past the unarmed bound → policy reap
+        const o = superviseTick(cfg, { env }).find(x => x.identity === identity)
+        expect(o?.action).toBe('reaped-ephemeral')
+        expect(o?.reason).toContain('unarmed idle')
+        expect(o?.personality).toBe('eu') // M3 drain fields present → queue feeds next
+        expect(alive()).toBe(false)
+        // policy death: no resume-eligibility, no crash-loop count
+        expect(hasIdleReaped(cfg, identity)).toBe(false)
+        expect(readDeaths(cfg, identity).length).toBe(0)
+        const logged = readFileSync(join(cfg.eventLogDir, 'lifecycle.log'), 'utf8')
+        expect(logged).toContain('outcome=ephemeral-unarmed-bound')
+        // a NON-ephemeral peer with the same age is untouched by this bound
+        // (its session lives on ITS OWN identity-derived socket — the tick keys
+        // sockets on runtime-personality, not on the test's prior sock)
+        const plainCwd = profileCwd(false, false)
+        const eupSock = join(root, 'socks', 'tmux-iap-claude-eup.sock')
+        try {
+          writeFileSync(
+            join(cfg.stateDir, `claude-eup.session`),
+            JSON.stringify({ identity: 'claude-eup', runtime: 'claude', personality: 'eup', cwd: plainCwd, wokeAt: Date.now() - 60_000 }),
+          )
+          spawnSync('tmux', ['-S', eupSock, 'new-session', '-d', '-s', 'claude-eup', 'sleep', '300'])
+          expect(superviseTick(cfg, { env }).find(x => x.identity === 'claude-eup')?.action).toBe('alive')
+        } finally {
+          spawnSync('tmux', ['-S', eupSock, 'kill-server'], { stdio: 'ignore' })
+          rmSync(plainCwd, { recursive: true, force: true })
+        }
+      } finally {
+        spawnSync('tmux', ['-S', sock, 'kill-server'], { stdio: 'ignore' })
+        rmSync(root, { recursive: true, force: true })
+        rmSync(laDir, { recursive: true, force: true })
+        rmSync(cwd, { recursive: true, force: true })
+      }
+    },
+    30000,
+  )
 })
 
 // ─────────────────────────────────────────────────────────────────────────────