@agfpd/iapeer 0.2.6 → 0.2.7

package/package.json

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

package/src/launch/index.ts

@@ -107,6 +107,72 @@ function ready(identity: string): LaunchResult {
   return { status: 'READY', identity, process_address: identity }
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Exit-cause observability — capture WHY a session's process died, AT THE MOMENT
+// of death. The daemon's 60 s supervise tick only learns of a death post-factum
+// (reaped-gone), by which time the exit code/signal — and often the whole tmux
+// server — is gone (the boris-fresh-style blind spot one level deeper than the
+// supervise log). A tmux `pane-died` hook closes it: it fires the instant the
+// pane's leader process exits (with `remain-on-exit on` retaining the dead pane so
+// `#{pane_dead_status}`/`#{pane_dead_signal}` are populated), logs one logfmt line,
+// then kill-sessions the now-dead pane so the daemon's `has-session` death
+// detection (and the always-on KeepAlive block-watch) stay intact.
+//
+// Scope — verified live on tmux 3.6a (3 death modes + the daemon-reap path):
+//   • graceful exit  → `dead_status=<code> dead_signal=`   (code, no signal)
+//   • SIGTERM/SIGKILL/crash to the PROCESS → `dead_status= dead_signal=<name>`
+//   • daemon-initiated `kill-session` (idle-reap / self-TTL / stop) does NOT fire
+//     pane-died → NO line here (those are already in lifecycle.log — no double-log).
+// IRREDUCIBLE GAP: SIGKILL to the tmux SERVER process itself runs no hook (the
+//   event loop is gone); only the daemon's post-factum reaped-gone catches that.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** The exit-cause log file inside `exitLogDir` (sibling to lifecycle.log). */
+export function exitLogPath(exitLogDir: string): string {
+  return `${exitLogDir}/exits.log`
+}
+
+/**
+ * Build the tmux `pane-died` hook command string (the value of `set-hook -t <id>
+ * pane-died <value>`). On the pane leader's death it appends ONE logfmt line —
+ *   `ts=<ISO> ev=session-exit identity=<id> dead_status=#{…} dead_signal=#{…}`
+ * — to `exitLogFile`, then runs a tmux-NATIVE `kill-session` (no shell `tmux`, so
+ * it needs no PATH — launchd gives always-on servers a minimal one). Pure (no I/O)
+ * so the exact string is unit-testable. Quoting: the `run-shell` arg is wrapped in
+ * tmux SINGLE quotes (literal at the tmux layer, still `#{}`-format-expanded) with
+ * sh DOUBLE quotes inside — the two levels never collide; `\n`/`$(…)` pass through
+ * tmux untouched to sh. `identity`/`exitLogFile` are assumed free of single quotes
+ * (runtime-personality identities and the ~/.iapeer/logs path always are). */
+export function exitCauseHook(identity: string, exitLogFile: string): string {
+  const line =
+    `ts=%s ev=session-exit identity=${identity} ` +
+    `dead_status=#{pane_dead_status} dead_signal=#{pane_dead_signal}\\n`
+  const log =
+    `printf "${line}" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "${exitLogFile}"`
+  return `run-shell '${log}' ; kill-session -t "${identity}"`
+}
+
+/** Install the exit-cause observability on a freshly-created session: ensure the
+ *  exit-log dir exists, turn `remain-on-exit` on (so pane-died can read the dead
+ *  pane's status/signal) and register the hook. Best-effort — a tmux/FS hiccup
+ *  here must never fail the launch (observability is never load-bearing). No-op
+ *  when `exitLogDir` is falsy (a partial/test cfg): `remain-on-exit` stays OFF so
+ *  behavior is byte-identical to before (and no dead pane can linger un-reaped). */
+function installExitHook(sock: string, identity: string, exitLogDir: string | undefined): void {
+  if (!exitLogDir) return
+  try {
+    mkdirSync(exitLogDir, { recursive: true, mode: 0o700 })
+    // remain-on-exit must be ON before the process can die, else pane-died won't
+    // retain the dead pane and the status/signal are lost. Set it (and the hook)
+    // immediately after new-session — the only un-coverable window is the few ms
+    // before this runs, irrelevant for a runtime that takes seconds to initialize.
+    tmux(sock, 'set-option', '-t', identity, 'remain-on-exit', 'on')
+    tmux(sock, 'set-hook', '-t', identity, 'pane-died', exitCauseHook(identity, exitLogPath(exitLogDir)))
+  } catch {
+    /* observability is best-effort — never block a wake on a hook-install hiccup */
+  }
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // launch — bring up ONE session (runtime-agnostic via the adapter)
 // ─────────────────────────────────────────────────────────────────────────────
@@ -178,6 +244,14 @@ export const launch: LaunchFn = async (
     return fail(identity, `tmux new-session failed: ${(start.stderr ?? '').trim() || 'exit ' + start.status}`)
   }
 
+  // (2.5) Exit-cause observability: a `pane-died` hook that records WHY this
+  //       session's process dies (status/signal) at the moment of death into
+  //       <exitLogDir>/exits.log, then kill-sessions the dead pane (so the
+  //       daemon's has-session death detection + always-on KeepAlive stay intact).
+  //       Installed ASAP — before pipe-pane — so even a runtime that dies during
+  //       boot leaves a cause. No-op without cfg.exitLogDir (remain-on-exit off).
+  installExitHook(sock, identity, cfg.exitLogDir)
+
   // (3) pipe-pane the session output to the per-identity log.
   mkdirSync(cfg.logDir, { recursive: true, mode: 0o700 })
   const paneLog = `${cfg.logDir}/${identity}.log`

package/src/launch/launch.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'bun:test'
-import { getAdapter, launch } from './index.ts'
+import { exitCauseHook, exitLogPath, getAdapter, launch } from './index.ts'
 import { claudeAdapter } from './adapters/claude.ts'
 import { codexAdapter } from './adapters/codex.ts'
 import { telegramAdapter } from './adapters/telegram.ts'
@@ -187,6 +187,39 @@ describe('claudeAdapter', () => {
   })
 })
 
