@cleocode/goal 0.0.0-stage → 0.9.0

package/src/engine/state.ts

@@ -0,0 +1,185 @@
+// Run state for one goal and the rules about who may change it. The worker
+// model can report progress, claim, block, flag and wait; only the owner (or the
+// host acting on owner policy) can start, resume, pause, abort or approve.
+import type { Contract } from "../contract/types"
+
+export type Status =
+  | "running"
+  | "waiting"
+  | "verifying"
+  | "paused"
+  | "blocked"
+  | "needs_review"
+  | "budget_limited"
+  | "complete"
+  | "failed"
+  | "aborted"
+  | "superseded"
+
+export const ACTIVE: readonly Status[] = ["running", "waiting", "verifying"]
+export const TERMINAL: readonly Status[] = ["complete", "failed", "aborted", "superseded"]
+export const isActive = (s: Status) => ACTIVE.includes(s)
+export const isTerminal = (s: Status) => TERMINAL.includes(s)
+
+export type CriterionState = {
+  status: "unknown" | "pass" | "fail" | "claimed"
+  by?: "host" | "verifier" | "verifier-fallback" | "human"
+  at?: number
+  detail?: string
+  rejections: number
+}
+
+export type PendingKind = "kickoff" | "continue" | "verdict" | "recovery" | "wrapup" | "resume"
+export type Handoff = { fromSessionID: string; toSessionID: string; agent?: string; model?: { providerID: string; id: string; variant?: string }; fallback?: string; /** v0.8.0: the generated handoff document, relative to the goal folder. */ file?: string }
+
+export type RunState = {
+  version: 1
+  slug: string
+  title: string
+  /** T061: copied from the contract at start so the registry/rebuild keep it. */
+  priority?: "low" | "medium" | "high"
+  sessionID: string
+  runId: string
+  lock: string
+  status: Status
+  reason?: string
+  createdAt: number
+  updatedAt: number
+  turn: number
+  activeMs: number
+  activeSince: number | null
+  usage: { tokens: number; cost: number; baseTokens: number | null; baseCost: number | null }
+  base: { commit?: string }
+  fingerprint?: string
+  counters: { noProgress: number; failures: number }
+  wrapup: boolean
+  blocker?: { key: string; count: number; reason: string; needs?: string; lastTurn: number }
+  criteria: Record<string, CriterionState>
+  steps: Record<string, "pending" | "active" | "done">
+  progress?: { note: string; next?: string; at: number; turn: number }
+  verdict?: { at: number; turn: number; passed: boolean; lines: string[] }
+  claim?: { at: number; turn: number; summary: string; evidence: Record<string, string> }
+  wait?: { until: number; reason: string }
+  pending?: { messageID: string; turn: number; at: number; kind: PendingKind }
+  turnFacts: { tools: number; goalCalls: number; stepsChanged: boolean; progressRecorded: boolean }
+  steers: number
+  compacted: boolean
+  /** last wall-clock ms the TUI/rpc was refreshed by a usage.recorded burst (T013) */
+  lastUsageEmit?: number
+  /** T053: what the engine is doing right now — feeds the live activity tracer. */
+  activity?: { kind: "turn" | "verifying" | "verifier-child" | "cooldown" | "waiting"; since: number; until?: number; detail?: string }
+  flags: Array<{ criterion?: string; kind: string; reason: string; at: number }>
+  amendments: Array<{ change: string; rationale: string; at: number; status: "proposed" | "accepted" | "rejected" }>
+  handoff?: Handoff
+  /** v0.8.0: peer availability announcements and the candidates they produced. */
+  peer?: {
+    lastAt?: number
+    outstanding?: { id: string; at: number }
+    lastReplyAt?: number
+    /** Bounded best-effort polling of the outstanding announcement. */
+    polls?: number
+    candidates?: Array<{ source: "peer"; project: string; taskId?: string; title: string; from?: string; messageId?: string; at?: number }>
+  }
+}
+
+export function initialRun(contract: Contract, args: { sessionID: string; runId: string; lock: string; commit?: string; now?: number }): RunState {
+  const now = args.now ?? Date.now()
+  return {
+    version: 1,
+    slug: contract.id,
+    title: contract.title,
+    ...(contract.priority ? { priority: contract.priority } : {}),
+    sessionID: args.sessionID,
+    runId: args.runId,
+    lock: args.lock,
+    status: "running",
+    createdAt: now,
+    updatedAt: now,
+    turn: 0,
+    activeMs: 0,
+    activeSince: now,
+    usage: { tokens: 0, cost: 0, baseTokens: null, baseCost: null },
+    base: args.commit ? { commit: args.commit } : {},
+    counters: { noProgress: 0, failures: 0 },
+    wrapup: false,
+    criteria: Object.fromEntries([...contract.criteria, ...contract.invariants].map((c) => [c.id, { status: "unknown", rejections: 0 } as CriterionState])),
+    steps: Object.fromEntries(contract.plan.map((s, i) => [s.id, i === 0 ? "active" : "pending"])),
+    turnFacts: { tools: 0, goalCalls: 0, stepsChanged: false, progressRecorded: false },
+    steers: 0,
+    compacted: false,
+    flags: [],
+    amendments: [],
+  }
+}
+
+/** Accumulate active (running/waiting/verifying) wall time. */
+export function account(state: RunState, now = Date.now()): RunState {
+  if (state.activeSince !== null) {
+    state.activeMs += Math.max(0, now - state.activeSince)
+    state.activeSince = isActive(state.status) ? now : null
+  } else if (isActive(state.status)) state.activeSince = now
+  state.updatedAt = now
+  return state
+}
+
+/** Move to a new status, keeping the active clock honest. */
+export function setStatus(state: RunState, status: Status, reason?: string, now = Date.now()): RunState {
+  account(state, now)
+  state.status = status
+  state.reason = reason
+  state.activeSince = isActive(status) ? now : null
+  if (!isActive(status)) state.pending = undefined
+  return state
+}
+
+export type OwnerAction = "pause" | "resume" | "abort" | "verify" | "approve" | "reject" | "amend" | "archive" | "revert"
+
+/** Owner transitions; returns an error string when the action does not apply. */
+export function ownerCan(state: RunState, action: OwnerAction): string | undefined {
+  switch (action) {
+    case "pause":
+      return isActive(state.status) ? undefined : `goal is ${state.status}`
+    case "resume":
+      return ["paused", "blocked", "needs_review", "budget_limited"].includes(state.status) ? undefined : `goal is ${state.status}; only a stopped goal can resume`
+    case "abort":
+      return isTerminal(state.status) ? `goal is already ${state.status}` : undefined
+    case "verify":
+      return isTerminal(state.status) ? `goal is ${state.status}` : undefined
+    case "revert":
+      return isTerminal(state.status) ? `goal is ${state.status}` : state.status === "verifying" ? "goal is verifying; wait for its verdict" : undefined
+    case "amend":
+      // T038: amendment re-locks a live contract; a terminal goal gets a new
+      // goal instead (supersession), never a rewrite of history.
+      return isTerminal(state.status) ? `goal is ${state.status}; write a new goal or supersede it instead` : undefined
+    case "archive":
+      // T032: demote-never-delete applies to finished work; a live goal is
+      // aborted first, never archived mid-flight.
+      return isTerminal(state.status) ? undefined : `goal is ${state.status}; abort it before archiving`
+    case "approve":
+    case "reject":
+      return isTerminal(state.status) ? `goal is ${state.status}` : undefined
+  }
+}
+
+export type ModelAction = "progress" | "claim" | "block" | "flag" | "wait" | "amend"
+
+/** The worker may only act on a goal that is running in its own session. */
+export function modelCan(state: RunState | undefined, action: ModelAction): string | undefined {
+  if (!state) return "no goal is running in this session"
+  if (isTerminal(state.status)) return `the goal is ${state.status}`
+  if (state.status === "verifying" && action !== "progress") return "the host is verifying your last claim; end your turn"
+  if (!["running", "waiting", "verifying"].includes(state.status)) return `the goal is ${state.status}; the owner must resume it`
+  return undefined
+}
+
+export const budgetUse = (state: RunState, contract: Contract, now = Date.now()) => {
+  const active = state.activeMs + (state.activeSince !== null ? Math.max(0, now - state.activeSince) : 0)
+  const b = contract.budget
+  const parts: Array<{ name: "turns" | "wall" | "tokens" | "cost"; used: number; limit: number }> = []
+  if (b.turns) parts.push({ name: "turns", used: state.turn, limit: b.turns })
+  if (b.wallMs) parts.push({ name: "wall", used: active, limit: b.wallMs })
+  if (b.tokens) parts.push({ name: "tokens", used: state.usage.tokens, limit: b.tokens })
+  if (b.cost_usd) parts.push({ name: "cost", used: state.usage.cost, limit: b.cost_usd })
+  const ratio = parts.reduce((max, p) => Math.max(max, p.used / p.limit), 0)
+  return { active, parts, ratio }
+}

