@agfpd/iapeer 0.2.26 → 0.2.27

package/package.json

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

package/src/launch/canary.test.ts

@@ -10,7 +10,9 @@ import { tmpdir } from 'os'
 import { join } from 'path'
 import {
   canaryChannel,
+  canaryProcessPattern,
   canaryScript,
+  dismissCanary,
   ensureServerCanary,
   exitLogPath,
   serverDeathsDir,
@@ -53,7 +55,7 @@ describe('canary script (pure)', () => {
     expect(exitLogPath('/r/logs/iapeer')).toBe('/r/logs/iapeer/exits.log')
   })
 
-  test('script carries the protocol: wait-for channel, silent-exit guards, record line, forensics', () => {
+  test('script carries the v2 protocol: wait-for channel, deliberate-silence guards, liveness probe, record line, forensics', () => {
     const s = canaryScript({
       identity: 'claude-bob',
       sock: '/tmp/x.sock',
@@ -62,8 +64,15 @@ describe('canary script (pure)', () => {
       forensicsDir: '/r/logs/iapeer/server-deaths',
     })
     expect(s).toContain(`wait-for 'iap-canary-claude-bob'`) // the blocking client
-    expect(s).toContain(`trap 'exit 0' HUP INT TERM`) // signaled canary = silent
-    expect(s).toContain(`[ "$rc" -eq 0 ] || [ "$rc" -ge 128 ]`) // clean/signaled guards
+    expect(s).toContain(`trap 'exit 0' HUP INT TERM`) // dismissed sh = silent (the ONLY deliberate silencer)
+    // v2: NO exit code is trusted as deliberate (a TERMed client returns rc=0 —
+    // proven live); the SERVER's liveness decides, after a dismissal grace sleep.
+    expect(s).not.toContain(`[ "$rc" -eq 0 ] || [ "$rc" -ge 128 ]; then exit 0`) // the v1 hole
+    expect(s).toContain('sleep 2') // dismissal grace window
+    expect(s).toContain(`has-session 2>/dev/null; then exit 0`) // server alive → nothing to record
+    expect(s).toContain('cause=server-vanished') // connection drop (SIGKILL/OOM class)
+    expect(s).toContain('cause=signaled-server-gone') // rc=0: channel/client-TERM, server died
+    expect(s).toContain('cause=client-killed-server-gone') // rc≥128: client took a hard kill
     expect(s).toContain('ev=server-exit identity=claude-bob') // the exits.log record
     expect(s).toContain(`>> '/r/logs/iapeer/exits.log'`)
     expect(s).toContain('/r/logs/iapeer/server-deaths/claude-bob') // forensics file
@@ -74,6 +83,19 @@ describe('canary script (pure)', () => {
   test('ensureServerCanary without exitLogDir → skipped (observability off)', () => {
     expect(ensureServerCanary({ identity: 'claude-none', sock: '/tmp/none.sock' })).toBe('skipped')
   })
+
+  test('canaryProcessPattern is identity-anchored (no prefix bleed) and matches both canary processes', () => {
+    const p = canaryProcessPattern('claude-iap')
+    expect(p).toBe('iap-canary-claude-iap([^a-z0-9-]|$)')
+    const re = new RegExp(p)
+    expect(re.test(`/opt/homebrew/bin/tmux -S /tmp/x.sock wait-for iap-canary-claude-iap`)).toBe(true) // client argv
+    expect(re.test(`/bin/sh -c ... wait-for 'iap-canary-claude-iap'\n...`)).toBe(true) // sh -c script (quoted channel)
+    expect(re.test(`tmux wait-for iap-canary-claude-iap-memory`)).toBe(false) // prefix identity must NOT match
+  })
+
+  test('dismissCanary is a harmless no-op when no canary runs', () => {
+    expect(() => dismissCanary('claude-nobody-here')).not.toThrow()
+  })
 })
 
 describe.if(tmuxAvailable)('canary live (sandbox tmux servers)', () => {
@@ -90,11 +112,22 @@ describe.if(tmuxAvailable)('canary live (sandbox tmux servers)', () => {
     return { sock, logDir: join(dir, `logs-${identity}`) }
   }
 
+  const allIds = [
+    'claude-canadirty',
+    'claude-canaclean',
+    'claude-canakill',
+    'notifier-canatear',
+    'claude-canasweep',
+    'claude-canaclient',
+  ]
+
   afterAll(() => {
     for (const sock of socks) {
-      // teardown is DELIBERATE → signal each canary before killing its server
-      for (const id of ['claude-canadirty', 'claude-canaclean', 'claude-canakill', 'notifier-canatear']) {
+      // teardown is DELIBERATE → silence each canary (signal + dismiss) before
+      // killing its server — the v2 contract for every deliberate path.
+      for (const id of allIds) {
         signalCanaryClean(sock, id)
+        dismissCanary(id)
       }
       spawnSync('tmux', ['-S', sock, 'kill-server'], { stdio: 'ignore' })
     }
@@ -197,4 +230,59 @@ describe.if(tmuxAvailable)('canary live (sandbox tmux servers)', () => {
     },
     20000,
   )
+
+  test(
+    'death-#4 shape: external killer sweeps server AND canary client → ev=server-exit cause=client-signaled',
+    async () => {
+      const identity = 'claude-canasweep'
+      const { sock, logDir } = bringUp(identity)
+      const pid = serverPid(sock)
+      expect(ensureServerCanary({ identity, sock, exitLogDir: logDir })).toBe('spawned')
+      expect(await waitFor(() => canaryRunning(identity), 3000)).toBe(true)
+      await sleep(500)
+
+      // The pre-clean-shaped external killer: one pattern takes the server AND
+      // the canary CLIENT (both argv contain `tmux -S <sock> `), the sh recorder
+      // survives. The TERMed client returns rc=0 (proven live) — v1 read that as
+      // a clean channel signal and stayed silent; exactly how deaths #4–#6
+      // (10.06) left zero records. v2 probes the server instead: dead → record.
+      spawnSync('pkill', ['-f', `tmux -S ${sock} `], { stdio: 'ignore' })
+      const log = exitLogPath(logDir)
+      expect(
+        await waitFor(() => existsSync(log) && readFileSync(log, 'utf8').includes('ev=server-exit'), 10000),
+      ).toBe(true)
+      const line = readFileSync(log, 'utf8')
+      expect(line).toContain(`ev=server-exit identity=${identity}`)
+      expect(line).toContain('cause=signaled-server-gone') // rc=0 shape, server found dead
+      expect(line).toContain(`server_pid=${pid}`)
+      expect(readdirSync(serverDeathsDir(logDir)).length).toBe(1) // forensics captured
+    },
+    20000,
+  )
+
+  test(
+    'canary client killed while server lives → silent (no false record), canary gone for the retrofit to re-arm',
+    async () => {
+      const identity = 'claude-canaclient'
+      const { sock, logDir } = bringUp(identity)
+      expect(ensureServerCanary({ identity, sock, exitLogDir: logDir })).toBe('spawned')
+      expect(await waitFor(() => canaryRunning(identity), 3000)).toBe(true)
+      await sleep(500)
+
+      // TERM the CLIENT only (argv ends with the bare channel — the sh's quoted
+      // form does not match this $-anchored pattern), server stays up.
+      spawnSync('pkill', ['-f', `wait-for ${canaryChannel(identity)}$`], { stdio: 'ignore' })
+      // the sh probes (≈2 s), finds the server ALIVE → exits silently
+      expect(await waitFor(() => !canaryRunning(identity), 6000)).toBe(true)
+      await sleep(300)
+      expect(
+        existsSync(exitLogPath(logDir)) && readFileSync(exitLogPath(logDir), 'utf8').includes('ev=server-exit'),
+      ).toBe(false) // no false server-death while the server lives
+      // server must still be alive — and ensure re-arms a fresh canary (the
+      // retrofit path; in prod the supervise tick does this and logs it)
+      expect(spawnSync('tmux', ['-S', sock, 'has-session', '-t', identity], { stdio: 'ignore' }).status).toBe(0)
+      expect(ensureServerCanary({ identity, sock, exitLogDir: logDir })).toBe('spawned')
+    },
+    20000,
+  )
 })

package/src/launch/canary.ts

@@ -8,17 +8,32 @@
 // Mechanism: one tiny detached `sh` per LIVE tmux server, holding a blocking
 // client `tmux -S <sock> wait-for iap-canary-<identity>` — a process OUTSIDE the
 // dying server, connected via its socket, so the server's death (any cause,
-// including SIGKILL) is observed the moment the connection drops. Protocol:
-//   • clean teardown (idle-reap / stop / pre-clean / killServerIfEmpty) SIGNALS
-//     the channel first (`wait-for -S`) → the canary exits 0, silently;
-//   • the canary itself signaled (TERM/HUP/INT, e.g. launch pre-clean pkill) →
-//     rc ≥ 128 / trap → exit silently (someone manages it deliberately);
-//   • anything else (wait-for returns an error = the server vanished under us)
-//     → ONE logfmt line `ev=server-exit` into exits.log (the per-peer death-cause
-//     home, next to pane-died's `ev=session-exit`) + a forensics snapshot file
-//     (vm_stat / swap / top-RSS ps / fresh DiagnosticReports) captured WITHIN
-//     SECONDS of the death — the evidence the 60 s supervise tick can never
+// including SIGKILL) is observed the moment the connection drops. Protocol (v2 —
+// death #4 10.06 15:42Z proved v1's exit-code trust wrong twice over: the killer
+// took the SERVER and the canary CLIENT together, AND a TERMed tmux client
+// returns rc=0 — indistinguishable from a clean channel signal — so the rc-based
+// `0 || ≥128 → silent` guard silenced a real death):
+//   • DELIBERATE silence is an explicit act, never an exit-code inference:
+//     every deliberate teardown (idle-reap / stop / pre-clean / pane-died hook /
+//     bootout teardown) signals the channel (`wait-for -S`) AND dismisses the
+//     sh recorder (`dismissCanary` → TERM → trap → silent exit). POSIX trap
+//     semantics make this race-free: the trap runs before any recording.
+//   • When wait-for returns — ANY code — the script sleeps 2 s (a concurrent
+//     dismissal TERM wins here), then probes SERVER LIVENESS: alive → exit
+//     silently (a lost canary is re-armed and logged by the supervise retrofit
+//     within a tick); dead with nobody having dismissed us → the death is real
+//     and unclaimed → ONE logfmt line `ev=server-exit` into exits.log (the
+//     per-peer death-cause home, next to pane-died's `ev=session-exit`) + a
+//     forensics snapshot (vm_stat / swap / top-RSS ps / fresh DiagnosticReports)
+//     captured within seconds — the evidence the 60 s supervise tick can never
 //     recover ("системных следов ноль" was the recurring investigation outcome).
+//     The raw wait_rc still ATTRIBUTES the death (cause=server-vanished /
+//     signaled-server-gone / client-killed-server-gone).
+// Residual blind spot (structural): a killer that SIGKILLs the sh recorder
+// itself leaves no in-process way to record. With v2 the ABSENCE of a record on
+// a server-dead reap narrows the diagnosis to exactly that shape; the canary
+// ensure-state lines in lifecycle.log (origin=launch/retrofit) evidence the
+// churn post-hoc.
 //
 // The canary is pure observability: it never wakes, reaps, restarts or otherwise
 // manages anything (H4-compatible by construction), it fires at most once, and
@@ -69,24 +84,45 @@ export function canaryScript(o: CanaryScriptOptions): string {
   return [
     // Server PID captured while alive — the postmortem grep key for system logs.
     `SPID="$('${o.tmuxBin}' -S '${o.sock}' display-message -p '#{pid}' 2>/dev/null)"`,
-    // A signal to the CANARY is deliberate management (pre-clean pkill) → silent.
+    // A signal to the SH WRAPPER is deliberate dismissal (dismissCanary) or host
+    // shutdown → silent. POSIX: the trap runs after the foreground command
+    // completes — so a TERM delivered during wait-for/sleep always exits us
+    // BEFORE any recording below (the race-free deliberate-silence guarantee).
     `trap 'exit 0' HUP INT TERM`,
     `'${o.tmuxBin}' -S '${o.sock}' wait-for '${ch}'`,
     `rc=$?`,
-    // rc=0 → clean-teardown signal; rc≥128 → the tmux client itself was signaled.
-    `if [ "$rc" -eq 0 ] || [ "$rc" -ge 128 ]; then exit 0; fi`,
-    // The server vanished under us — record, within seconds of the death.
+    // NO wait-for exit code is trusted as "deliberate" by itself — PROVEN live
+    // (death-#4 postmortem): a TERM to the tmux CLIENT returns rc=0, identical
+    // to a clean channel signal, so an external killer sweeping server+client
+    // rides the clean-looking code straight past any rc-based guard (v1's
+    // `rc=0 || rc>=128 → silent` was exactly that hole). v2 contract instead:
+    //   • deliberate teardowns DISMISS this sh (TERM → trap above) — the sleep
+    //     below gives a concurrently-delivered dismissal time to win;
+    //   • then the SERVER's liveness, not the exit code, decides: alive →
+    //     nothing to record (a lost canary is re-armed and logged by the
+    //     supervise retrofit within a tick); dead and nobody dismissed us →
+    //     the death is real and unclaimed → record it.
+    `sleep 2`,
+    `if '${o.tmuxBin}' -S '${o.sock}' has-session 2>/dev/null; then exit 0; fi`,
+    // The exit code still ATTRIBUTES the recorded death (raw wait_rc is kept):
+    //   rc=0   → signaled-server-gone   (channel signal or client-TERM, server died)
+    //   rc≥128 → client-killed-server-gone (client took a non-TERM kill)
+    //   else   → server-vanished        (connection drop — SIGKILL/OOM class)
+    `cause=server-vanished`,
+    `if [ "$rc" -eq 0 ]; then cause=signaled-server-gone; fi`,
+    `if [ "$rc" -ge 128 ]; then cause=client-killed-server-gone; fi`,
+    // The server is gone under us — record, within seconds of the death.
     `ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"`,
     `f='${o.forensicsDir}/${o.identity}'-"$(date +%s)".txt`,
     `{`,
-    `  echo "server-death identity=${o.identity} ts=$ts server_pid=$SPID wait_rc=$rc"`,
+    `  echo "server-death identity=${o.identity} ts=$ts server_pid=$SPID wait_rc=$rc cause=$cause"`,
     `  echo '--- vm_stat'; vm_stat`,
     `  echo '--- swapusage'; sysctl -n vm.swapusage`,
     `  echo '--- ps-top-rss'; ps axo pid,ppid,rss,etime,command | sort -rn -k3 | head -25`,
     `  echo '--- diagnosticreports-user'; ls -t "$HOME/Library/Logs/DiagnosticReports" 2>/dev/null | head`,
     `  echo '--- diagnosticreports-system'; ls -t /Library/Logs/DiagnosticReports 2>/dev/null | head`,
     `} > "$f" 2>&1`,
-    `printf 'ts=%s ev=server-exit identity=${o.identity} server_pid=%s wait_rc=%s forensics=%s\\n' "$ts" "$SPID" "$rc" "$f" >> '${o.exitLogFile}'`,
+    `printf 'ts=%s ev=server-exit identity=${o.identity} server_pid=%s wait_rc=%s cause=%s forensics=%s\\n' "$ts" "$SPID" "$rc" "$cause" "$f" >> '${o.exitLogFile}'`,
   ].join('\n')
 }
 
@@ -150,3 +186,27 @@ export function signalCanaryClean(sock: string, identity: string): void {
     /* best-effort */
   }
 }
+
+/** The pgrep/pkill ERE matching BOTH canary processes of ONE identity — the sh
+ *  wrapper (its -c script quotes the channel: `…'iap-canary-<id>'…`) and the
+ *  tmux client (argv ends with the bare channel). Anchored so an identity can
+ *  never match another identity's prefix (claude-iapeer ≠ claude-iapeer-memory). */
+export function canaryProcessPattern(identity: string): string {
+  return `${canaryChannel(identity)}([^a-z0-9-]|$)`
+}
+
+/**
+ * Dismiss this identity's canary BEFORE a deliberate server teardown: TERM the
+ * sh wrapper (trap → silent exit, race-free — the trap always runs before the
+ * v2 recording branch) and the tmux client. The explicit counterpart of the
+ * channel signal: with v2 a signaled CLIENT alone is no longer read as
+ * deliberate, so every deliberate path must dismiss the RECORDER (the sh).
+ * Best-effort: no canary running → harmless no-op (pkill exits 1).
+ */
+export function dismissCanary(identity: string): void {
+  try {
+    spawnSync('pkill', ['-f', canaryProcessPattern(identity)], { stdio: 'ignore' })
+  } catch {
+    /* best-effort */
+  }
+}

package/src/launch/index.ts

@@ -19,7 +19,8 @@ import { dirname } from 'path'
 import { spawnSync } from 'child_process'
 import { CODEX_BEARER_ENV_VAR, CODEX_DUMMY_BEARER, type Runtime } from '../core/constants.ts'
 import { readLaunchEnv } from '../storage/index.ts'
-import { ensureServerCanary, exitLogPath, signalCanaryClean } from './canary.ts'
+import { canaryChannel, dismissCanary, ensureServerCanary, exitLogPath, signalCanaryClean } from './canary.ts'
+import { appendLifecycleEvent } from '../lifecycle/eventlog.ts'
 import { claudeAdapter } from './adapters/claude.ts'
 import { codexAdapter } from './adapters/codex.ts'
 import { telegramAdapter } from './adapters/telegram.ts'
@@ -155,7 +156,18 @@ export function exitCauseHook(identity: string, exitLogFile: string): string {
     `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}"`
+  // Silence the server-death canary BEFORE kill-session: with a single-session
+  // server the kill empties the server and exit-empty takes it down — without
+  // explicit silence the canary would append a second, muddier `ev=server-exit`
+  // record for a death this very hook just captured (the session-exit line is
+  // the richer, authoritative one: it has the exit code/signal). v2 contract:
+  // deliberate = channel signal (tmux-NATIVE wait-for -S) + DISMISS the sh
+  // recorder (abs-path /usr/bin/pkill — survives the minimal launchd PATH;
+  // `\$` keeps the regex anchor literal through the sh double-quote layer; the
+  // `[i]` class keeps the pattern from matching its OWN occurrence in this
+  // hook-sh's cmdline — the pgrep self-match classic).
+  const dismiss = `/usr/bin/pkill -f "[i]${canaryChannel(identity).slice(1)}([^a-z0-9-]|\\$)"`
+  return `run-shell '${log} ; ${dismiss}' ; wait-for -S "${canaryChannel(identity)}" ; kill-session -t "${identity}"`
 }
 
 /** Install the exit-cause observability on a freshly-created session: ensure the
@@ -212,11 +224,15 @@ export const launch: LaunchFn = async (
   mkdirSync(dirname(sock), { recursive: true })
 
   // (1) Pre-clean any stale tmux server on this socket, then launch detached.
-  //     Signal the server-death canary FIRST: this teardown is deliberate, the
-  //     canary must exit silently, not record a false server-death (the pkill
-  //     below also matches the canary's cmdline — by design, it sweeps a stale
-  //     canary along with the stale server; a signaled canary is already gone).
+  //     Silence the server-death canary EXPLICITLY first — this teardown is
+  //     deliberate: signal the channel (client exits 0) AND dismiss the sh
+  //     recorder (TERM → trap → silent; canary v2 no longer reads a signaled
+  //     client alone as deliberate — an external killer sweeping server+client
+  //     was exactly the death-#4 silence). Only then sweep the server processes
+  //     (the pkill also matches a leftover canary client — harmless, both
+  //     canary processes are already dismissed).
   signalCanaryClean(sock, identity)
+  dismissCanary(identity)
   spawnSync('pkill', ['-f', `tmux -S ${sock} `], { stdio: 'ignore' })
   tmux(sock, 'kill-server')
 
@@ -268,7 +284,14 @@ export const launch: LaunchFn = async (
   //       that records `ev=server-exit` + a forensics snapshot when the whole
   //       server dies dirty (SIGKILL/OOM class). Same gate as the exit hook;
   //       best-effort by construction (every failure → a state, never a throw).
-  ensureServerCanary({ identity, sock, exitLogDir: cfg.exitLogDir, env })
+  //       The ensure-state is logged (origin=launch) so the arming trail is
+  //       complete in lifecycle.log: 'spawned' is the newborn-server norm here,
+  //       'failed' a newborn server starting its life UNWATCHED (death-#4
+  //       postmortem hinged on this very question being unanswerable).
+  const canaryState = ensureServerCanary({ identity, sock, exitLogDir: cfg.exitLogDir, env })
+  if (canaryState !== 'skipped') {
+    appendLifecycleEvent(cfg.exitLogDir, { ev: 'canary', identity, state: canaryState, origin: 'launch' }, { env })
+  }
 
   // (3) pipe-pane the session output to the per-identity log.
   mkdirSync(cfg.logDir, { recursive: true, mode: 0o700 })

package/src/launch/launch.test.ts

@@ -227,6 +227,14 @@ describe('exitCauseHook (exit-cause observability)', () => {
     // tmux-NATIVE kill-session (no shell `tmux`) → needs no PATH (launchd minimal env).
     expect(hook).toContain('kill-session -t "claude-iapeer"')
   })
+  test('silences the server-death canary (native wait-for -S) BEFORE kill-session — no double record', () => {
+    // kill-session on a single-session server → exit-empty takes the server down;
+    // without the signal the canary would add a second `ev=server-exit` record for
+    // a death this hook just captured (session-exit carries the code/signal).
+    expect(hook).toContain('wait-for -S "iap-canary-claude-iapeer"')
+    expect(hook.indexOf('wait-for -S')).toBeLessThan(hook.indexOf('kill-session'))
+    expect(hook.indexOf('run-shell')).toBeLessThan(hook.indexOf('wait-for -S')) // log first
+  })
   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

package/src/launch/launchdRun.ts

@@ -23,7 +23,7 @@ import { buildProcessAddress, buildSocketPath } from '../core/socket.ts'
 import { peerLogsDir, pluginLogsDir } from '../storage/index.ts'
 import { readPeerProfile } from '../identity/index.ts'
 import { getAdapter, launch } from './index.ts'
-import { signalCanaryClean } from './canary.ts'
+import { dismissCanary, signalCanaryClean } from './canary.ts'
 import type { LaunchConfig, LaunchSpec } from './types.ts'
 
 /** Block-watch poll cadence — seconds, deliberately NOT a tight loop (the session
@@ -55,7 +55,10 @@ function sessionAlive(sock: string, identity: string): boolean {
  * both paths now converge on the same end state.
  */
 export function teardownAlwaysOnSession(sock: string, identity: string): void {
+  // Explicit canary silence (v2): channel signal (client exits 0) + dismiss the
+  // sh recorder — a signaled client alone is no longer read as deliberate.
   signalCanaryClean(sock, identity)
+  dismissCanary(identity)
   spawnSync('tmux', ['-S', sock, 'kill-session', '-t', identity], { stdio: 'ignore' })
   const ls = spawnSync('tmux', ['-S', sock, 'list-sessions', '-F', '#{session_name}'], { encoding: 'utf8' })
   if (!(ls.stdout ?? '').trim()) {

package/src/lifecycle/index.ts

@@ -46,7 +46,7 @@ import {
   type LaunchSpec,
 } from '../launch/index.ts'
 import { composeSystemPrompt, gatherPromptInput } from '../launch/composeSystemPrompt.ts'
-import { ensureServerCanary, signalCanaryClean } from '../launch/canary.ts'
+import { dismissCanary, ensureServerCanary, signalCanaryClean } from '../launch/canary.ts'
 import { appendLifecycleEvent, superviseLogVerbose } from './eventlog.ts'
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -1009,9 +1009,11 @@ export function killSession(sock: string, identity: string): void {
   tmux(sock, 'kill-session', '-t', identity)
   const sessions = tmux(sock, 'list-sessions', '-F', '#{session_name}').out
   if (!sessions.trim()) {
-    // Deliberate server teardown → signal the server-death canary FIRST so it
-    // exits silently instead of recording a false `ev=server-exit` (canary.ts).
+    // Deliberate server teardown → silence the canary EXPLICITLY first: signal
+    // the channel (client exits 0) AND dismiss the sh recorder (canary v2 no
+    // longer reads a signaled client alone as deliberate — see canary.ts).
     signalCanaryClean(sock, identity)
+    dismissCanary(identity)
     tmux(sock, 'kill-server')
     try {
       rmSync(sock, { force: true })
@@ -1190,7 +1192,15 @@ export function superviseTick(cfg: LifecycleConfig, deps: SuperviseDeps = {}): S
       // every ALIVE daemon-owned server — covers a fleet launched by older code
       // within one tick of a deploy, no session restarts. Idempotent (pgrep on
       // the per-identity wait-for channel), best-effort, pure observability.
-      ensureServerCanary({ identity: s.identity, sock, exitLogDir: cfg.eventLogDir, env })
+      // A non-'already' state IS a decision-grade event (not verbose-gated):
+      // post-0.2.22 every launch arms a canary, so a retrofit 'spawned' on an
+      // alive server means the previous canary VANISHED mid-watch (the death-#4
+      // blind spot was exactly this churn being invisible); 'failed' means the
+      // server is currently UNWATCHED. At most one line per loss, not per tick.
+      const canaryState = ensureServerCanary({ identity: s.identity, sock, exitLogDir: cfg.eventLogDir, env })
+      if (canaryState !== 'already') {
+        trace({ identity: s.identity, action: 'canary', state: canaryState, origin: 'retrofit' })
+      }
       out.push({ identity: s.identity, action: 'alive' })
       if (verbose) trace({ identity: s.identity, action: 'alive', age: `${ageSecs}s` })
     }