+// ─── exit-cause observability: the pane-died hook builder (pure string) ──────
+describe('exitCauseHook (exit-cause observability)', () => {
+  const hook = exitCauseHook('claude-iapeer', '/r/logs/iapeer/exits.log')
+
+  test('exitLogPath → exits.log sibling to lifecycle.log', () => {
+    expect(exitLogPath('/r/logs/iapeer')).toBe('/r/logs/iapeer/exits.log')
+  })
+  test('reads pane_dead_status AND pane_dead_signal (both death classes)', () => {
+    // graceful exit populates #{pane_dead_status}; a signal populates #{pane_dead_signal}.
+    expect(hook).toContain('dead_status=#{pane_dead_status}')
+    expect(hook).toContain('dead_signal=#{pane_dead_signal}')
+  })
+  test('one logfmt line: ts + ev=session-exit + identity, appended to the exit log', () => {
+    expect(hook).toContain('ev=session-exit')
+    expect(hook).toContain('identity=claude-iapeer')
+    expect(hook).toContain('ts=%s')
+    expect(hook).toContain('>> "/r/logs/iapeer/exits.log"')
+    expect(hook).toContain('\\n') // literal backslash-n for sh printf, not a real newline
+  })
+  test('logs BEFORE it reaps: run-shell (sync, no -b) then tmux-native kill-session', () => {
+    // run-shell must NOT be backgrounded (-b) — the printf has to finish before the
+    // kill tears the server down, else the line is lost to the race (verified live).
+    expect(hook).not.toContain('run-shell -b')
+    expect(hook.indexOf('run-shell')).toBeLessThan(hook.indexOf('kill-session'))
+    // tmux-NATIVE kill-session (no shell `tmux`) → needs no PATH (launchd minimal env).
+    expect(hook).toContain('kill-session -t "claude-iapeer"')
+  })
+  test('quoting: single-quoted run-shell arg (tmux layer) wrapping double-quoted sh', () => {
+    expect(hook).toMatch(/run-shell '.*'/)
+    expect(hook).not.toContain("''") // no empty/again-collapsed single-quote pair
+  })
+})
+
 // ─── Ф-A #2: deliveryMarkers OWNED by the adapter (07.06 refactor) ───────────
 describe('deliveryMarkers (adapter-owned, was transport PROMPT_GLYPHS)', () => {
   test('claude: ❯ glyph + paste patterns', () => {

package/src/launch/launchdRun.ts

@@ -20,7 +20,7 @@ import { spawnSync } from 'child_process'
 import { join } from 'path'
 import { INFRA_RUNTIME_BIN_ENV, isInfraRuntime, resolveSockDir } from '../core/constants.ts'
 import { buildProcessAddress, buildSocketPath } from '../core/socket.ts'
-import { peerLogsDir } from '../storage/index.ts'
+import { peerLogsDir, pluginLogsDir } from '../storage/index.ts'
 import { readPeerProfile } from '../identity/index.ts'
 import { getAdapter, launch } from './index.ts'
 import type { LaunchConfig, LaunchSpec } from './types.ts'
@@ -102,6 +102,12 @@ export async function runAlwaysOn(personality: string, runtime: string, cwd: str
     // GLOBAL infra logs (Фаза §8): ~/.iapeer/logs/<personality>/ — match the plist's
     // stdout/stderr dir (installAlwaysOnPlist), not per-peer <cwd>/.iapeer/logs/.
     logDir: peerLogsDir(personality, { env }),
+    // Exit-cause log → the shared ~/.iapeer/logs/iapeer (== lifecycle eventLogDir),
+    // so an infra peer's self-death is recorded next to lifecycle.log too. The hook
+    // also reaps the dead pane: without it remain-on-exit would linger a dead pane,
+    // keeping sessionAlive() true so runAlwaysOn block-watches forever and KeepAlive
+    // never respawns — the hook prevents that regression as well as logging the cause.
+    exitLogDir: pluginLogsDir('iapeer', { env }),
     env,
     alwaysOn: true,
   }

package/src/launch/types.ts

@@ -266,6 +266,17 @@ export interface LaunchConfig extends LaunchAdapterConfig {
   maxAgeSecs: number
   /** Log dir for pipe-pane output. */
   logDir: string
+  /**
+   * Durable EXIT-CAUSE log dir (~/.iapeer/logs/iapeer — next to lifecycle.log,
+   * where the investigator looks). When set, launch installs a tmux `pane-died`
+   * hook that records WHY the session's process died (exit status / signal) AT THE
+   * MOMENT of death, into `<exitLogDir>/exits.log` — the blind spot the daemon's
+   * 60 s supervise tick (reaped-gone) can only see post-factum, after the exit code
+   * is already lost. Routed through cfg (NOT re-resolved from env) so it is isolated
+   * by the same sandbox as the rest of launch; a FALSY dir → no hook installed and
+   * `remain-on-exit` stays off (original behavior — a partial/test cfg never writes
+   * and never lingers a dead pane). See exitCauseHook in index.ts. */
+  exitLogDir?: string
   env?: NodeJS.ProcessEnv
   /**
    * Always-on bring-up (infra runtimes held by launchd KeepAlive): SKIP the

package/src/lifecycle/index.ts

@@ -805,6 +805,10 @@ export async function wakeOrSpawn(args: WakeArgs, deps: WakeDeps = {}): Promise<
       readyGateSecs: cfg.readyGateSecs,
       maxAgeSecs: cfg.maxAgeSecs,
       logDir: cfg.logDir,
+      // Exit-cause log → next to lifecycle.log (~/.iapeer/logs/iapeer), where the
+      // investigator already looks: a self-death now leaves `exits.log` with the
+      // status/signal the daemon's post-factum reaped-gone could never recover.
+      exitLogDir: cfg.eventLogDir,
       env,
     }
     // C2 — initial_prompt (launch-seed): on a FRESH wake, seed the first turn with