package/src/engine/store.ts

@@ -0,0 +1,263 @@
+// A goal is a folder: .opencode/goals/<slug>/ holds the owner's contract
+// (goal.yaml) and the plugin's run.json, ledger.jsonl and evidence/.
+import { appendFileSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, writeFileSync, writeSync } from "node:fs"
+import { join } from "node:path"
+import { parseContract, type ParseResult } from "../contract/parse"
+import type { RunState } from "./state"
+import type { AmendmentRequest } from "./amendments"
+
+export type LedgerEvent = { t: number; type: string; [key: string]: unknown }
+
+export class Store {
+  readonly goalsDir: string
+  constructor(readonly root: string) {
+    this.goalsDir = join(root, ".opencode", "goals")
+  }
+
+  dir(slug: string) {
+    return join(this.goalsDir, slug)
+  }
+
+  contractPath(slug: string) {
+    return join(this.dir(slug), "goal.yaml")
+  }
+
+  slugs(): string[] {
+    if (!existsSync(this.goalsDir)) return []
+    return readdirSync(this.goalsDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory() && existsSync(join(this.goalsDir, d.name, "goal.yaml")))
+      .map((d) => d.name)
+      .sort()
+  }
+
+  /** T032: the archive tier sits beside goals/ — demoted, never deleted. */
+  get archiveDir() {
+    return join(this.root, ".opencode", "goals-archive")
+  }
+
+  archivedSlugs(): string[] {
+    if (!existsSync(this.archiveDir)) return []
+    return readdirSync(this.archiveDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory() && existsSync(join(this.archiveDir, d.name, "goal.yaml")))
+      .map((d) => d.name)
+      .sort()
+  }
+
+  archivedPath(slug: string) {
+    return join(this.archiveDir, slug)
+  }
+
+  /** Move a goal folder into the archive tier (ledger and evidence travel along). */
+  archive(slug: string) {
+    mkdirSync(this.archiveDir, { recursive: true })
+    renameSync(this.dir(slug), this.archivedPath(slug))
+  }
+
+  readContract(slug: string, options: { archived?: boolean } = {}): (ParseResult & { text: string }) | undefined {
+    const path = options.archived ? join(this.archivedPath(slug), "goal.yaml") : this.contractPath(slug)
+    if (!existsSync(path)) return undefined
+    const text = readFileSync(path, "utf8")
+    return { ...parseContract(text, { slug }), text }
+  }
+
+  /** T108: the raw bytes plus any duplicated object keys. JSON.parse silently
+   * keeps the last duplicate, so a hand merge (the reported shape: two
+   * "updatedAt", "tokens", "tools", "lastUsageEmit") would otherwise become the
+   * run's state without anyone writing it on purpose. */
+  readRunRaw(slug: string, options: { archived?: boolean } = {}): { text: string; duplicates: string[] } | undefined {
+    const path = join(options.archived ? this.archivedPath(slug) : this.dir(slug), "run.json")
+    if (!existsSync(path)) return undefined
+    const text = readFileSync(path, "utf8")
+    return { text, duplicates: duplicateJsonKeys(text) }
+  }
+
+  readRun(slug: string, options: { archived?: boolean } = {}): RunState | undefined {
+    const raw = this.readRunRaw(slug, options)
+    if (!raw || raw.duplicates.length) return undefined
+    try {
+      const value = JSON.parse(raw.text)
+      return value?.version === 1 ? (value as RunState) : undefined
+    } catch {
+      return undefined
+    }
+  }
+
+  /** Keep the exact bytes a corrupt run.json had, beside the run. */
+  keepCorruptRun(slug: string, text: string, at = Date.now()): string {
+    const dir = this.dir(slug)
+    mkdirSync(dir, { recursive: true })
+    const path = join(dir, `run.json.corrupt-${at}.json`)
+    writeFileSync(path, text, { mode: 0o600 })
+    return path
+  }
+
+  writeRun(state: RunState) {
+    const dir = this.dir(state.slug)
+    mkdirSync(dir, { recursive: true })
+    const path = join(dir, "run.json")
+    const tmp = `${path}.${process.pid}.${Date.now()}.tmp`
+    const fd = openSync(tmp, "w", 0o600)
+    try {
+      writeSync(fd, `${JSON.stringify(state, null, 2)}\n`)
+      fsyncSync(fd)
+    } finally {
+      closeSync(fd)
+    }
+    renameSync(tmp, path)
+  }
+
+  writeContractSnapshot(slug: string, runId: string, lock: string, text: string) {
+    const dir = join(this.dir(slug), "evidence", runId)
+    mkdirSync(dir, { recursive: true })
+    const path = join(dir, `contract-${lock}.yaml`)
+    if (existsSync(path)) return
+    this.writeAtomic(path, text)
+  }
+
+  /** Redo an accepted generation from a durable host write-ahead receipt.
+   * Recovery runs before hooks admit work: consumers cannot see half of a
+   * generation. Neither a new run nor an unexpected third lock is overwritten. */
+  commitAmendment(request: AmendmentRequest): RunState {
+    if (!request.commit || request.status !== "executing") throw new Error("Amendment has no host-recorded acceptance")
+    const read = this.readContract(request.slug), state = this.readRun(request.slug)
+    const next = parseContract(request.nextText, { slug: request.slug })
+    if (!next.contract || next.lock !== request.nextLock) throw new Error("Approved amendment payload is invalid")
+    if (!state || state.runId !== request.runId || state.sessionID !== request.targetSessionID) throw new Error("Amendment target identity changed")
+    if (state.lock !== request.lock && state.lock !== request.nextLock) throw new Error("Amendment run lock conflicts with a different generation")
+    if (!read || read.lock !== request.lock && read.lock !== request.nextLock) throw new Error("Amendment disk contract changed outside the reviewed generation")
+    if (request.commit.state.lock !== request.nextLock || request.commit.state.runId !== state.runId) throw new Error("Invalid host write-ahead state")
+    const result = state.lock === request.nextLock ? state : request.commit.state
+    this.writeContractSnapshot(request.slug, request.runId, request.lock, read.lock === request.lock ? read.text : this.lockedSnapshot(request.slug, request.runId, request.lock))
+    this.writeContractSnapshot(request.slug, request.runId, request.nextLock, request.nextText)
+    if (read.lock !== request.nextLock) this.writeAtomic(this.contractPath(request.slug), request.nextText)
+    if (state.lock !== request.nextLock) this.writeRun(result)
+    const generation = result.amendments.filter((a) => a.status === "accepted").length
+    this.evidence(request.slug, request.runId, `amendment-${generation}-${request.id}`, {
+      decisionId: request.id, generation, oldLock: request.lock, newLock: request.nextLock,
+      by: request.appliedBy ?? "owner", ...(request.policyClasses ? { policyClasses: request.policyClasses } : {}), at: request.commit.acceptedAt, rationale: request.rationale,
+      ...request.diff, contract: request.nextText,
+    })
+    if (!this.recent(request.slug, 1000).some((e) => e.type === "amended" && e.decisionId === request.id))
+      this.ledger(request.slug, { type: "amended", decisionId: request.id, generation, oldLock: request.lock, newLock: request.nextLock, summary: request.diff.summary, by: request.appliedBy ?? "owner", ...(request.policyClasses ? { policyClasses: request.policyClasses } : {}), ...(request.recovery ? { recovery: true } : {}) })
+    return result
+  }
+
+  /** Owner-chosen divergence restore: keep the divergent disk bytes as
+   * evidence, then write the locked generation's exact bytes back. */
+  restoreLocked(slug: string, runId: string, lock: string, discarded: { text: string; lock: string }): string {
+    const locked = this.lockedSnapshot(slug, runId, lock)
+    const dir = join(this.dir(slug), "evidence", runId)
+    mkdirSync(dir, { recursive: true })
+    const kept = join(dir, `divergent-${discarded.lock}-${Date.now()}.yaml`)
+    this.writeAtomic(kept, discarded.text)
+    const current = this.readContract(slug)
+    if (!current || current.lock !== discarded.lock) throw new Error("Disk contract changed again during restore; nothing written")
+    this.writeAtomic(this.contractPath(slug), locked)
+    return kept
+  }
+
+  lockedText(slug: string, runId: string, lock: string): string { return this.lockedSnapshot(slug, runId, lock) }
+
+  private lockedSnapshot(slug: string, runId: string, lock: string): string {
+    const keyed = join(this.dir(slug), "evidence", runId, `contract-${lock}.yaml`)
+    const first = join(this.dir(slug), "evidence", runId, "contract.yaml")
+    const text = readFileSync(existsSync(keyed) ? keyed : first, "utf8")
+    if (parseContract(text, { slug }).lock !== lock) throw new Error("Prior locked amendment snapshot is unavailable")
+    return text
+  }
+
+  private writeAtomic(path: string, text: string) {
+    const tmp = `${path}.${process.pid}.${Date.now()}.tmp`
+    const fd = openSync(tmp, "wx", 0o600)
+    try { writeSync(fd, text); fsyncSync(fd) } finally { closeSync(fd) }
+    renameSync(tmp, path)
+  }
+
+  /** The last n ledger events, oldest first; tolerant of a torn final line. */
+  recent(slug: string, n: number): LedgerEvent[] {
+    const path = join(this.dir(slug), "ledger.jsonl")
+    if (!existsSync(path)) return []
+    const lines = readFileSync(path, "utf8").trimEnd().split("\n")
+    const out: LedgerEvent[] = []
+    for (const line of lines.slice(-n)) {
+      try {
+        out.push(JSON.parse(line) as LedgerEvent)
+      } catch {
+        // a half-written trailing line is skipped, never fatal
+      }
+    }
+    return out
+  }
+
+  ledger(slug: string, event: Omit<LedgerEvent, "t"> & { t?: number }, options: { archived?: boolean } = {}) {
+    const dir = options.archived ? this.archivedPath(slug) : this.dir(slug)
+    mkdirSync(dir, { recursive: true })
+    appendFileSync(join(dir, "ledger.jsonl"), `${JSON.stringify({ t: Date.now(), ...event })}\n`, { mode: 0o600 })
+  }
+
+  readLedger(slug: string, limit = 50): LedgerEvent[] {
+    const path = join(this.dir(slug), "ledger.jsonl")
+    if (!existsSync(path)) return []
+    return readFileSync(path, "utf8")
+      .split("\n")
+      .filter(Boolean)
+      .slice(-limit)
+      .flatMap((line) => {
+        try {
+          return [JSON.parse(line) as LedgerEvent]
+        } catch {
+          return []
+        }
+      })
+  }
+
+  evidence(slug: string, runId: string, name: string, data: unknown): string {
+    const dir = join(this.dir(slug), "evidence", runId)
+    mkdirSync(dir, { recursive: true })
+    const file = join(dir, `${name}.json`)
+    const fd = openSync(file, "w", 0o600)
+    try {
+      writeSync(fd, `${JSON.stringify(data, null, 2)}\n`)
+    } finally {
+      closeSync(fd)
+    }
+    return file
+  }
+}
+
+/** Duplicated keys inside any JSON object, as dotted paths. A tiny scanner,
+ * because JSON itself cannot report them. */
+export function duplicateJsonKeys(text: string): string[] {
+  const duplicates: string[] = []
+  const stack: Array<{ keys: Set<string>; path: string }> = []
+  let i = 0, pending = ""
+  while (i < text.length) {
+    const ch = text[i]!
+    if (ch === '"') {
+      let j = i + 1, raw = ""
+      while (j < text.length) {
+        if (text[j] === "\\") { raw += text[j + 1] ?? ""; j += 2; continue }
+        if (text[j] === '"') break
+        raw += text[j]
+        j++
+      }
+      i = j + 1
+      // A string is a key when the next non-space character is ':'.
+      let k = i
+      while (k < text.length && /\s/.test(text[k]!)) k++
+      if (text[k] === ":" && stack.length) {
+        const level = stack[stack.length - 1]!
+        const path = level.path ? `${level.path}.${raw}` : raw
+        if (level.keys.has(raw)) duplicates.push(path)
+        level.keys.add(raw)
+        pending = path
+      }
+      continue
+    }
+    if (ch === "{") { stack.push({ keys: new Set(), path: pending }); pending = ""; i++; continue }
+    if (ch === "}") { stack.pop(); pending = ""; i++; continue }
+    if (ch === "," || ch === ":" || ch === "[" || ch === "]") { if (ch === ",") pending = ""; i++; continue }
+    i++
+  }
+  return [...new Set(duplicates)]
+}

