@agfpd/iapeer 0.2.5 → 0.2.7

package/package.json

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

package/src/launch/adapters/claude.ts

@@ -30,15 +30,17 @@ import type { ControlCommand, ControlPlan, LaunchAdapterConfig, LaunchSpec, Runt
 // ─────────────────────────────────────────────────────────────────────────────
 
 /**
- * The known claude startup dialogs whose default-highlighted option is the
- * proceed path, so a single Enter clears each:
+ * Markers that a claude startup dialog / picker is on screen — used by isInputReady
+ * to GATE delivery (a dialog up ⇒ not ready). The KEYS that clear each live in
+ * bootDialogKeys (NOT uniformly Enter — the resume picker must be NAVIGATED, see there):
  *   - 'trust this folder'                      — first-run folder-trust modal.
  *   - 'Allow external CLAUDE.md file imports?' — external-import consent.
  *   - 'I am using this for local development'   — dev-channels accept
  *     (claude-start.sh:337), shown when PEER_START_ARGS carries
  *     --dangerously-load-development-channels.
- *   - 'Resume from summary' / 'Resuming the full session' — the --resume picker.
- * Same set, same order as lifecycle.claudeBootDialog (index.ts:281-289).
+ *   - 'Resume from summary'      — the resume compact-picker (default cursor =
+ *     "summary (recommended)", which compacts; bootDialogKeys picks "full" instead).
+ *   - 'Resuming the full session' — the post-select load state (still not ready).
  */
 const CLAUDE_BOOT_DIALOG_MARKERS = [
   'trust this folder',
@@ -104,7 +106,7 @@ export const claudeAdapter: RuntimeAdapter = {
 
   /**
    * argv = claudeBin + headless flags + (system-prompt-file when set) +
-   * (--resume <ref> when resumeRef set) + extraArgs.
+   * (--continue when resuming) + extraArgs.
    *
    *   - '--dangerously-skip-permissions'  claude-start.sh:318, spawner.ts:776 —
    *     headless peer has no interactive owner to grant per-tool permission.
@@ -117,8 +119,15 @@ export const claudeAdapter: RuntimeAdapter = {
    *     ONLY when set (a tui runtime that usesDoctrine composes one). Swaps the
    *     CC coding baseline for the merged peer doctrine; plugin/MCP/CLAUDE.md
    *     layers stay intact (claude-start.sh:293-303).
-   *   - '--resume', spec.resumeRef  spawner.ts:779-781 — ONLY when the caller
-   *     pre-resolved a uuid (resolveResume); never a silent fresh fallback.
+   *   - '--continue' when spec.resume — continue the cwd's MOST-RECENT session
+   *     (one session-lineage per peer cwd, so most-recent == the warm peer's
+   *     session, == the newest transcript resolveResume validated). NOT
+   *     '--resume <uuid>': in claude 2.1.169 `--resume <arg>` treats arg as a
+   *     SEARCH QUERY (opens a session-list picker), not a session-id — so a bare
+   *     uuid no longer resumes directly. `--continue` resumes the last session
+   *     with no session-list step. The summary-vs-full compact picker still
+   *     appears (handled in bootDialogKeys: pick "full", never the recommended
+   *     summary). resolveResume still gates resume-vs-fresh upstream (fail-loud).
    *   - ...extraArgs  PEER_START_ARGS passthrough (LaunchSpec.extraArgs).
    * NO currency — no marketplace/install/update on this path.
    */
@@ -129,19 +138,37 @@ export const claudeAdapter: RuntimeAdapter = {
       '--disallowedTools',
       'AskUserQuestion',
       ...(spec.systemPromptFile ? ['--system-prompt-file', spec.systemPromptFile] : []),
-      ...(spec.resumeRef ? ['--resume', spec.resumeRef] : []),
+      ...(spec.resume ? ['--continue'] : []),
       ...(spec.extraArgs ?? []),
     ]
   },
 
   /**
-   * A visible startup dialog → ['Enter'] to clear it (its default-highlighted
-   * option is the proceed path), else null. Same marker set as
-   * lifecycle.claudeBootDialog; claude-start.sh:341 (dev-channels) and the
-   * folder-trust/import/resume modals all accept a bare Enter.
+   * Map a visible startup dialog to the keys that clear it correctly:
+   *
+   *   - RESUME COMPACT-PICKER ('Resume from summary …') → ['Down','Enter'].
+   *     This menu's cursor DEFAULTS to "1. Resume from summary (recommended)",
+   *     and selecting it COMPACTS the session (claude implements that choice as an
+   *     internal /compact). A bare Enter would therefore silently compact a warm
+   *     peer on EVERY idle-reap→resume — losing its full context. Move the cursor
+   *     DOWN one to "2. Resume full session as-is" and confirm, keeping full
+   *     context. (Verified against the live picker: ❯ on option 1, ↑↓ navigation,
+   *     "Enter to confirm".)
+   *   - OTHER MODALS (folder-trust / external-import / dev-channels) → ['Enter']:
+   *     their default-highlighted option IS the proceed path, so a bare Enter clears
+   *     each (claude-start.sh:341).
+   *   - anything else (incl. the post-select "Resuming…" load state) → null (wait).
    */
   bootDialogKeys(pane: string): string[] | null {
-    return anyBootDialog(pane) ? ['Enter'] : null
+    if (pane.includes('Resume from summary')) return ['Down', 'Enter']
+    if (
+      pane.includes('trust this folder') ||
+      pane.includes('Allow external CLAUDE.md file imports?') ||
+      pane.includes('I am using this for local development')
+    ) {
+      return ['Enter']
+    }
+    return null
   },
 
   /**

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'
@@ -120,9 +120,12 @@ describe('claudeAdapter', () => {
     ])
   })
 
-  test('buildArgv with system-prompt-file + resume + extras (exact flags/order)', () => {
+  test('buildArgv with system-prompt-file + resume + extras → --continue (NOT --resume <uuid>)', () => {
+    // resume uses `--continue` (continue the cwd's most-recent session), NOT
+    // `--resume <uuid>` — in claude 2.1.169 `--resume <arg>` is a search query, not a
+    // session-id. resumeRef is set by the daemon but no longer consumed by the launch.
     const argv = claudeAdapter.buildArgv(
-      spec({ systemPromptFile: '/tmp/sp.md', resumeRef: 'uuid-1', extraArgs: ['--foo'] }),
+      spec({ systemPromptFile: '/tmp/sp.md', resume: true, resumeRef: 'uuid-1', extraArgs: ['--foo'] }),
       cfg,
     )
     expect(argv).toEqual([
@@ -132,10 +135,17 @@ describe('claudeAdapter', () => {
       'AskUserQuestion',
       '--system-prompt-file',
       '/tmp/sp.md',
-      '--resume',
-      'uuid-1',
+      '--continue',
       '--foo',
     ])
+    expect(argv).not.toContain('--resume')
+    expect(argv).not.toContain('uuid-1')
+  })
+
+  test('buildArgv: resume FALSE (fresh) → no --continue / --resume', () => {
+    const argv = claudeAdapter.buildArgv(spec({ resume: false, resumeRef: 'uuid-1' }), cfg)
+    expect(argv).not.toContain('--continue')
+    expect(argv).not.toContain('--resume')
   })
 
   test('buildArgv carries NO currency (no marketplace/plugin tokens)', () => {
@@ -153,12 +163,23 @@ describe('claudeAdapter', () => {
     expect(claudeAdapter.isInputReady('❯ just a prompt')).toBe(false)
   })
 
-  test('bootDialogKeys: a dialog → [Enter], clean pane → null', () => {
+  test('bootDialogKeys: proceed-modals → [Enter]; clean/load pane → null', () => {
     expect(claudeAdapter.bootDialogKeys('I am using this for local development')).toEqual(['Enter'])
-    expect(claudeAdapter.bootDialogKeys('Resuming the full session')).toEqual(['Enter'])
+    expect(claudeAdapter.bootDialogKeys('trust this folder')).toEqual(['Enter'])
+    expect(claudeAdapter.bootDialogKeys('Allow external CLAUDE.md file imports?')).toEqual(['Enter'])
+    // the post-select "Resuming…" load state is NOT a modal to Enter — just wait.
+    expect(claudeAdapter.bootDialogKeys('Resuming the full session')).toBeNull()
     expect(claudeAdapter.bootDialogKeys('❯ ready')).toBeNull()
   })
 
+  test('bootDialogKeys: resume compact-picker → [Down, Enter] (pick "full", NOT the recommended summary)', () => {
+    // Default cursor is "1. Resume from summary (recommended)"; bare Enter would compact.
+    // Move DOWN to "2. Resume full session as-is" and confirm → full context preserved.
+    expect(
+      claudeAdapter.bootDialogKeys('❯ 1. Resume from summary (recommended)\n  2. Resume full session as-is'),
+    ).toEqual(['Down', 'Enter'])
+  })
+
   test('permissionDialog: proceed prompt → active, [Enter]', () => {
     expect(claudeAdapter.permissionDialogActive('Do you want to proceed?')).toBe(true)
     expect(claudeAdapter.permissionDialogActive('nothing')).toBe(false)
@@ -166,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