@agfpd/iapeer 0.4.96 → 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/docs/19-notices.md

@@ -29,7 +29,8 @@ renders approvals renders notices with the same plumbing.
 
 ## 2. The signal: `peer-mute`
 
-The v1 notice kind. It means: *a structural API error left this peer unable to answer.*
+The first notice kind (§2a adds `peer-goal-stalled`). It means: *a structural API error left
+this peer unable to answer.*
 
 The daemon does not infer this from silence — silence is unfalsifiable. It reads the fact
 **structurally** out of the runtime's own session file. Neither runtime is scraped from the
@@ -66,6 +67,63 @@ detector keys on **non-null**, never on the variant strings (`rate_limit_reached
 `workspace_owner_usage_limit_reached`, `workspace_member_credits_depleted`, … — read out of
 the 0.144.1 binary), so a variant we have never seen still detects and reports itself.
 
+## 2a. The signal: `peer-goal-stalled` (codex only)
+
+The second notice kind. It means: *this peer's pinned objective stopped being worked, and
+will not resume on its own.* Same class as `peer-mute` — peer alive, every health signal
+green, nobody told — different evidence and a different cause.
+
+**What the harness is.** Codex 0.144.x pins an objective to a thread (`create_goal`) and then
+continues it AUTOMATICALLY: when the thread goes idle it injects a synthetic
+`<codex_internal_context source="goal">` user message and runs another turn. iapeer owns no
+part of this and writes nothing into it.
+
+**Why it stalls.** `ext/goal/src/extension.rs::on_turn_error` maps every terminal turn error
+that is not a usage limit to `ActiveGoalStopReason::TurnError`, which `ext/goal/src/runtime.rs`
+writes as status `blocked`. That is the **only** path that reaches `blocked` without the model
+calling `update_goal`. Once the status leaves `active`, `clear_active_goal()` runs and
+automatic continuation stops **permanently**: the objective is abandoned while the peer stays
+healthy and keeps taking unrelated turns.
+
+**Where the truth is — the state DB, not the rollout.** Unlike `peer-mute`, this fact is *not*
+in the session file. A live capture (16.07.2026, `zapret2-oneclick`, thread `019f6709…`) holds
+exactly one `thread_goal_updated` event in 1971 rollout lines — the `active` one at resume —
+and **none** for the transition to `blocked`. The transition exists only in codex's goal store:
+
+```
+~/.codex/goals_<n>.sqlite   thread_goals(thread_id, goal_id, objective, status,
+                                         token_budget, tokens_used, time_used_seconds,
+                                         created_at_ms, updated_at_ms)
+~/.codex/state_<n>.sqlite   threads(id, cwd, …)     ← the only place a thread's cwd lives
+```
+
+Both are read **read-only**, and the filename generation is globbed (highest `_<n>` wins) —
+`state_5` says codex has rolled it before, so a pinned literal name would silently read a
+stale DB the day it rolls again. Attribution is the §6 rule unchanged: `thread_id` → `cwd`
+(state DB) → personality (registry). A thread whose cwd is no peer's is a human's own codex
+and is never notified.
+
+**The reported statuses** are codex's own values, verbatim on `errorType`:
+
+| status | meaning | notified |
+|---|---|---|
+| `blocked` | a turn error stopped continuation | **yes** |
+| `usage_limited` | a usage wall stopped continuation | **yes** |
+| `budget_limited` | the token budget stopped continuation | **yes** |
+| `active` | being worked | no — healthy |
+| `complete` | the model proved it done | no — success is not news |
+| `paused` | the human's own choice | no — his own click is not news |
+
+`blocked` and `usage_limited` stay distinct rather than flattening into one "stalled": they
+are different facts with different remedies, and they carry different dedup identities.
+
+**One-shot without a state file.** A stalled goal's row is never touched again — its
+accounting is `ActiveOnly`, measured live: through 17 further minutes of turns the blocked
+row's `tokens_used`/`updated_at_ms` stayed frozen at the block instant. So `updated_at_ms` is
+a stable *transition* clock, and the `updated_at_ms > since` boundary fires exactly once and
+then falls behind forever. A goal blocked while the daemon was down is missed — the same
+honest boundary `peer-mute` already has (§7).
+
 ## 3. What the owner is told — and what is deliberately withheld
 
 A notice states who, which runtime, which error type, which model, and when the wall lifts.
@@ -108,15 +166,15 @@ resets, the plan) — data, never our interpretation of the cause.
 | field | type | notes |
 |---|---|---|
 | `id` | string | `n1`, `n2`, … Unique while live; **not** stable across a daemon restart. |
-| `personality` | string | the mute peer |
+| `personality` | string | the affected peer |
 | `runtime` | string | `claude` \| `codex` |
-| `kind` | string | `peer-mute` in v1. **Treat unknown kinds as renderable** — new kinds ride this surface. |
-| `errorType` | string | the runtime's OWN value (`rate_limit`, `overloaded`, `rate_limit_reached`, …). Free-form: do not switch exhaustively. |
-| `model` | string? | **absent** when the runtime did not name it |
+| `kind` | string | `peer-mute` \| `peer-goal-stalled` (codex only). **Treat unknown kinds as renderable** — new kinds ride this surface. |
+| `errorType` | string | the runtime's OWN value (`rate_limit`, `overloaded`, `rate_limit_reached`, …; for `peer-goal-stalled` the goal status: `blocked` \| `usage_limited` \| `budget_limited`). Free-form: do not switch exhaustively. |
+| `model` | string? | **absent** when the runtime did not name it (always absent on `peer-goal-stalled` — the goal store names no model) |
 | `resetsAtMs` | number? | epoch-ms; **absent** when the runtime did not state it → render "unknown", never substitute |
-| `summary` | string | one line, e.g. `boris · claude — rate_limit (Fable 5)` |
-| `content` | string | verbatim (claude) / rendered from typed fields (codex) |
-| `sessionId` | string? | correlates with the on-disk transcript |
+| `summary` | string | one line, e.g. `boris · claude — rate_limit (Fable 5)`, `zapret2-oneclick · codex — goal blocked: <objective>` |
+| `content` | string | verbatim (claude) / rendered from typed fields (codex, both kinds) |
+| `sessionId` | string? | correlates with the on-disk transcript. On `peer-goal-stalled` this is the codex **thread id** — the rollout's `session_meta.session_id`. |
 | `createdMs` | number | when the notice was raised (board clock — the TTL anchor) |
 | `lastMs` | number | when the latest occurrence was folded in (board clock). A sweep that merely re-reads an already-counted event does not move it. |
 | `expiresMs` | number | TTL boundary |
@@ -241,6 +299,18 @@ there is nothing to derive from. Reading the file's own statement works for both
 - **The blocking-window heuristic is unverified.** Codex does not say WHICH window blocked;
   the notice reports the **fullest** one. Both windows ride in `content`, so a human sees the
   raw fact even if the heuristic picks wrong.
+- **`peer-goal-stalled` — the state read is proven on real data; the CAUSE of one instance is
+  not.** The detector was run against the live goal store on 16.07.2026 and returned exactly
+  the real stall (`zapret2-oneclick`, `blocked`, goal `c25d2378…`, 09:54:32, attributed via the
+  real registry), and returned nothing with the boundary at `now` — both directions on real
+  bytes, not fixtures. What is **not** proven is which turn error blocked that particular goal:
+  codex logged nothing in the 28 s spanning the transition and the rollout carries no error
+  event. That gap does not weaken the detector, which watches the **state** and is deliberately
+  cause-agnostic — it is why the notice reports codex's status verbatim and never names a cause.
+- **The `blocked` mechanism itself is proven by source + live state**, not inferred from
+  silence: `on_turn_error` → `TurnError` → `Blocked` is the only non-`update_goal` writer in
+  the upstream tree, the model called `update_goal` zero times in the captured rollout, and the
+  blocked row's counters stayed frozen through 17 further minutes of turns.
 
 Forensic evidence for all of the above: `docs/internals/forensics/model-limit-2026-07-15/`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.4.96",
+  "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/goalwatch.ts

@@ -0,0 +1,385 @@
+// Goal-watch — the daemon's detector for a codex peer whose OBJECTIVE died while the peer
+// itself stayed perfectly healthy (docs/19). Sibling of mutewatch.ts: same class of failure
+// (peer alive, every health signal green, nothing anywhere saying why), different evidence.
+//
+// WHAT CODEX'S GOAL HARNESS IS. Codex 0.144.x ships a "thread goal": an objective pinned to a
+// thread (`create_goal`), after which codex AUTOMATICALLY continues working it — when the
+// thread goes idle the TUI injects a synthetic `<codex_internal_context source="goal">` user
+// message and runs another turn. That loop is the harness's own; iapeer owns NO part of it and
+// this module WRITES nothing — it only reads what codex already wrote about itself.
+//
+// THE FAILURE. `ext/goal/src/extension.rs::on_turn_error` maps EVERY terminal turn error that
+// is not a usage limit to `ActiveGoalStopReason::TurnError`, and `runtime.rs` turns that into
+// status `blocked`. Upstream calls this deliberate ("Block the goal to prevent automatic
+// continuation from looping and consuming tokens, as can happen with compaction errors"), and
+// it is the ONLY path that writes `blocked` without the model calling `update_goal`. Once the
+// status leaves `active`, `clear_active_goal()` runs and automatic continuation STOPS FOREVER.
+// The objective is abandoned. Nothing dies, nothing errors, no exit code, no IAP message —
+// the peer just never works the objective again. Measured live on this host 16.07.2026
+// (zapret2-oneclick, thread 019f6709…, goal c25d2378…): status `blocked` at 09:54:32 with no
+// `update_goal` call anywhere in the rollout, while the peer went on running unrelated turns
+// for another 17 minutes with its goal counters FROZEN at the block instant.
+//
+// WHY SQLITE AND NOT THE ROLLOUT. mutewatch reads the rollout because the rate-limit fact is
+// written there. The block is NOT: the same live capture shows exactly ONE `thread_goal_updated`
+// event in 1971 rollout lines (the `active` one at resume) and NONE for the transition to
+// `blocked`. The transition is written ONLY to codex's goals DB. Read the state or miss it.
+//
+// WHY TWO DATABASES. The goals DB keys on thread_id and carries no cwd, so a goal row alone
+// cannot be attributed to a peer. Codex's state DB (`threads`) carries `id` + `cwd`. Joining
+// the two yields cwd, and cwd → personality is the SAME attribution rule mutewatch already
+// uses: a thread whose cwd is no peer's (a human's own codex) is ignored, never notified.
+//
+// WHY THE FILENAMES ARE GLOBBED. These are codex's private files and their names carry a
+// schema generation (`goals_1.sqlite`, `state_5.sqlite` — the 5 says it has rolled before).
+// Pinning the literal name would silently read a stale DB the day codex rolls it, so the
+// highest generation present wins. Absent/unreadable/renamed → the detector no-ops. Reading
+// another product's internal store is a real coupling; it is accepted for the same reason
+// mutewatch parses codex's rollout — there is no other place the fact exists — and it is
+// confined to this module, guarded, and READ-ONLY.
+//
+// ONE-SHOT, WITHOUT A STATE FILE. A blocked goal's row is never touched again (its accounting
+// is ActiveOnly — proven live: counters frozen through 17 minutes of later turns), so its
+// `updated_at_ms` is a STABLE transition clock. Filtering on `updated_at_ms > sinceMs` there-
+// fore fires exactly once per transition and then falls behind the boundary forever — no
+// repeat, no TTL re-raise, no persisted "already told him" set. A goal blocked while the
+// daemon was down is missed, exactly as mutewatch misses an error it was not up for; the
+// boundary is the contour's existing honesty, not a new compromise.
+
+import { existsSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import type { LifecycleConfig } from '../lifecycle/index.ts'
+import type { NoticeBoard } from './notices.ts'
+
+/** Overlap on the since-boundary so a transition landing between two sweeps is never missed.
+ *  Re-reads are free: the board folds them by `eventAtMs` (see notices.ts). */
+const SCAN_OVERLAP_MS = 15_000
+/** Objective text is user-authored and unbounded — bound it before it reaches a notice. */
+const OBJECTIVE_MAX = 300
+
+/**
+ * The goal statuses that mean "this objective is not being worked and will not resume on its
+ * own". CODEX'S OWN taxonomy values, never our invention (docs/19 §2).
+ *
+ * Deliberately excluded:
+ *   • `active`    — working; the healthy case.
+ *   • `complete`  — the model proved the objective done. Success is not news.
+ *   • `paused`    — a human's own choice. Notifying him of his own click is noise.
+ * `usage_limited` / `budget_limited` ride along because they are the same shape: continuation
+ * stopped, objective unfinished, nobody told. They are NOT the same CAUSE as `blocked`, which
+ * is why the status travels verbatim as the notice's errorType instead of being flattened.
+ */
+export const STALLED_GOAL_STATUSES = new Set(['blocked', 'usage_limited', 'budget_limited'])
+
+/** A row of codex's `thread_goals`, as codex wrote it. */
+export interface GoalRow {
+  threadId: string
+  goalId: string
+  objective: string
+  status: string
+  tokensUsed: number
+  timeUsedSeconds: number
+  updatedAtMs: number
+}
+
+export interface GoalDetection {
+  personality: string
+  runtime: 'codex'
+  /** Codex's own status value — `blocked` | `usage_limited` | `budget_limited`. */
+  status: string
+  goalId: string
+  threadId: string
+  objective: string
+  tokensUsed: number
+  timeUsedSeconds: number
+  /** The row's `updated_at_ms` — the TRANSITION's own clock, not our sweep's. */
+  atMs: number
+  cwd: string
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Pure selection — rows in, detections out (fs/sqlite-free: tests need no DB)
+// ─────────────────────────────────────────────────────────────────────────────
+
+function clip(s: string, max: number): string {
+  const t = s.replace(/\s+/g, ' ').trim()
+  return t.length <= max ? t : `${t.slice(0, max - 1)}…`
+}
+
+/** The human-readable line, rendered from codex's TYPED fields — codex writes no prose for a
+ *  goal transition, the same situation as its rate-limit snapshot, and the same answer:
+ *  render the facts, never our reading of the cause. */
+export function renderGoalContent(d: Omit<GoalDetection, 'personality' | 'runtime'>): string {
+  return [
+    `Codex goal ${d.status} — automatic goal continuation has stopped; this objective will not`,
+    `resume without an explicit resume. Objective: "${d.objective}".`,
+    `goal=${d.goalId} thread=${d.threadId} accounted=${d.tokensUsed} tokens / ${d.timeUsedSeconds}s.`,
+  ].join(' ')
+}
+
+/**
+ * Every peer-attributable goal that stalled STRICTLY after `sinceMs`.
+ *
+ * `cwdByThread` and `peerByCwd` are injected so this stays pure: the whole selection rule is
+ * testable without a codex install.
+ */
+export function selectStalledGoals(
+  goals: GoalRow[],
+  cwdByThread: Map<string, string>,
+  peerByCwd: (cwd: string) => string | undefined,
+  sinceMs: number,
+): GoalDetection[] {
+  const out: GoalDetection[] = []
+  for (const g of goals) {
+    if (!STALLED_GOAL_STATUSES.has(g.status)) continue
+    if (!Number.isFinite(g.updatedAtMs) || g.updatedAtMs <= sinceMs) continue
+    const cwd = cwdByThread.get(g.threadId)
+    if (!cwd) continue // thread not in the state DB → unattributable; ignore rather than guess
+    const personality = peerByCwd(cwd)
+    if (!personality) continue // a human's own codex thread — never notify
+    out.push({
+      personality,
+      runtime: 'codex',
+      status: g.status,
+      goalId: g.goalId,
+      threadId: g.threadId,
+      objective: clip(g.objective, OBJECTIVE_MAX),
+      tokensUsed: g.tokensUsed,
+      timeUsedSeconds: g.timeUsedSeconds,
+      atMs: g.updatedAtMs,
+      cwd,
+    })
+  }
+  return out
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// The codex-state reader — the only part that touches another product's files
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface GoalWatchPaths {
+  /** ~/.codex — INJECTED, never re-resolved from env inside a sweep. */
+  codexHome: string
+}
+
+export function resolveGoalWatchPaths(env: NodeJS.ProcessEnv): GoalWatchPaths {
+  const home = env.HOME?.trim() || ''
+  return { codexHome: env.IAPEER_CODEX_HOME?.trim() || join(home, '.codex') }
+}
+
+/**
+ * The highest-generation `<prefix>_<n>.sqlite` in `dir`, or null.
+ * Codex rolls the generation when it changes schema; the newest is the live one.
+ */
+export function findVersionedDb(dir: string, prefix: string): string | null {
+  if (!existsSync(dir)) return null
+  let best: { n: number; name: string } | null = null
+  let names: string[]
+  try {
+    names = readdirSync(dir)
+  } catch {
+    return null
+  }
+  const re = new RegExp(`^${prefix}_(\\d+)\\.sqlite$`)
+  for (const name of names) {
+    const m = re.exec(name)
+    if (!m) continue
+    const n = parseInt(m[1] as string, 10)
+    if (!Number.isFinite(n)) continue
+    if (!best || n > best.n) best = { n, name }
+  }
+  return best ? join(dir, best.name) : null
+}
+
+/** Open a codex DB READ-ONLY. Never creates, never migrates, never writes. */
+async function openReadOnly(path: string): Promise<{ query: (sql: string) => { all: (...a: unknown[]) => unknown[] }; close: () => void } | null> {
+  try {
+    const { Database } = (await import('bun:sqlite')) as typeof import('bun:sqlite')
+    return new Database(path, { readonly: true }) as unknown as {
+      query: (sql: string) => { all: (...a: unknown[]) => unknown[] }
+      close: () => void
+    }
+  } catch {
+    return null // absent / locked / rolled schema → the detector no-ops, never throws
+  }
+}
+
+function num(v: unknown): number {
+  return typeof v === 'number' && Number.isFinite(v) ? v : 0
+}
+
+function str(v: unknown): string {
+  return typeof v === 'string' ? v : ''
+}
+
+/** Codex's goal rows. Empty on any shape we do not recognise — never a throw. */
+export async function readGoalRows(codexHome: string): Promise<GoalRow[]> {
+  const path = findVersionedDb(codexHome, 'goals')
+  if (!path) return []
+  const db = await openReadOnly(path)
+  if (!db) return []
+  try {
+    const rows = db
+      .query('SELECT thread_id, goal_id, objective, status, tokens_used, time_used_seconds, updated_at_ms FROM thread_goals')
+      .all() as Array<Record<string, unknown>>
+    return rows.map(r => ({
+      threadId: str(r.thread_id),
+      goalId: str(r.goal_id),
+      objective: str(r.objective),
+      status: str(r.status),
+      tokensUsed: num(r.tokens_used),
+      timeUsedSeconds: num(r.time_used_seconds),
+      updatedAtMs: num(r.updated_at_ms),
+    }))
+  } catch {
+    return []
+  } finally {
+    try {
+      db.close()
+    } catch {
+      /* best-effort */
+    }
+  }
+}
+
+/** thread_id → cwd, for the given threads only. Empty on any unrecognised shape. */
+export async function readThreadCwds(codexHome: string, threadIds: string[]): Promise<Map<string, string>> {
+  const out = new Map<string, string>()
+  if (threadIds.length === 0) return out
+  const path = findVersionedDb(codexHome, 'state')
+  if (!path) return out
+  const db = await openReadOnly(path)
+  if (!db) return out
+  try {
+    const holes = threadIds.map(() => '?').join(',')
+    const rows = db.query(`SELECT id, cwd FROM threads WHERE id IN (${holes})`).all(...threadIds) as Array<Record<string, unknown>>
+    for (const r of rows) {
+      const id = str(r.id)
+      const cwd = str(r.cwd)
+      if (id && cwd) out.set(id, cwd)
+    }
+  } catch {
+    /* unrecognised schema → no attribution, no notice */
+  } finally {
+    try {
+      db.close()
+    } catch {
+      /* best-effort */
+    }
+  }
+  return out
+}
+
+export interface GoalScanDeps extends GoalWatchPaths {
+  /** personality ← cwd. Built from the registry by the composition point. */
+  peerByCwd: (cwd: string) => string | undefined
+}
+
+/** One sweep: every peer-attributable goal that stalled since `sinceMs`. */
+export async function scanStalledGoals(deps: GoalScanDeps, sinceMs: number): Promise<GoalDetection[]> {
+  const floor = sinceMs - SCAN_OVERLAP_MS
+  const goals = await readGoalRows(deps.codexHome)
+  // Only the stalled rows are worth a threads lookup — an active goal is the common case.
+  const candidates = goals.filter(g => STALLED_GOAL_STATUSES.has(g.status) && g.updatedAtMs > floor)
+  if (candidates.length === 0) return []
+  const cwds = await readThreadCwds(
+    deps.codexHome,
+    candidates.map(g => g.threadId).filter(Boolean),
+  )
+  return selectStalledGoals(candidates, cwds, deps.peerByCwd, floor)
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// The tick
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface GoalWatchDeps extends GoalScanDeps {
+  board: NoticeBoard
+  now?: () => number
+  /** Reported, never thrown — a detector must never take the daemon down. */
+  onError?: (err: unknown) => void
+}
+
+/** Run one watch tick: sweep, raise. Returns notices actually RAISED + the new boundary. */
+export async function goalWatchTick(deps: GoalWatchDeps, sinceMs: number): Promise<{ raised: number; sinceMs: number }> {
+  const now = deps.now ?? Date.now
+  const startedMs = now()
+  let raised = 0
+  try {
+    for (const d of await scanStalledGoals(deps, sinceMs)) {
+      const { deduped } = deps.board.raise({
+        personality: d.personality,
+        runtime: d.runtime,
+        kind: 'peer-goal-stalled',
+        // Codex's own status is the taxonomy value — `blocked` and `usage_limited` are
+        // different facts for the owner and must not collapse into one dedup identity.
+        errorType: d.status,
+        content: renderGoalContent(d),
+        // The thread IS the session: it correlates the notice with the rollout on disk.
+        sessionId: d.threadId,
+        // The TRANSITION's own clock — see notices.ts on why this is not the sweep's.
+        eventAtMs: d.atMs,
+        summary: `${d.personality} · codex — goal ${d.status}: ${clip(d.objective, 80)}`,
+      })
+      if (!deduped) raised += 1
+    }
+  } catch (e) {
+    deps.onError?.(e)
+  }
+  return { raised, sinceMs: startedMs }
+}
+
+export interface StartGoalWatchOptions {
+  env?: NodeJS.ProcessEnv
+  intervalMs?: number
+  paths?: GoalWatchPaths
+  /** Override the registry read (tests). Default: a lazy import of the CLI's listPeers. */
+  listPeers?: () => Array<{ personality: string; cwd: string }>
+  now?: () => number
+  onError?: (err: unknown) => void
+}
+
+/**
+ * Start the goal-watch timer. Returns its stop function — the caller OWNS teardown.
+ * Mirrors startMuteWatch: registry re-read every sweep, `listPeers` imported lazily.
+ */
+export function startGoalWatch(_cfg: LifecycleConfig, board: NoticeBoard, opts: StartGoalWatchOptions = {}): () => void {
+  const env = opts.env ?? process.env
+  const paths = opts.paths ?? resolveGoalWatchPaths(env)
+  const now = opts.now ?? Date.now
+  let listPeers = opts.listPeers
+  let since = now()
+  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 same reason as mutewatch:
+      // macOS paths are case-insensitive and codex records the cwd STRING as launched.
+      const byCwd = new Map<string, string>()
+      for (const r of rows) if (r.cwd) byCwd.set(r.cwd.replace(/\/+$/, '').toLowerCase(), r.personality)
+      const deps: GoalWatchDeps = {
+        ...paths,
+        board,
+        now,
+        onError: opts.onError,
+        peerByCwd: (cwd: string) => byCwd.get(cwd.replace(/\/+$/, '').toLowerCase()),
+      }
+      since = (await goalWatchTick(deps, since)).sinceMs
+    } catch (e) {
+      opts.onError?.(e)
+    } finally {
+      running = false
+    }
+  }
+
+  const timer = setInterval(() => void sweep(), opts.intervalMs ?? 20_000)
+  ;(timer as { unref?: () => void }).unref?.()
+  return () => clearInterval(timer)
+}

package/src/daemon/main.ts

@@ -69,6 +69,8 @@ import { appendDeliveryEvent } from './deliverylog.ts'
 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
@@ -100,6 +102,18 @@ export const DEFAULT_SUPERVISE_INTERVAL_MS = 60_000
  *  to spare. The sweep is cheap — it stats only files that CHANGED since the last pass. */
 export const DEFAULT_MUTEWATCH_INTERVAL_MS = 20_000
 
+/** Goal-watch cadence (docs/19) — how often the daemon reads codex's goal store for an
+ *  objective that stopped continuing. Same 20 s and the same reason as the mute-watch: the
+ *  owner must learn within a minute. Cheaper than that sweep — two indexed reads of a small
+ *  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)
 
@@ -330,6 +344,10 @@ export interface ConfiguredDaemonOptions {
   superviseIntervalMs?: number
   /** Mute-watch sweep cadence (default DEFAULT_MUTEWATCH_INTERVAL_MS). */
   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
@@ -369,6 +387,36 @@ export async function startConfiguredDaemon(opts: ConfiguredDaemonOptions = {}):
       } catch { /* best-effort */ }
     },
   })
+  // Goal-watch (docs/19) — the SAME board and the same class as the mute-watch: a peer left
+  // alive and green while the thing it was told to do quietly stopped. Separate detector
+  // because the evidence is elsewhere (codex's goal store, not a transcript) and it is
+  // codex-only; sharing the board is what makes it one owner-facing surface.
+  const stopGoalWatch = startGoalWatch(cfg, board, {
+    env,
+    intervalMs: opts.goalWatchIntervalMs ?? DEFAULT_GOALWATCH_INTERVAL_MS,
+    onError: (err: unknown) => {
+      try {
+        const detail = err instanceof Error ? (err.stack ?? err.message) : String(err)
+        appendLifecycleEvent(cfg.eventLogDir, { ev: 'goalwatch-error', error: detail.replace(/\s+/g, ' ').slice(0, 600) }, { env })
+      } 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
@@ -395,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
@@ -443,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(); 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)
+}