package/src/engine/tick-record.ts

@@ -0,0 +1,129 @@
+// v0.7.0 - RECORDING a turn at Stop time, for a harness that is not OpenCode.
+//
+// The OpenCode adapter records a turn from its own event stream: the turn
+// counter, the repository fingerprint, whether the agent called the progress
+// tool, and whether a plan step moved. A CLI at a Stop event cannot see the
+// session - so this module records ONLY what a Stop-time observer can honestly
+// know, and says what it could not see:
+//
+//   always      the turn increment; the repository fingerprint (a move counts
+//               as progress); a claim the run already carries
+//   from the    a transcript the Stop payload points at, mined best-effort for
+//   payload     tool calls and a progress call - OPTIONAL, and its absence is
+//               never an error
+//
+// It never invents a tool call, a progress call or a live-check transition that
+// it did not observe. Everything is written through OCG's own store afterwards,
+// so records, ledger and schema stay identical to the adapter's.
+
+import type { Contract } from "../contract/types"
+import type { RunState } from "./state"
+
+/** What a Stop-time observer can see, injected so the recorder is testable. */
+export type RecordInputs = {
+  /** The repository fingerprint now (git), or undefined when it cannot be taken. */
+  fingerprint: () => string | undefined
+  /** The raw harness Stop payload, if the harness passed one. */
+  payload?: string
+  /** Read a transcript the payload points at. Absent/unreadable is fine. */
+  readTranscript?: (path: string) => string | undefined
+  now?: number
+}
+
+export type TurnRecord = {
+  turn: number
+  changed: boolean
+  progress: boolean
+  claimHonoured: boolean
+  /** What the payload mining recovered, when a readable transcript was named. */
+  mined?: { transcriptPath: string; toolCalls: number; ownerMessages: number; progressCall: boolean }
+  /** What this observer could NOT see, named rather than assumed. */
+  couldNotSee: string[]
+}
+
+/** The names a progress call may appear under in a transcript. */
+const PROGRESS_TOOLS = /goal_progress|progress|goal-status/i
+
+/**
+ * Record one turn on `state` (mutating it) and return what was recorded.
+ * A missing payload, transcript or fingerprint is a degradation, never an error.
+ */
+export function recordTurn(state: RunState, _contract: Contract, inputs: RecordInputs): TurnRecord {
+  const couldNotSee: string[] = []
+  state.turn = (state.turn ?? 0) + 1
+
+  // The fingerprint is the only progress the observer can measure itself.
+  let changed = false
+  try {
+    const fp = inputs.fingerprint()
+    changed = fp !== undefined && fp !== state.fingerprint
+    state.fingerprint = fp
+  } catch {
+    couldNotSee.push("the repository fingerprint (it could not be taken)")
+  }
+
+  // A claim already on the run is honoured: it is the agent's own statement.
+  const claimHonoured = Boolean(state.claim)
+
+  // Best-effort payload mining. A harness without a transcript simply does not
+  // get tool-call accounting - and that is stated, not guessed.
+  let mined: TurnRecord["mined"]
+  let progressCall = false
+  const payload = inputs.payload?.trim()
+  if (!payload) {
+    couldNotSee.push("the agent's tool calls and progress call (the harness passed no Stop payload)")
+  } else {
+    let transcriptPath: string | undefined
+    try {
+      const parsed = JSON.parse(payload)
+      transcriptPath = typeof parsed?.transcript_path === "string" ? parsed.transcript_path : typeof parsed?.transcriptPath === "string" ? parsed.transcriptPath : undefined
+    } catch {
+      couldNotSee.push("the Stop payload (it was not JSON)")
+    }
+    if (!transcriptPath) {
+      couldNotSee.push("the agent's tool calls and progress call (the Stop payload named no transcript)")
+    } else if (!inputs.readTranscript) {
+      couldNotSee.push("the transcript (this build cannot read one)")
+    } else {
+      let text: string | undefined
+      try {
+        text = inputs.readTranscript(transcriptPath)
+      } catch {
+        text = undefined
+      }
+      if (text === undefined) {
+        couldNotSee.push(`the transcript at ${transcriptPath} (absent or unreadable)`)
+      } else {
+        let toolCalls = 0
+        let ownerMessages = 0
+        for (const line of text.split("\n")) {
+          const trimmed = line.trim()
+          if (!trimmed) continue
+          let entry: any
+          try {
+            entry = JSON.parse(trimmed)
+          } catch {
+            continue // a transcript line we cannot parse is skipped, not counted
+          }
+          const parts: any[] = Array.isArray(entry?.content) ? entry.content : Array.isArray(entry?.message?.content) ? entry.message.content : []
+          if (String(entry?.type ?? entry?.role ?? entry?.message?.role ?? "") === "user") ownerMessages += 1
+          for (const part of parts) {
+            if (part?.type !== "tool_use" && part?.type !== "tool") continue
+            toolCalls += 1
+            if (PROGRESS_TOOLS.test(String(part?.name ?? ""))) progressCall = true
+          }
+        }
+        mined = { transcriptPath, toolCalls, ownerMessages, progressCall }
+        if (toolCalls === 0 && ownerMessages === 0) couldNotSee.push("any content in the transcript (it parsed but held no tool calls or messages)")
+      }
+    }
+  }
+
+  const progress = changed || progressCall
+  state.counters.noProgress = progress ? 0 : (state.counters.noProgress ?? 0) + 1
+  state.pending = undefined
+  state.turnFacts = { tools: mined?.toolCalls ?? 0, goalCalls: progressCall ? 1 : 0, stepsChanged: false, progressRecorded: progressCall }
+  state.updatedAt = inputs.now ?? Date.now()
+  state.activity = { kind: "turn", since: state.updatedAt, detail: "tick" }
+  return { turn: state.turn, changed, progress, claimHonoured, ...(mined ? { mined } : {}), couldNotSee }
+}