@agfpd/iapeer 0.4.97 → 0.4.98

package/docs/15-fleet-api.md

@@ -48,7 +48,7 @@ The full fleet state. The peer rows are produced by the **same in-process functi
       "default_runtime": "claude",
       "cwd": "/Users/me/.iapeer/peers/boris",
       "runtimes": [
-        { "runtime": "claude", "status": "live", "attached": true },
+        { "runtime": "claude", "status": "live", "attached": true, "activity": "working" },
         { "runtime": "codex",  "status": "asleep" }
       ],
       "last_active_runtime": "claude",
@@ -78,6 +78,7 @@ Field notes:
 
 - `runtimes[].status` — `live` (session up) · `asleep` (wakeable on demand) · `stopped` (operator stop flag; the daemon won't wake it). Same glyph semantics as the CLI: `●` / `○` / `✕`.
 - `runtimes[].attached` — present (`true`) only when a **human operator** is attached to that live hosted session.
+- `runtimes[].activity` — **turn activity**: is this runtime *in a turn* right now. See «Activity» below. Additive; absent on a pre-activity daemon, on every non-`live` runtime, and whenever the daemon has no evidence — clients MUST treat absence as **no claim**, never as `idle`.
 - `attached` — any runtime attached (peer-level convenience).
 - `launchd_managed` — launchd owns this peer's lifecycle (H4): the daemon never wakes/reaps it, and wake/stop/start commands are guarded accordingly.
 - `wake_policy` — `warm` (default: wake-on-message, idle-reap, resume) or `ephemeral` (stateless worker: serial task queue, die-after-reply).
@@ -90,6 +91,65 @@ Field notes:
 - `approvals` (top-level, docs/17-approval) — the pending human-approval queue, the SAME items `GET /fleet/v1/approvals` returns, carried in the snapshot so a client that already re-fetches `/snapshot` on every event renders the queue with no extra call. **ADDITIVE + OMITTED when the queue is empty** — a client MUST treat its absence as an empty queue (the same rule as `approval_mode`). Each item: `id` (broker id, the target of `POST /fleet/v1/approvals/<id>/(approve|deny)`), `personality` + `runtime` (whose action), `kind` (`tool`|`plan`|`question`|`circuit-breaker`), `tool` (the tool / breaker name), `summary` (a one-line badge string), `content` (the FULL verbatim action — command / diff / plan; criterion #7), `createdMs` / `expiresMs`. The broker's item is a superset — unknown extra fields (`title`, `approvers`) MUST be ignored (obligation 2).
 - `notices` (top-level, docs/19-notices) — live OWNER-facing notices: things the daemon noticed that the peer itself could not report, the v1 case being a structural API error that left it MUTE (`kind: peer-mute`). The SAME items `GET /fleet/v1/notices` returns. **ADDITIVE + OMITTED when the board is empty** — absence ⇒ empty board (the same rule as `approvals`). **READ-ONLY**: a notice is one-way, there is nothing to approve or deny. Each item: `id`, `personality` + `runtime` (who went mute), `kind` (`peer-mute`; treat unknown kinds as renderable), `errorType` (the RUNTIME's own value — `rate_limit`, `overloaded`, `rate_limit_reached`, … — free-form, do not switch exhaustively), `model?`, `resetsAtMs?`, `summary`, `content` (verbatim for claude), `sessionId?`, `createdMs` / `lastMs` / `expiresMs`, `count` (detections folded in — render as `×N`). **`model` and `resetsAtMs` are ABSENT when the runtime did not state them** — absence means *the runtime did not say*, NOT *there is no limit*; a client MUST render unknown and MUST NOT substitute the 5h/7d reset, which belongs to a different limit (docs/19 §3).
 
+## Activity — is this runtime in a turn?
+
+`runtimes[].activity` answers the operator's actual question, which `status` never did: a peer
+idling with an unfinished job and a peer grinding through a turn are BOTH `live`.
+
+**Activity is not liveness, and the two never merge.** `status` keeps its exact prior meaning.
+`activity` is an additive sibling on the same per-runtime object.
+
+| value | meaning |
+|---|---|
+| `working` | a turn is in flight on this runtime |
+| `idle` | live, but not in a turn |
+| `unknown` | live; the turn was seen to start, never seen to finish, and the evidence has gone stale |
+| *absent* | **no claim** — see below |
+
+`activity` is **ABSENT** (never `idle`) when any of these hold, and a client MUST NOT infer
+idleness from absence:
+
+- the daemon predates this field (obligation 1);
+- `status !== 'live'` — an asleep/stopped session has no turn to be in;
+- the daemon has no evidence for that live runtime yet.
+
+### Where the value comes from
+
+The **runtime's own turn marker**, read from its session file. Never CPU, never a pane-log
+mtime, never a reconstruction:
+
+- **codex** — the rollout's `event_msg` payloads `task_started` → `working`, `task_complete` →
+  `idle`; last one wins. Codex emits `task_complete` for a turn that ends on an error too, so
+  the terminal-error path needs no separate marker.
+- **claude** — the transcript's assistant `stop_reason`. **Only `tool_use` means the turn
+  continues**; every other terminal reason (`end_turn`, `stop_sequence`, `max_tokens`, a future
+  value, `null`) means it ended. The polarity is deliberately asymmetric: an unrecognised reason
+  must never invent work. A genuine `user` line also reads `working` (a prompt to answer or a
+  tool_result to consume), but compaction summaries (`isCompactSummary`), sub-agent sidechains
+  (`isSidechain`) and injected meta lines (`isMeta`) are excluded — each is a measured
+  false-`working` vector, the worst being a `/compact` run while idle leaving a phantom
+  `working` forever.
+
+### Bounds a client can rely on
+
+- **Lag** — the daemon re-reads changed session files every **~3 s**, so an `idle`↔`working`
+  flip appears within roughly one interval plus fs latency. A turn shorter than the interval may
+  never be observed at all; activity is a *state* to render, not an event ledger to count.
+- **Stale bound** — a `working` claim whose evidence is older than **10 min** decays to
+  `unknown`. `idle` NEVER decays: a session that ended its turn stays idle until something pokes
+  it, and age proves nothing against that.
+- **Restart** — the board is in-memory and re-seeds from the session files (a 48 h look-back) on
+  daemon start, so a restart cannot preserve a phantom `working`; a stale one decays by the rule
+  above, and a dead session drops out via `status` first.
+
+### Events
+
+`turns.log` → the SSE stream, `src: "turns"`, `ev`: **`turn-started`** / **`turn-ended`**, with
+`personality`, `runtime`, `from` (the previous state, absent on first observation), `at` +
+`at_iso` (the MARKER's own timestamp, not the sweep's). Emitted only on a real state **change** —
+two lines per turn per runtime, not one per sweep. Treat the snapshot as the source of truth and
+these as a push hint (obligation: the stream is at-least-once).
+
 ## GET /fleet/v1/peers/&lt;personality&gt;
 
 One peer's card: the same object as the snapshot row, plus its recent history.
@@ -122,7 +182,7 @@ GET /fleet/v1/events?replay=50
 - A comment `: connected` marks the transition from replay to live; `: hb` comments every ~15 s keep the connection alive.
 - Latency: live events surface within ~0.5 s (log-tail poll).
 
-Current `ev` vocabulary (grows over time — see obligation 1): `wake`, `supervise` (with `action`: `reaped-idle` = parked, `reaped-ephemeral`, `dead`→fresh/resume classification, `eager-orphan-fresh`, `skipped-error`…), `stopped` / `started` (the stop/start verbs — an operator changed a peer's ✕/○ state; `action` is `stopped`/`started` for warm runtimes, `bootout`/`bootstrap` for always-on, with `reason` on failure), `delivery`, `topic-note`, `ephemeral-drain`, `attach` / `attach-end`, `hosted-deliver`, `pty-host-failed`, `supervise-error`, `composer-queue-failed-notify`, `memory-provision`, `session-exit` (from `exits.log`: `cause=child-exit` with `dead_status`/`dead_signal` when the session's process died on its own, `cause=shutdown-sigterm`/`shutdown-sigint` when the supervisor was torn down — reap/stop/new), `supervisor-uncaught` (a survivable supervisor fault left as forensics; the session keeps serving), `notice-raised` (docs/19 — the daemon told the OWNER something a peer could not tell him itself: a structural API error left it mute. One line per condition, not per occurrence — repeats fold into the live notice silently).
+Current `ev` vocabulary (grows over time — see obligation 1): `wake`, `supervise` (with `action`: `reaped-idle` = parked, `reaped-ephemeral`, `dead`→fresh/resume classification, `eager-orphan-fresh`, `skipped-error`…), `stopped` / `started` (the stop/start verbs — an operator changed a peer's ✕/○ state; `action` is `stopped`/`started` for warm runtimes, `bootout`/`bootstrap` for always-on, with `reason` on failure), `delivery`, `topic-note`, `ephemeral-drain`, `attach` / `attach-end`, `hosted-deliver`, `pty-host-failed`, `supervise-error`, `composer-queue-failed-notify`, `memory-provision`, `session-exit` (from `exits.log`: `cause=child-exit` with `dead_status`/`dead_signal` when the session's process died on its own, `cause=shutdown-sigterm`/`shutdown-sigint` when the supervisor was torn down — reap/stop/new), `supervisor-uncaught` (a survivable supervisor fault left as forensics; the session keeps serving), `notice-raised` (docs/19 — the daemon told the OWNER something a peer could not tell him itself: a structural API error left it mute. One line per condition, not per occurrence — repeats fold into the live notice silently), `turn-started` / `turn-ended` (from `turns.log`, `src: turns` — a runtime entered/left a turn; see «Activity». One line per real state CHANGE, never one per sweep).
 
 What the headline states look like on the stream: a peer **waking** is `ev=wake`; a peer **parked to sleep** is `ev=supervise action=reaped-idle`; an operator **stop/start** is `ev=stopped` / `ev=started`; a **death** is `ev=session-exit` (immediately, from the supervisor) followed by the daemon's classification on its next pass.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.4.97",
+  "version": "0.4.98",
   "description": "Run Claude Code and Codex CLI as local background agents that message each other, wake on demand, and share one memory.",
   "license": "Apache-2.0",
   "author": "agfpd",

package/src/daemon/fleet.ts

@@ -64,6 +64,8 @@ import { approvalsLogPath } from './approvalslog.ts'
 import { ApprovalBroker } from './approvals.ts'
 import { noticesLogPath } from './noticeslog.ts'
 import { NoticeBoard } from './notices.ts'
+import { turnsLogPath } from './turnslog.ts'
+import { ActivityBoard, type TurnActivity } from './turnwatch.ts'
 import { callTool, type CallToolDeps } from './index.ts'
 
 /** The API generation baked into every snapshot (additive evolution within v1 —
@@ -79,6 +81,18 @@ export interface FleetRuntimeStatus {
   status: 'live' | 'asleep' | 'stopped'
   /** Present (true) iff a HUMAN operator is attached to this live hosted session. */
   attached?: boolean
+  /** Whether this runtime is IN A TURN right now — a SEPARATE concept from `status`, which
+   *  stays pure liveness (docs/15 §Activity). Read from the runtime's own turn marker
+   *  (codex `task_started`/`task_complete`; claude assistant `stop_reason`), never from CPU or
+   *  an mtime proxy.
+   *
+   *  ABSENT unless `status === 'live'`: an asleep/stopped session has no turn to be in, and a
+   *  fabricated `idle` would read as a claim we have not earned. Also absent for a live session
+   *  the daemon has no evidence for yet.
+   *
+   *  `unknown` = live, saw the turn start, never saw it finish, and the evidence has gone
+   *  stale (TURN_STALE_MS) — an honest "no claim", never a phantom `working`. */
+  activity?: TurnActivity
 }
 
 export interface FleetPeer {
@@ -208,12 +222,25 @@ export function buildFleetSnapshot(
   nowMs: number = Date.now(),
   approvals: FleetApproval[] = [],
   notices: FleetNotice[] = [],
+  /** Per-runtime turn activity (docs/15 §Activity). Injected — the snapshot never scans
+   *  session files itself; the turn-watch owns that and keeps an in-memory board, so building
+   *  a snapshot stays O(peers). Absent lookup (library/test daemons) → the field is simply
+   *  never emitted, which is exactly its "no claim" semantics. */
+  activityOf?: (personality: string, runtime: string) => TurnActivity | undefined,
 ): FleetSnapshot {
   const peers: FleetPeer[] = ops.listPeers({ env }).map(r => {
     const runtimes: FleetRuntimeStatus[] = r.runtimes.map(s => {
       const attached =
         s.status === 'live' && hasAttachedSupervisorClient(buildProcessAddress(s.runtime, r.personality), env)
-      return { runtime: s.runtime, status: s.status, ...(attached ? { attached: true } : {}) }
+      // Live-only, by design: see FleetRuntimeStatus.activity on why a dead session gets no
+      // claim rather than a fabricated `idle`.
+      const activity = s.status === 'live' ? activityOf?.(r.personality, s.runtime) : undefined
+      return {
+        runtime: s.runtime,
+        status: s.status,
+        ...(attached ? { attached: true } : {}),
+        ...(activity ? { activity } : {}),
+      }
     })
     let ephemeral = false
     try {
@@ -296,6 +323,10 @@ export function fleetEventFiles(cfg: LifecycleConfig): Array<{ path: string; src
     // path — a face subscribed to /fleet/v1/events receives owner notices with no
     // further wiring, exactly as it already receives approvals.
     { path: noticesLogPath(cfg.eventLogDir), src: 'notices' },
+    // Turn-activity events (docs/15 §Activity): turn-started / turn-ended. Same trick — the
+    // log IS the push path. Written on a real state CHANGE only, so this is two lines per turn
+    // per runtime, not one per sweep.
+    { path: turnsLogPath(cfg.eventLogDir), src: 'turns' },
   ]
 }
 
@@ -517,6 +548,11 @@ export interface FleetHandlerOptions {
    *  mute-watch raises into — that shared instance IS the wiring: the watch writes, this
    *  handler reads. Default: a fresh one (a handler with no watch simply stays empty). */
   board?: NoticeBoard
+  /** The turn-activity board (docs/15 §Activity). Same sharing contract as `board`: the
+   *  composition point passes the SAME instance the turn-watch folds observations into.
+   *  Default: a fresh one — a handler with no watch reports no activity at all, which is the
+   *  correct "no claim" rather than a fabricated idle. */
+  activity?: ActivityBoard
 }
 
 export type FleetHandler = (
@@ -542,6 +578,11 @@ export function buildFleetHandler(opts: FleetHandlerOptions = {}): FleetHandler
   // The notice board — one per daemon; the mute-watch RAISES into it and the /notices reads
   // below serve it. Same shape as the broker above: one in-memory store, many interfaces.
   const board = opts.board ?? new NoticeBoard({ logDir: cfg.eventLogDir, env })
+  // The turn-activity board — same one-store-many-interfaces shape. The turn-watch folds
+  // observations in; the snapshot below reads it. Reading is O(1): no file touched per request.
+  const activity = opts.activity ?? new ActivityBoard()
+  const activityOf = (personality: string, runtime: string): TurnActivity | undefined =>
+    activity.get(personality, runtime, Date.now())
   let opsPromise: Promise<FleetOps> | undefined
   const getOps = (): Promise<FleetOps> => {
     if (opts.ops) return Promise.resolve(opts.ops)
@@ -564,7 +605,7 @@ export function buildFleetHandler(opts: FleetHandlerOptions = {}): FleetHandler
         return sendJson(
           res,
           200,
-          buildFleetSnapshot(env, cfg, await getOps(), startedAtMs, undefined, broker.list(), board.list()),
+          buildFleetSnapshot(env, cfg, await getOps(), startedAtMs, undefined, broker.list(), board.list(), activityOf),
         )
       }
       if (path === '/fleet/v1/events') {
@@ -576,7 +617,17 @@ export function buildFleetHandler(opts: FleetHandlerOptions = {}): FleetHandler
       if (peerMatch) {
         if (method !== 'GET') return sendJson(res, 405, { error: 'method not allowed — GET /fleet/v1/peers/<peer>' })
         const personality = decodeURIComponent(peerMatch[1]!)
-        const snapshot = buildFleetSnapshot(env, cfg, await getOps(), startedAtMs)
+        // activityOf passed here too: peer-detail must not disagree with the list it came from.
+        const snapshot = buildFleetSnapshot(
+          env,
+          cfg,
+          await getOps(),
+          startedAtMs,
+          undefined,
+          undefined,
+          undefined,
+          activityOf,
+        )
         const peer = snapshot.peers.find(p => p.personality === personality)
         if (!peer) return sendJson(res, 404, { error: `unknown peer "${personality}"` })
         const events = readRecentEvents(files, 50, personality)

package/src/daemon/main.ts

@@ -70,6 +70,7 @@ import { buildFleetHandler } from './fleet.ts'
 import { NoticeBoard } from './notices.ts'
 import { startMuteWatch } from './mutewatch.ts'
 import { startGoalWatch } from './goalwatch.ts'
+import { ActivityBoard, startTurnWatch } from './turnwatch.ts'
 import { defaultDaemonSocketPath, startDaemon, type DaemonHandle } from './index.ts'
 
 /** Default TCP loopback port for the always-on router. Real http MCP clients
@@ -107,6 +108,12 @@ export const DEFAULT_MUTEWATCH_INTERVAL_MS = 20_000
  *  DB, and the threads join runs ONLY when a stalled row is actually present. */
 export const DEFAULT_GOALWATCH_INTERVAL_MS = 20_000
 
+/** Turn-watch cadence (docs/15 §Activity) — how often the daemon re-reads the turn markers of
+ *  session files that CHANGED. Much faster than the notice watches because the fact is
+ *  short-lived: a turn can be shorter than 20 s, so a 20 s sweep would report `idle` straight
+ *  through one. This bounds the snapshot's idle↔working lag to roughly one interval. */
+export const DEFAULT_TURNWATCH_INTERVAL_MS = 3_000
+
 // This module's own path — the launchd plist runs `bun <this>` as the daemon.
 const DAEMON_MAIN_PATH = fileURLToPath(import.meta.url)
 
@@ -339,6 +346,8 @@ export interface ConfiguredDaemonOptions {
   muteWatchIntervalMs?: number
   /** Goal-watch sweep cadence (default DEFAULT_GOALWATCH_INTERVAL_MS). */
   goalWatchIntervalMs?: number
+  /** Turn-watch sweep cadence (default DEFAULT_TURNWATCH_INTERVAL_MS). */
+  turnWatchIntervalMs?: number
   /** Write the router.json discovery file (default true for production). */
   discovery?: boolean
   rootDir?: string
@@ -392,6 +401,22 @@ export async function startConfiguredDaemon(opts: ConfiguredDaemonOptions = {}):
       } catch { /* best-effort */ }
     },
   })
+  // Turn-activity board + watch (docs/15 §Activity). Constructed HERE for the same reason as
+  // the notice board: the watch WRITES it and the fleet handler READS it, and that sharing is
+  // the whole wiring. Faster cadence than the notice watches (3 s vs 20 s) because a turn is a
+  // short-lived fact — a 20 s sweep would miss whole turns. Affordable: the sweep stats only
+  // files CHANGED since the last pass (measured on this host: ~2 ms across both runtime trees).
+  const activity = new ActivityBoard()
+  const stopTurnWatch = startTurnWatch(cfg, activity, {
+    env,
+    intervalMs: opts.turnWatchIntervalMs ?? DEFAULT_TURNWATCH_INTERVAL_MS,
+    onError: (err: unknown) => {
+      try {
+        const detail = err instanceof Error ? (err.stack ?? err.message) : String(err)
+        appendLifecycleEvent(cfg.eventLogDir, { ev: 'turnwatch-error', error: detail.replace(/\s+/g, ' ').slice(0, 600) }, { env })
+      } catch { /* best-effort */ }
+    },
+  })
   const handle = await startDaemon({
     wake: makeWakeFn(cfg, env),
     // M2 arm-on-outbound (see makeArmEphemeralOnDelivered): ephemeral caller's ok
@@ -418,7 +443,7 @@ export async function startConfiguredDaemon(opts: ConfiguredDaemonOptions = {}):
     // (the same listPeers truth as `iapeer list`), SSE events (tail of the durable
     // logs), commands over the existing verb functions. Same listeners, same bearer
     // gate; advertised in router.json as fleet:1. Contract: docs/15-fleet-api.md.
-    fleet: buildFleetHandler({ env, board }),
+    fleet: buildFleetHandler({ env, board, activity }),
     supervise: {
       intervalMs: opts.superviseIntervalMs ?? DEFAULT_SUPERVISE_INTERVAL_MS,
       // idle-reap / zombie-sweep, THEN the eager fresh re-launch for any peer whose
@@ -466,7 +491,7 @@ export async function startConfiguredDaemon(opts: ConfiguredDaemonOptions = {}):
   // The mute-watch timer is OURS, not startDaemon's — so its teardown must hang off the
   // handle we return, or a closed daemon would leave a live timer sweeping the disk (and
   // every test that starts a daemon would hang on exit).
-  return { ...handle, close: async () => { stopMuteWatch(); stopGoalWatch(); await handle.close() } }
+  return { ...handle, close: async () => { stopMuteWatch(); stopGoalWatch(); stopTurnWatch(); await handle.close() } }
 }
 
 // ─────────────────────────────────────────────────────────────────────────────

package/src/daemon/turnslog.ts

@@ -0,0 +1,52 @@
+// Turn-activity durable log — the daemon's DURABLE trace of every per-runtime turn boundary
+// it observes (docs/15 §Activity). Sibling to lifecycle.log / delivery.log / exits.log /
+// approvals.log / notices.log under cfg.eventLogDir; tailed by the fleet-API SSE stream
+// (fleetEventFiles), so `turn-started` / `turn-ended` reach every operator client with
+// at-least-once semantics — the same "the log IS the push mechanism" trick notices.log uses.
+//
+// Volume is bounded by DESIGN, not by luck: turnWatchTick writes only on a real state CHANGE,
+// never once per sweep. The watch polls every ~3 s; without that guard it would emit a line per
+// peer per pass and drown the very log meant to make turn history readable. Two lines per turn
+// per runtime is the ceiling.
+//
+// Same rotation class as its siblings: written by OUR code → self-rotates via the shared
+// storage/rotatelog primitive. The dir is passed IN by the composition point, never re-resolved
+// from env — a falsy dir → no-op (library/test daemons stay hermetic).
+
+import { join } from 'path'
+import { DEFAULT_LOG_KEEP, DEFAULT_LOG_MAX_BYTES, appendRotatedEvent } from '../storage/rotatelog.ts'
+
+/** The turn-activity log inside `logDir` (sibling to notices.log). */
+export function turnsLogPath(logDir: string): string {
+  return join(logDir, 'turns.log')
+}
+
+function envPosInt(raw: string | undefined, dflt: number): number {
+  const n = parseInt(raw ?? '', 10)
+  return Number.isFinite(n) && n > 0 ? n : dflt
+}
+
+export interface AppendTurnOptions {
+  /** Reads the rotation knobs IAPEER_TURNS_LOG_MAX_BYTES / _KEEP. */
+  env?: NodeJS.ProcessEnv
+  /** Stamp the line with this epoch-ms. Default Date.now(). */
+  nowMs?: number
+}
+
+/**
+ * Append one turn event line into `logDir`/turns.log. A falsy `logDir` is a no-op. Fully
+ * best-effort — never throws; logging must never fail a detection sweep.
+ */
+export function appendTurnEvent(
+  logDir: string | undefined,
+  fields: Record<string, string | number | undefined>,
+  opts: AppendTurnOptions = {},
+): void {
+  if (!logDir) return
+  const env = opts.env ?? process.env
+  appendRotatedEvent(turnsLogPath(logDir), fields, {
+    nowMs: opts.nowMs,
+    maxBytes: envPosInt(env.IAPEER_TURNS_LOG_MAX_BYTES, DEFAULT_LOG_MAX_BYTES),
+    keep: envPosInt(env.IAPEER_TURNS_LOG_KEEP, DEFAULT_LOG_KEEP),
+  })
+}

package/src/daemon/turnwatch.ts

@@ -0,0 +1,450 @@
+// Turn-watch — per-runtime TURN ACTIVITY for the fleet surface (docs/15 §Activity).
+//
+// WHY THIS EXISTS. The snapshot answered exactly one question about a session: is the process
+// alive (`status: live | asleep | stopped`). That is LIVENESS, and it is not the operator's
+// question. A peer sitting idle with an unfinished job and a peer grinding through a turn are
+// both `live` — indistinguishable. The owner spotted a stalled peer before the PM twice
+// because the surface could not tell "working" from "merely alive".
+//
+// ACTIVITY IS NOT LIVENESS, AND THEY STAY SEPARATE. `status` keeps its exact meaning; the new
+// `activity` field is additive and rides ALONGSIDE it on the same per-runtime object. A client
+// that ignores `activity` is unaffected. Activity is reported ONLY for a `live` runtime — for
+// an asleep/stopped session there is no turn to be in, and the field is OMITTED rather than
+// filled with a fake `idle`: absent means "no claim", which a dead session deserves.
+//
+// THE EVIDENCE IS THE RUNTIME'S OWN TURN MARKER — mechanical, never a CPU/mtime reconstruction:
+//
+//   • codex → the rollout's `event_msg` payloads `task_started` / `task_complete`. Explicit
+//     turn boundaries; the last one wins. Measured across 3 days of real rollouts: 156 started
+//     / 147 complete — the 9-line gap is precisely the dangling-turn risk the stale bound below
+//     exists for. Codex emits `task_complete` even for a turn that ended on an error (measured:
+//     the 16.07 goal-blocking turn ends token_count → task_complete, no error event), so the
+//     terminal error path needs no separate marker.
+//
+//   • claude → the transcript's assistant `stop_reason`. `tool_use` means the turn CONTINUES;
+//     every other terminal reason means it ended. Measured over every transcript this peer has:
+//     tool_use 18317, end_turn 663, stop_sequence 16, null 4. So the rule is deliberately
+//     ASYMMETRIC — only `tool_use` reads as working, and anything else (end_turn, stop_sequence,
+//     max_tokens, refusal, an unknown future value, null) reads as IDLE. An unknown reason must
+//     never invent work; the polarity always fails toward idle.
+//
+// THE THREE FALSE-WORKING TRAPS, each measured on real transcripts rather than assumed:
+//
+//   1. **A `user` line means working** (the model is about to answer, or a tool_result just
+//      landed) — but claude writes NON-model user lines too. A compaction summary is
+//      `type:"user"` with `isCompactSummary:true` (12 found here), and a `/compact` run while
+//      IDLE would leave one as the last line → a permanent phantom "working". Excluded. The
+//      `compact_boundary` line is `type:"system"` and never qualifies anyway. Excluding the
+//      summary is also CORRECT for mid-turn compaction: the prior assistant `tool_use` line
+//      then decides, and the turn is genuinely still running.
+//   2. **Sub-agent lines.** A Task sidechain writes assistant/user lines into the SAME
+//      transcript with `isSidechain:true`. They belong to a different chain and must not decide
+//      the peer's turn state. Excluded.
+//   3. **Injected meta lines** (`isMeta:true`, 13 found here) are not the model being asked
+//      anything. Excluded.
+//
+// THE STALE BOUND. A `working` claim rests on evidence that stops being written the moment a
+// session hangs mid-turn — the transcript simply goes quiet. Liveness already removes the dead
+// session (activity is live-only), so what remains is a LIVE session whose last recorded act
+// was starting work and which has since written nothing. Past TURN_STALE_MS the claim decays to
+// `unknown` rather than standing as `working` forever: unknown is the honest word for "we saw
+// it start and never saw it finish". `idle` never decays — a session that ended its turn stays
+// idle until something pokes it, and age proves nothing against that.
+//
+// Deliberately NOT the pane-log mtime, which looks like a freshness clock and is not: measured
+// live 16.07, an IDLE claude pane-log advances every second (the statusline repaints) while an
+// IDLE codex pane-log freezes (39s→46s). The signal means opposite things per runtime; one
+// clock that lies differently on each runtime is worse than no clock.
+
+import { existsSync, openSync, closeSync, fstatSync, readSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import type { LifecycleConfig } from '../lifecycle/index.ts'
+import { appendTurnEvent } from './turnslog.ts'
+
+/** Tail parsed per session file. The turn marker is always at the very end. */
+const TAIL_BYTES = 128 * 1024
+/** Head slice for codex's `session_meta` (line 1 — a long rollout pushes it out of the tail). */
+const HEAD_BYTES = 64 * 1024
+/** Walk depth for the codex YYYY/MM/DD tree. */
+const CODEX_WALK_DEPTH = 3
+/** How far back the FIRST sweep looks, to seed state for sessions already running when the
+ *  daemon started. Bounded on purpose: a full-history pass would read every transcript ever.
+ *  Measured cost of a 48h seed on this host: ~2 ms of walk, 97 files. */
+const SEED_LOOKBACK_MS = 48 * 3_600_000
+/** Overlap on the since-boundary so a write landing between sweeps is never missed. */
+const SCAN_OVERLAP_MS = 2_000
+
+/**
+ * How long a `working` claim outlives its last evidence before decaying to `unknown`.
+ * Generous on purpose: a turn legitimately writes NOTHING while one long tool runs (a deploy
+ * here takes minutes), and a false `unknown` on a genuinely working peer is a worse lie than a
+ * late one. Ten minutes is far past any tool this fleet runs and still bounds the phantom.
+ */
+export const TURN_STALE_MS = 10 * 60_000
+
+/** The operator-facing verdict. `unknown` = live, but the evidence cannot support a claim. */
+export type TurnActivity = 'working' | 'idle' | 'unknown'
+
+export interface TurnState {
+  state: 'working' | 'idle'
+  /** The EVIDENCE's own timestamp (the transcript line's), never our sweep clock. */
+  atMs: number
+  cwd: string
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Pure parsers — text in, state out (fs-free: tests need no session tree)
+// ─────────────────────────────────────────────────────────────────────────────
+
+function toMs(ts: unknown): number | null {
+  if (typeof ts !== 'string') return null
+  const ms = Date.parse(ts)
+  return Number.isFinite(ms) ? ms : null
+}
+
+/**
+ * The claude transcript's turn state, or null if the file states nothing usable.
+ *
+ * Only `tool_use` continues a turn; every other stop_reason ends it (see the header on why the
+ * polarity is asymmetric). Compaction summaries, sidechain lines and meta lines are excluded —
+ * each is a measured false-working vector.
+ */
+export function parseClaudeTurn(text: string): TurnState | null {
+  let found: TurnState | null = null
+  for (const line of text.split('\n')) {
+    const s = line.trim()
+    if (!s.startsWith('{')) continue // a partial first line from the tail cut
+    let d: Record<string, unknown>
+    try {
+      d = JSON.parse(s) as Record<string, unknown>
+    } catch {
+      continue // never fail a sweep over one garbled line
+    }
+    const type = d.type
+    if (type !== 'assistant' && type !== 'user') continue
+    if (d.isSidechain === true) continue // a sub-agent's chain, not the peer's turn
+    if (d.isCompactSummary === true) continue // compaction artifact, not the model being asked
+    if (d.isMeta === true) continue // injected, not a real prompt
+    const atMs = toMs(d.timestamp)
+    if (atMs === null) continue
+    const cwd = typeof d.cwd === 'string' ? d.cwd : ''
+    if (!cwd) continue // unattributable to a peer → ignore rather than guess
+    let state: 'working' | 'idle'
+    if (type === 'assistant') {
+      const msg = d.message as { stop_reason?: unknown } | undefined
+      // ONLY tool_use continues. end_turn / stop_sequence / max_tokens / refusal / an unknown
+      // future value / null all mean the assistant stopped.
+      state = msg?.stop_reason === 'tool_use' ? 'working' : 'idle'
+    } else {
+      // A real user line: a prompt to answer or a tool_result to consume — either way the
+      // model is on the hook. (The non-model user lines were filtered above.)
+      state = 'working'
+    }
+    found = { state, atMs, cwd }
+  }
+  return found
+}
+
+/**
+ * The codex rollout's turn state, or null. `task_started` / `task_complete` are explicit
+ * boundaries — the last one wins. `cwd` comes from `session_meta` (line 1), so pass the file
+ * HEAD when the tail may have cut it away.
+ */
+export function parseCodexTurn(text: string, head = ''): TurnState | null {
+  let cwd = ''
+  const scanMeta = (src: string): void => {
+    for (const line of src.split('\n')) {
+      const s = line.trim()
+      if (!s.startsWith('{') || !s.includes('session_meta')) continue
+      try {
+        const d = JSON.parse(s) as { type?: string; payload?: { cwd?: unknown } }
+        if (d.type !== 'session_meta' || !d.payload) continue
+        if (typeof d.payload.cwd === 'string') cwd = d.payload.cwd
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+  scanMeta(head)
+  if (!cwd) scanMeta(text)
+  if (!cwd) return null // unattributable to a peer
+
+  let found: TurnState | null = null
+  for (const line of text.split('\n')) {
+    const s = line.trim()
+    if (!s.startsWith('{') || !s.includes('task_')) continue
+    let d: { timestamp?: unknown; type?: unknown; payload?: { type?: unknown } }
+    try {
+      d = JSON.parse(s)
+    } catch {
+      continue
+    }
+    if (d.type !== 'event_msg') continue
+    const p = d.payload?.type
+    if (p !== 'task_started' && p !== 'task_complete') continue
+    const atMs = toMs(d.timestamp)
+    if (atMs === null) continue
+    found = { state: p === 'task_started' ? 'working' : 'idle', atMs, cwd }
+  }
+  return found
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// The board — in-memory (personality, runtime) → last known turn state
+// ─────────────────────────────────────────────────────────────────────────────
+
+function key(personality: string, runtime: string): string {
+  return `${runtime}-${personality}` // the identity scheme (docs/03)
+}
+
+/**
+ * Last known turn state per (personality, runtime). In-memory and ephemeral, exactly like the
+ * notice board: a restart re-seeds from the session files, which are the durable truth.
+ */
+export class ActivityBoard {
+  private readonly states = new Map<string, TurnState>()
+
+  /** Record an observation. Returns the PREVIOUS state, so the caller can log only real
+   *  transitions rather than one line per sweep. */
+  set(personality: string, runtime: string, next: TurnState): TurnState | undefined {
+    const k = key(personality, runtime)
+    const prev = this.states.get(k)
+    // Evidence older than what we already hold is a stale re-read — never let it rewind state.
+    if (prev && next.atMs < prev.atMs) return prev
+    this.states.set(k, next)
+    return prev
+  }
+
+  /** The operator-facing verdict, with the stale bound applied at READ time (so a claim decays
+   *  even while nothing new is swept). `undefined` → we have no evidence at all. */
+  get(personality: string, runtime: string, nowMs: number): TurnActivity | undefined {
+    const st = this.states.get(key(personality, runtime))
+    if (!st) return undefined
+    if (st.state === 'idle') return 'idle' // idle never decays — age proves nothing against it
+    return nowMs - st.atMs > TURN_STALE_MS ? 'unknown' : 'working'
+  }
+
+  /** The raw record (peer-detail / tests). */
+  raw(personality: string, runtime: string): TurnState | undefined {
+    return this.states.get(key(personality, runtime))
+  }
+
+  size(): number {
+    return this.states.size
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// The sweep
+// ─────────────────────────────────────────────────────────────────────────────
+
+function readTail(path: string): { tail: string; head: string } | null {
+  try {
+    const fd = openSync(path, 'r')
+    try {
+      const size = fstatSync(fd).size
+      if (size <= 0) return null
+      const off = Math.max(0, size - TAIL_BYTES)
+      const buf = Buffer.alloc(size - off)
+      readSync(fd, buf, 0, buf.length, off)
+      let head = ''
+      if (off > 0) {
+        const hb = Buffer.alloc(Math.min(HEAD_BYTES, off))
+        readSync(fd, hb, 0, hb.length, 0)
+        head = hb.toString('utf8')
+      }
+      return { tail: buf.toString('utf8'), head }
+    } finally {
+      closeSync(fd)
+    }
+  } catch {
+    return null
+  }
+}
+
+function safeReaddir(dir: string): string[] {
+  try {
+    return readdirSync(dir)
+  } catch {
+    return []
+  }
+}
+
+/** *.jsonl under `root` (depth-bounded) whose mtime is at/after `sinceMs`. */
+function changedJsonl(root: string, sinceMs: number, depth: number): string[] {
+  if (!existsSync(root)) return []
+  const out: string[] = []
+  const walk = (dir: string, left: number): void => {
+    for (const name of safeReaddir(dir)) {
+      const p = join(dir, name)
+      if (name.endsWith('.jsonl')) {
+        let m: number | null = null
+        try {
+          m = statSync(p).mtimeMs
+        } catch {
+          continue
+        }
+        if (m >= sinceMs) out.push(p)
+        continue
+      }
+      if (left <= 0 || name.startsWith('.')) continue
+      try {
+        if (statSync(p).isDirectory()) walk(p, left - 1)
+      } catch {
+        continue
+      }
+    }
+  }
+  walk(root, depth)
+  return out
+}
+
+export interface TurnWatchPaths {
+  /** ~/.claude/projects — INJECTED, never re-resolved from env inside a sweep. */
+  claudeProjectsDir: string
+  /** ~/.codex/sessions — same rule. */
+  codexSessionsDir: string
+}
+
+export function resolveTurnWatchPaths(env: NodeJS.ProcessEnv): TurnWatchPaths {
+  const home = env.HOME?.trim() || ''
+  return {
+    claudeProjectsDir: env.IAPEER_CLAUDE_PROJECTS_DIR?.trim() || join(home, '.claude', 'projects'),
+    codexSessionsDir: env.IAPEER_CODEX_SESSIONS_DIR?.trim() || join(home, '.codex', 'sessions'),
+  }
+}
+
+export interface TurnScanDeps extends TurnWatchPaths {
+  /** personality ← cwd. Built from the registry by the composition point. */
+  peerByCwd: (cwd: string) => string | undefined
+}
+
+export interface TurnObservation extends TurnState {
+  personality: string
+  runtime: 'claude' | 'codex'
+}
+
+/** One sweep: the turn state of every peer session file touched since `sinceMs`. */
+export function scanTurnStates(deps: TurnScanDeps, sinceMs: number): TurnObservation[] {
+  const floor = sinceMs - SCAN_OVERLAP_MS
+  const out: TurnObservation[] = []
+  const push = (st: TurnState | null, runtime: 'claude' | 'codex'): void => {
+    if (!st) return
+    const personality = deps.peerByCwd(st.cwd)
+    if (!personality) return // a human's own session — never reported
+    out.push({ ...st, personality, runtime })
+  }
+  for (const file of changedJsonl(deps.claudeProjectsDir, floor, 1)) {
+    const t = readTail(file)
+    if (t) push(parseClaudeTurn(t.tail), 'claude')
+  }
+  for (const file of changedJsonl(deps.codexSessionsDir, floor, CODEX_WALK_DEPTH)) {
+    const t = readTail(file)
+    if (t) push(parseCodexTurn(t.tail, t.head), 'codex')
+  }
+  return out
+}
+
+export interface TurnWatchDeps extends TurnScanDeps {
+  board: ActivityBoard
+  /** cfg.eventLogDir — turns.log (falsy → no durable log, hermetic). */
+  logDir?: string
+  env?: NodeJS.ProcessEnv
+  now?: () => number
+  onError?: (err: unknown) => void
+}
+
+/**
+ * Run one watch tick: sweep, fold into the board, log REAL transitions only.
+ * Returns how many transitions were logged plus the new since-boundary.
+ */
+export function turnWatchTick(deps: TurnWatchDeps, sinceMs: number): { transitions: number; sinceMs: number } {
+  const now = deps.now ?? Date.now
+  const startedMs = now()
+  let transitions = 0
+  try {
+    for (const o of scanTurnStates(deps, sinceMs)) {
+      const prev = deps.board.set(o.personality, o.runtime, { state: o.state, atMs: o.atMs, cwd: o.cwd })
+      // Only a genuine change is an event. Without this the 3 s sweep would write a line per
+      // pass per peer and bury the log it is supposed to make readable.
+      if (prev?.state === o.state) continue
+      // A rewound observation (older evidence than held) is not a transition either.
+      if (prev && o.atMs < prev.atMs) continue
+      transitions += 1
+      appendTurnEvent(
+        deps.logDir,
+        {
+          ev: o.state === 'working' ? 'turn-started' : 'turn-ended',
+          personality: o.personality,
+          runtime: o.runtime,
+          from: prev?.state,
+          at: o.atMs,
+          at_iso: new Date(o.atMs).toISOString(),
+        },
+        { env: deps.env, nowMs: startedMs },
+      )
+    }
+  } catch (e) {
+    deps.onError?.(e)
+  }
+  return { transitions, sinceMs: startedMs }
+}
+
+export interface StartTurnWatchOptions {
+  env?: NodeJS.ProcessEnv
+  intervalMs?: number
+  paths?: TurnWatchPaths
+  listPeers?: () => Array<{ personality: string; cwd: string }>
+  now?: () => number
+  onError?: (err: unknown) => void
+}
+
+/**
+ * Start the turn-watch timer. Returns its stop function — the caller OWNS teardown.
+ * The FIRST sweep reaches back SEED_LOOKBACK_MS so sessions already mid-turn when the daemon
+ * started are known immediately; every later sweep is incremental (changed files only).
+ */
+export function startTurnWatch(cfg: LifecycleConfig, board: ActivityBoard, opts: StartTurnWatchOptions = {}): () => void {
+  const env = opts.env ?? process.env
+  const paths = opts.paths ?? resolveTurnWatchPaths(env)
+  const now = opts.now ?? Date.now
+  let listPeers = opts.listPeers
+  let since = now() - SEED_LOOKBACK_MS
+  let running = false
+
+  const sweep = async (): Promise<void> => {
+    if (running) return // a slow sweep must never overlap itself into a stampede
+    running = true
+    try {
+      if (!listPeers) {
+        const cli = await import('../cli/index.ts')
+        listPeers = () => cli.listPeers({ env }).map(p => ({ personality: p.personality, cwd: p.cwd }))
+      }
+      const rows = listPeers()
+      // Case-insensitive, trailing-slash-tolerant — same rule and reason as mutewatch.
+      const byCwd = new Map<string, string>()
+      for (const r of rows) if (r.cwd) byCwd.set(r.cwd.replace(/\/+$/, '').toLowerCase(), r.personality)
+      since = turnWatchTick(
+        {
+          ...paths,
+          board,
+          logDir: cfg.eventLogDir,
+          env,
+          now,
+          onError: opts.onError,
+          peerByCwd: (cwd: string) => byCwd.get(cwd.replace(/\/+$/, '').toLowerCase()),
+        },
+        since,
+      ).sinceMs
+    } catch (e) {
+      opts.onError?.(e)
+    } finally {
+      running = false
+    }
+  }
+
+  void sweep() // seed immediately — do not make the operator wait one interval for the truth
+  const timer = setInterval(() => void sweep(), opts.intervalMs ?? 3_000)
+  ;(timer as { unref?: () => void }).unref?.()
+  return () => clearInterval(timer)
+}