@agfpd/iapeer 0.4.96 → 0.4.97

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.97",
   "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/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,7 @@ 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 { defaultDaemonSocketPath, startDaemon, type DaemonHandle } from './index.ts'
 
 /** Default TCP loopback port for the always-on router. Real http MCP clients
@@ -100,6 +101,12 @@ 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
+
 // This module's own path — the launchd plist runs `bun <this>` as the daemon.
 const DAEMON_MAIN_PATH = fileURLToPath(import.meta.url)
 
@@ -330,6 +337,8 @@ 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
   /** Write the router.json discovery file (default true for production). */
   discovery?: boolean
   rootDir?: string
@@ -369,6 +378,20 @@ 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 */ }
+    },
+  })
   const handle = await startDaemon({
     wake: makeWakeFn(cfg, env),
     // M2 arm-on-outbound (see makeArmEphemeralOnDelivered): ephemeral caller's ok
@@ -443,7 +466,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(); await handle.close() } }
 }
 
 // ─────────────────────────────────────────────────────────────────────────────