@cleocode/goal 0.0.0-stage → 0.9.0

package/src/engine/handoff.ts

@@ -0,0 +1,102 @@
+// v0.8.0 — the launch handoff.
+//
+// A fresh launch used to give the new session the contract and nothing else:
+// no prior run, no red baseline, no "start here". This builder turns facts the
+// host ALREADY holds into a bounded document the kickoff can carry. It is
+// context, not authority: it cannot approve, resume or change anything.
+//
+// Pure so the content is testable without a host. The adapter supplies the
+// facts (prior run, repo head, rehearsal, plan) and writes the two files.
+
+export type PriorRun = {
+  slug: string
+  runId: string
+  lock: string
+  status: string
+  turn: number
+  evidence: string
+  summary?: string
+}
+
+export type HandoffFacts = {
+  slug: string
+  title: string
+  fromSessionID: string
+  toSessionID: string
+  prior?: PriorRun
+  repo: { head?: string; branch?: string; dirty?: string[] }
+  baseline?: Array<{ id: string; pass: boolean }>
+  nextAction?: { step: string; title: string }
+  authority?: { trust: string[]; stale: string[] }
+  evidence?: string[]
+  now?: number
+}
+
+export type HandoffDocument = {
+  schema: "opencode-goal/handoff/v1"
+  generatedAt: string
+  markdown: string
+  data: Omit<HandoffFacts, "now">
+}
+
+/** A turn-1 digest; the full document stays on disk. */
+export const HANDOFF_DIGEST_LIMIT = 8_000
+
+export function buildHandoff(facts: HandoffFacts): HandoffDocument {
+  const generatedAt = new Date(facts.now ?? Date.now()).toISOString()
+  const lines: string[] = []
+  lines.push(`# Handoff — ${facts.slug}`)
+  lines.push(`Generated ${generatedAt} for a fresh goal session. This is context, not authority: it cannot approve a criterion, accept an amendment, resume a stopped goal or change a contract.`)
+  lines.push("")
+  lines.push("## Prior run")
+  if (facts.prior) {
+    lines.push(`- Goal: ${facts.prior.slug} (run ${facts.prior.runId}, ${facts.prior.status}, turn ${facts.prior.turn})`)
+    lines.push(`- Lock: ${facts.prior.lock}`)
+    lines.push(`- Evidence: ${facts.prior.evidence}`)
+    if (facts.prior.summary) lines.push(`- Summary: ${facts.prior.summary}`)
+  } else {
+    lines.push("- No prior run in this project. This is the first goal here; start from the contract and the repo.")
+  }
+  lines.push("")
+  lines.push("## Current state")
+  lines.push(`- Session: ${facts.fromSessionID} → ${facts.toSessionID}`)
+  if (facts.repo.head) lines.push(`- HEAD: ${facts.repo.head}`)
+  if (facts.repo.branch) lines.push(`- Branch: ${facts.repo.branch}`)
+  lines.push(`- Uncommitted: ${facts.repo.dirty?.length ? facts.repo.dirty.slice(0, 20).join(", ") : "none"}`)
+  lines.push("")
+  if (facts.baseline?.length) {
+    lines.push("## Red baseline (measured before this run started)")
+    for (const b of facts.baseline) lines.push(`- ${b.id}: ${b.pass ? "pass" : "failing (red baseline)"}`)
+    lines.push("")
+  }
+  if (facts.nextAction) {
+    lines.push("## Start here")
+    lines.push(`- ${facts.nextAction.step}: ${facts.nextAction.title}`)
+    lines.push("")
+  }
+  if (facts.authority && (facts.authority.trust.length || facts.authority.stale.length)) {
+    lines.push("## Authority")
+    if (facts.authority.trust.length) lines.push(`- Trust: ${facts.authority.trust.join(", ")}`)
+    if (facts.authority.stale.length) lines.push(`- Stale / do not follow blindly: ${facts.authority.stale.join(", ")}`)
+    lines.push("")
+  }
+  if (facts.evidence?.length) {
+    lines.push("## Evidence")
+    for (const e of facts.evidence) lines.push(`- ${e}`)
+    lines.push("")
+  }
+  lines.push("## What this document is not")
+  lines.push("- It is not a contract: only .opencode/goals/<slug>/goal.yaml is locked and verified.")
+  lines.push("- It is not consent: owner decisions still need their own exact review.")
+  lines.push("- If it disagrees with the contract, the contract wins and the disagreement is an owner question.")
+  const markdown = lines.join("\n")
+  const { now: _now, ...data } = facts
+  return { schema: "opencode-goal/handoff/v1", generatedAt, markdown, data }
+}
+
+/** The bounded block a kickoff tail carries. */
+export function handoffDigest(markdown: string, limit = HANDOFF_DIGEST_LIMIT): string {
+  const text = markdown.trim()
+  if (text.length <= limit) return text
+  return `${text.slice(0, limit - 200).trimEnd()}\n\n…(truncated; the full handoff is in this goal folder as handoff.md)`
+}

package/src/engine/interrupt-policy.ts

@@ -0,0 +1,45 @@
+// v0.8.0 — what a host restart does to a live run.
+//
+// The owner's policy: a restart is not an owner decision. If the contract on
+// disk is still the locked contract and the run's own state is intact, the run
+// resumes by itself. A changed contract, a divergent/repair-needed run or an
+// interrupted write is still a stop: those are exactly the cases where guessing
+// would resume work against bytes nobody approved.
+//
+// Pure: no filesystem, no clock, no OpenCode types. `app.ts` gathers the facts
+// and applies the decision; the unit suite pins every case.
+
+import type { Status } from "./state"
+
+export type RestartFacts = {
+  /** The status persisted before the restart. */
+  status: Status
+  /** The generation the run is bound to. */
+  lock: string
+  /** The lock computed from the contract currently on disk (undefined if unreadable). */
+  diskLock?: string
+  /** run.json parsed cleanly (no duplicate keys, no repair). */
+  runIntact: boolean
+  /** An amendment/launch journal says a write was in flight when the host died. */
+  interruptedWrite?: boolean
+}
+
+export type RestartDecision =
+  | { action: "resume"; reason: string }
+  | { action: "pause"; code: "not-intact" | "interrupted-write" | "contract-missing" | "diverged"; reason: string }
+  | { action: "none"; reason: string }
+
+/** Only an ACTIVE run can resume; a stopped one is the owner's to restart. */
+export function restartDecision(facts: RestartFacts): RestartDecision {
+  if (!["running", "waiting", "verifying"].includes(facts.status))
+    return { action: "none", reason: `the run was ${facts.status}; nothing to resume` }
+  if (!facts.runIntact)
+    return { action: "pause", code: "not-intact", reason: "run state was repaired from its ledger after a corrupt write; inspect it before resuming" }
+  if (facts.interruptedWrite)
+    return { action: "pause", code: "interrupted-write", reason: "a write was interrupted when the host stopped; the accepted generation is uncertain" }
+  if (!facts.diskLock)
+    return { action: "pause", code: "contract-missing", reason: "the locked contract could not be read from disk; resume would run against unknown bytes" }
+  if (facts.diskLock !== facts.lock)
+    return { action: "pause", code: "diverged", reason: `the contract on disk is generation ${facts.diskLock.slice(0, 12)}… but the run is locked to ${facts.lock.slice(0, 12)}…` }
+  return { action: "resume", reason: "the lock is unchanged and the run is intact" }
+}

package/src/engine/inventory.ts

@@ -0,0 +1,70 @@
+import { existsSync, readFileSync, statSync } from "node:fs"
+import { join } from "node:path"
+import type { Contract } from "../contract/types"
+import { parseContract } from "../contract/parse"
+import type { GoalSummary } from "../rpc"
+import { isActive, isTerminal, type RunState } from "./state"
+import { Store } from "./store"
+import { byPriorityThenRecency } from "./registry"
+import { launchView, type LaunchRequest } from "./launches"
+
+const readableRun = (value?: RunState): value is RunState => !!value && typeof value.slug === "string" && typeof value.runId === "string" && typeof value.lock === "string" && typeof value.sessionID === "string" && typeof value.status === "string" && !!value.criteria && typeof value.criteria === "object" && !Array.isArray(value.criteria) && !!value.steps && typeof value.steps === "object"
+
+/** Project-local, source-of-truth inventory. Archives are READ ONLY. The
+ * machine registry and CLEO task tree are not a substitute for goal folders. */
+export function projectInventory(store: Store, live: Iterable<RunState> = [], options: { detailsForKey?: string; launches?: LaunchRequest[] } = {}): GoalSummary[] {
+  const liveBySlug = new Map([...live].filter(readableRun).map((s) => [s.slug, s]))
+  const rows: GoalSummary[] = []
+  for (const archived of [false, true]) {
+    for (const slug of archived ? store.archivedSlugs() : store.slugs()) {
+      const dir = archived ? store.archivedPath(slug) : store.dir(slug)
+      const issues: string[] = []
+      let read: ReturnType<Store["readContract"]> = undefined
+      try { read = store.readContract(slug, { archived }) } catch { issues.push("Contract could not be read") }
+      for (const i of read?.issues ?? []) if (i.level === "error") issues.push(`${i.path}: ${i.message}`)
+      const saved = !archived ? liveBySlug.get(slug) ?? store.readRun(slug) : store.readRun(slug, { archived: true })
+      const run = readableRun(saved) ? saved : undefined
+      if (existsSync(join(dir, "run.json")) && !run) issues.push("Run state is unreadable; status/progress/session cannot be inferred")
+      let contract: Contract | undefined = read?.contract
+      // The locked generation, not an unaccepted disk edit, defines the
+      // started goal's title, oracle count, plan and relationship metadata.
+      if (run && read?.lock !== run.lock) {
+        contract = undefined
+        for (const name of [`contract-${run.lock}.yaml`, "contract.yaml"]) {
+          try {
+            const locked = parseContract(readFileSync(join(dir, "evidence", run.runId, name), "utf8"), { slug })
+            if (locked.contract && locked.lock === run.lock) { contract = locked.contract; break }
+          } catch { /* Try the original snapshot; never mutate history. */ }
+        }
+        issues.push("Disk contract differs from the locked generation")
+      }
+      const states = run ? Object.values(run.criteria).filter((c) => c && typeof c === "object") : []
+      const status = run?.status ?? (existsSync(join(dir, "run.json")) ? "unknown" : "draft")
+      const terminal = run ? isTerminal(run.status) : false
+      let updatedAt = run?.updatedAt ?? 0
+      if (!run) try { updatedAt = statSync(join(dir, "goal.yaml")).mtimeMs } catch { /* Unknown remains 0. */ }
+      const key = `${archived ? "archive" : "live"}:${slug}:${run?.runId ?? read?.lock ?? "invalid"}`
+      const launch = !archived ? options.launches?.filter((p) => p.slug === slug).sort((a, b) => Number(b.status === "executing") - Number(a.status === "executing") || b.createdAt - a.createdAt)[0] : undefined
+      rows.push({
+        key,
+        slug, title: run?.title ?? contract?.title ?? slug, status,
+        archived, terminal, attachable: !archived && !!run && !terminal && !isActive(run.status),
+        valid: !!contract && !issues.length, updatedAt,
+        proven: states.filter((c) => c.status === "pass").length,
+        total: run ? states.length : contract ? contract.criteria.length + contract.invariants.length : 0,
+        ...(run ? { sessionID: run.sessionID, runId: run.runId, lock: run.lock, turn: run.turn, ...(run.progress ? { progress: { ...run.progress } } : {}) } : read?.lock ? { lock: read.lock } : {}),
+        ...(run?.handoff ? { handoff: { ...run.handoff } } : {}),
+        ...(launch ? { launch: launchView(launch) } : {}),
+        ...(run?.priority ?? contract?.priority ? { priority: run?.priority ?? contract?.priority } : {}),
+        ...(contract ? { outcome: contract.outcome, meta: contract.meta, ...(contract.supersedes ? { supersedes: contract.supersedes } : {}), ...(contract.execution.agent ? { configuredAgent: contract.execution.agent } : {}), steps: contract.plan.map((s) => ({ id: s.id, title: s.title, status: run?.steps[s.id] ?? "pending" })) } : {}),
+        sessionState: run || existsSync(join(dir, "run.json")) ? "unknown" : "unassigned",
+        ...(issues.length ? { issues } : {}),
+        ...(options.detailsForKey === key && contract ? { details: { criteria: [...contract.criteria.map((c) => ({ ...c, invariant: false })), ...contract.invariants.map((c) => ({ ...c, invariant: true }))].map((c) => {
+          const state = run?.criteria[c.id]
+          return { id: c.id, statement: c.statement, essential: c.essential, invariant: c.invariant, kind: c.check.kind, status: state?.status ?? "unknown", ...(state?.by ? { by: state.by } : {}), ...(state?.detail ? { detail: state.detail } : {}) }
+        }), constraints: contract.constraints, nonGoals: contract.non_goals } } : {}),
+      })
+    }
+  }
+  return rows.sort(byPriorityThenRecency)
+}

package/src/engine/launches.ts

@@ -0,0 +1,82 @@
+import { OwnerReviewStore, processAlive, type ReviewRequest } from "./owner-reviews"
+export { processAlive } from "./owner-reviews"
+
+export type LaunchActivity = { phase: "starting" | "rehearsal" | "check"; since: number; detail: string; completed: number; total: number; checkId?: string }
+export type LaunchRequest = ReviewRequest & { fresh: boolean; activity?: LaunchActivity; updatedAt?: number; chatAdmissionMessageID?: string }
+/** Admission is not a run: expose the host receipt without inventing running state. */
+export type LaunchView = Pick<LaunchRequest, "slug" | "sessionID" | "lock" | "fresh" | "status" | "result" | "activity" | "updatedAt" | "expiresAt"> & { decisionId: string }
+export function launchView(p: LaunchRequest): LaunchView {
+  return { decisionId: p.id, slug: p.slug, sessionID: p.sessionID, lock: p.lock, fresh: p.fresh, status: p.status, expiresAt: p.expiresAt,
+    ...(p.result ? { result: p.result } : {}), ...(p.activity ? { activity: p.activity } : {}), updatedAt: p.updatedAt ?? p.createdAt }
+}
+export const launchChoices = [
+  { value: "launch", label: "Start goal now (Recommended)", description: "Launch exactly this validated contract in the displayed session mode." },
+  { value: "revise", label: "Revise this goal", description: "Return to the interview with changes; nothing launches." },
+  { value: "save", label: "Save for later", description: "Keep the validated draft; nothing launches." },
+] as const
+
+export class LaunchStore extends OwnerReviewStore<LaunchRequest> {
+  constructor(file: string) { super(file, launchChoices) }
+
+  /** Non-consenting admission pointer; actual persisted chat is checked later. */
+  noteChatAdmission(id: string, messageID?: string): LaunchRequest | undefined {
+    return this.mutate((data) => {
+      const request = data.requests[id]
+      if (!request || !["pending", "interrupted", "expired"].includes(request.status) || request.ownerMessageID
+        || request.issuerPID !== process.pid && processAlive(request.issuerPID)) return undefined
+      if (messageID) request.chatAdmissionMessageID = messageID
+      else delete request.chatAdmissionMessageID
+      return request
+    })
+  }
+
+  takeChatAdmission(id: string, messageID: string): boolean {
+    return this.mutate((data) => {
+      const request = data.requests[id]
+      if (!request || !["pending", "interrupted", "expired"].includes(request.status) || request.chatAdmissionMessageID !== messageID || request.ownerMessageID
+        || request.issuerPID !== process.pid && processAlive(request.issuerPID)) return false
+      delete request.chatAdmissionMessageID
+      return true
+    })
+  }
+
+  override update(id: string, change: Partial<Pick<ReviewRequest, "status" | "result" | "comment">>): LaunchRequest {
+    return this.mutate((data) => {
+      const p = data.requests[id]
+      if (!p) throw new Error("Unknown launch decision")
+      Object.assign(p, change)
+      p.updatedAt = Date.now()
+      if (p.status !== "executing") delete p.activity
+      return p
+    })
+  }
+
+  override reserve(id: string): LaunchRequest | undefined {
+    return this.mutate((data) => {
+      const p = data.requests[id]
+      if (!p || p.status !== "pending") return undefined
+      if (p.ownerMessageID && Object.values(data.requests).some((other) => other.id !== id && other.ownerMessageID === p.ownerMessageID && ["executing", "succeeded", "failed"].includes(other.status))) return undefined
+      if (p.expiresAt < Date.now()) { p.status = "expired"; return undefined }
+      if (p.issuerPID !== process.pid && processAlive(p.issuerPID)) return undefined
+      // Reserve the actual draft/session too: separate native reviews must
+      // not both rehearse or create fresh sessions for one admission.
+      if (Object.values(data.requests).some((other) => other.id !== id && other.status === "executing" && (other.slug === p.slug || other.sessionID === p.sessionID))) return undefined
+      p.status = "executing"
+      p.issuerPID = process.pid
+      p.updatedAt = Date.now()
+      return p
+    })
+  }
+
+  activity(id: string, activity?: LaunchActivity): LaunchRequest {
+    return this.mutate((data) => {
+      const p = data.requests[id]
+      if (!p) throw new Error("Unknown launch decision")
+      if (activity && p.status !== "executing") throw new Error("Launch admission is not executing")
+      p.updatedAt = Date.now()
+      if (activity) p.activity = activity
+      else delete p.activity
+      return p
+    })
+  }
+}

package/src/engine/loop-stop.ts

@@ -0,0 +1,50 @@
+// v0.8.0 — what still stops the loop.
+//
+// The owner's policy removes lifecycle prompts, not safety. A human criterion,
+// a real blocker and an outward/destructive act always stop and ask. Two more
+// stops are stated by the contract this project is run under (C6): a first visit
+// to a project the loop has never worked in, and an exhausted budget — unless the
+// contract says otherwise. Those two are the only stops an owner can waive, and
+// they are waived explicitly (`allowNewProjects`, `allowBudgetExhaustion`), never
+// by inference.
+//
+// Pure: the adapter gathers the facts, this decides.
+
+export type StopFacts = {
+  /** A `human` criterion is waiting for owner sign-off. */
+  humanCriterionPending?: boolean
+  /** A blocker was reported (missing credential/access/decision). */
+  blocker?: string
+  /** The next step would publish, deploy, merge, delete, spend or reveal secrets. */
+  outwardActRequired?: boolean
+  /** The source contract's budget is used up. */
+  budgetExhausted?: boolean
+  /** The contract explicitly allows continuing past its budget. */
+  allowBudgetExhaustion?: boolean
+  /** The project the candidate belongs to, when a candidate exists. */
+  candidateProject?: string
+  currentProject: string
+  /** Projects this loop has already worked in. */
+  visitedProjects?: string[]
+  /** The contract explicitly allows a first visit to a new project. */
+  allowNewProjects?: boolean
+}
+
+export type StopDecision =
+  | { stop: false }
+  | { stop: true; code: "human" | "blocker" | "outward" | "budget" | "new-project"; reason: string }
+
+export function loopStop(facts: StopFacts): StopDecision {
+  if (facts.humanCriterionPending)
+    return { stop: true, code: "human", reason: "a human criterion needs the owner's sign-off" }
+  if (facts.blocker)
+    return { stop: true, code: "blocker", reason: `a blocker needs the owner: ${facts.blocker}` }
+  if (facts.outwardActRequired)
+    return { stop: true, code: "outward", reason: "the next step is outward or destructive; the owner must authorize it" }
+  if (facts.budgetExhausted && !facts.allowBudgetExhaustion)
+    return { stop: true, code: "budget", reason: "the budget is exhausted and the contract does not allow continuing past it" }
+  if (facts.candidateProject && facts.candidateProject !== facts.currentProject
+    && !(facts.visitedProjects ?? []).includes(facts.candidateProject) && !facts.allowNewProjects)
+    return { stop: true, code: "new-project", reason: `the candidate is in a project this loop has never worked in: ${facts.candidateProject}` }
+  return { stop: false }
+}

package/src/engine/loop.ts

@@ -0,0 +1,109 @@
+// v0.6.0 - the loop's DECISION, extracted from the OpenCode adapter.
+//
+// `decide(state, signals, limits)` is PURE: no filesystem, no network, no
+// OpenCode types. The adapter calls it from `onTurnEnd` and maps the action onto
+// its existing calls (setStatus, ledger, decide dialog, admit/schedule); the `ocg
+// tick` entry point calls it and maps the action onto CLEO's tick contract. One
+// loop, many harnesses.
+//
+// Parity is the point: each action here corresponds to a branch the adapter
+// already took, and the TailKind of a continuation is the same one the adapter
+// already sent. `test/unit/loop-decision.test.ts` pins every case and
+// docs/research/harness-agnostic-loop-decision.md carries the parity table.
+
+import type { TailKind } from "../contract/render"
+import type { RunState, Status } from "./state"
+
+/** How the harness reported the turn ending. */
+export type LoopTurn = "succeeded" | "failed" | "interrupted"
+
+/** The owner-set and host-set bounds the decision reads (never hard-coded here). */
+export type LoopLimits = {
+  blockerRepeats: number
+  stallTurns: number
+  recoveryAt: number
+  backstopTurns: number
+}
+
+/** Everything the decision needs, gathered by the caller (all pure data). */
+export type LoopSignals = {
+  turn: LoopTurn
+  /** The kind of continuation the host had pending for this turn, if any. */
+  pending?: TailKind
+  /** Host-visible repository change since the last turn. */
+  changed: boolean
+  /** The agent recorded progress with the progress tool this turn. */
+  progressRecorded: boolean
+  /** A plan step changed state this turn. */
+  stepsChanged: boolean
+  /** A stalled run whose recent turns showed host-visible activity. */
+  activeStalled: boolean
+  /** The reason text for a stall (already formatted by the adapter). */
+  stallReason: string
+  /** The owner-set stall policy from the contract. */
+  onStall: "pause" | "continue"
+  /** Budget consumed, 0..1+ (the adapter computes it). */
+  budgetRatio: number
+  /** No contract budget, and the backstop turn count was reached. */
+  backstop: boolean
+  /** The adapter's cooldown between scheduled continuations. */
+  cooldownMs: number
+  now?: number
+}
+
+/** What the loop decided to do next. */
+export type LoopAction =
+  | { kind: "none" }
+  | { kind: "verify" }
+  | { kind: "admit"; tail: TailKind }
+  | { kind: "schedule"; tail: TailKind; delayMs: number; waiting?: { reason: string } }
+  | { kind: "stop"; status: Status; code: "blocked" | "stalled" | "budget" | "wrapup"; reason: string }
+
+/**
+ * The one decision. Ordering mirrors the adapter exactly:
+ * claim -> kickoff -> wrap-up done -> blocked -> budget/backstop -> stall ->
+ * wait -> continue (recovery when progress has been missing long enough).
+ */
+export function decide(state: RunState, signals: LoopSignals, limits: LoopLimits): LoopAction {
+  // A failed or interrupted turn is the adapter's failure path, not this one.
+  if (signals.turn !== "succeeded") return { kind: "none" }
+  // Only a running run continues; a WAITING run continues only because it claimed.
+  if (state.status !== "running" && !(state.status === "waiting" && state.claim)) return { kind: "none" }
+  if (state.claim) return { kind: "verify" }
+  if (state.turn === 0) return { kind: "admit", tail: "kickoff" }
+  if (signals.pending === "wrapup")
+    return { kind: "stop", status: "budget_limited", code: "wrapup", reason: "budget used; wrap-up turn done" }
+  if (state.blocker && state.blocker.count >= limits.blockerRepeats)
+    return { kind: "stop", status: "blocked", code: "blocked", reason: `${state.blocker.key}: ${state.blocker.reason}` }
+  if (signals.budgetRatio >= 1 || signals.backstop) {
+    // One wrap-up turn is admitted before the run stops for the owner.
+    if (!state.wrapup) return { kind: "admit", tail: "wrapup" }
+    return { kind: "stop", status: "budget_limited", code: "budget", reason: signals.backstop ? `backstop of ${limits.backstopTurns} turns reached` : "budget used" }
+  }
+  if (state.counters.noProgress >= limits.stallTurns) {
+    // Owner-set policy: a genuinely stalled-but-active run may continue with a
+    // recorded report instead of pausing. Idle runs and the default still stop.
+    if (signals.activeStalled && signals.onStall === "continue")
+      return { kind: "schedule", tail: "continue", delayMs: signals.cooldownMs }
+    return { kind: "stop", status: "paused", code: "stalled", reason: signals.stallReason }
+  }
+  const now = signals.now ?? Date.now()
+  if (state.wait && state.wait.until > now)
+    return { kind: "schedule", tail: "continue", delayMs: state.wait.until - now, waiting: { reason: state.wait.reason } }
+  return { kind: "schedule", tail: state.counters.noProgress >= limits.recoveryAt ? "recovery" : "continue", delayMs: signals.cooldownMs }
+}
+
+/**
+ * The continuation text this action produces, as the OpenCode adapter would send
+ * it. `null` means the loop is not sending a continuation for this action (it is
+ * verifying or stopping), which is what the tick reports as `{"final":false}`.
+ */
+export function continuationTail(action: LoopAction): TailKind | null {
+  switch (action.kind) {
+    case "admit":
+    case "schedule":
+      return action.tail
+    default:
+      return null
+  }
+}

package/src/engine/next-work.ts

@@ -0,0 +1,82 @@
+// v0.8.0 — what the loop does after a goal completes.
+//
+// Sources, in order (the design note states this too):
+//   1. a ready CLEO item in THIS project — the owner's own task board;
+//   2. work offered by a peer over AgentMBX (a reply to our availability notice);
+//   3. nothing — go idle and announce availability (rate-limited).
+//
+// A candidate is a proposal, never consent: the stop rules are evaluated for
+// every candidate before it can be started, and the adapter records what it
+// started. Pure so the host is not needed to test the decision.
+
+import { loopStop, type StopDecision } from "./loop-stop"
+import { announceDue, type AnnounceState } from "./peer-announce"
+
+export type WorkCandidate = {
+  source: "cleo" | "peer"
+  /** Project identity the work belongs to (absolute path or project id). */
+  project: string
+  taskId?: string
+  title: string
+  acceptance?: string[]
+  /** Peer identity, for peer candidates. */
+  from?: string
+  messageId?: string
+  at?: number
+}
+
+export type NextWorkInput = {
+  candidates: WorkCandidate[]
+  currentProject: string
+  visitedProjects?: string[]
+  /** Safety stops, evaluated before any candidate. */
+  humanCriterionPending?: boolean
+  blocker?: string
+  outwardActRequired?: boolean
+  /** Per-candidate limits from the source contract. */
+  budgetExhausted?: boolean
+  allowBudgetExhaustion?: boolean
+  allowNewProjects?: boolean
+  announce: AnnounceState
+  now: number
+  cooldownMs: number
+}
+
+export type NextWorkDecision =
+  | { kind: "start"; candidate: WorkCandidate }
+  | { kind: "announce" }
+  | { kind: "hold"; reason: "outstanding" | "cooldown" | "no-work" }
+  | { kind: "stop"; code: Extract<StopDecision, { stop: true }>["code"]; reason: string }
+
+export function nextWork(input: NextWorkInput): NextWorkDecision {
+  // The three stops no policy may waive.
+  const safety = loopStop({
+    ...(input.humanCriterionPending ? { humanCriterionPending: true } : {}),
+    ...(input.blocker ? { blocker: input.blocker } : {}),
+    ...(input.outwardActRequired ? { outwardActRequired: true } : {}),
+    currentProject: input.currentProject,
+  })
+  if (safety.stop) return { kind: "stop", code: safety.code, reason: safety.reason }
+
+  // CLEO first, then peers. The caller supplies each source already ordered.
+  const ordered = [...input.candidates].sort((a, b) => (a.source === b.source ? 0 : a.source === "cleo" ? -1 : 1))
+  for (const candidate of ordered) {
+    const stop = loopStop({
+      ...(input.humanCriterionPending ? { humanCriterionPending: true } : {}),
+      ...(input.blocker ? { blocker: input.blocker } : {}),
+      ...(input.outwardActRequired ? { outwardActRequired: true } : {}),
+      ...(input.budgetExhausted ? { budgetExhausted: true } : {}),
+      ...(input.allowBudgetExhaustion ? { allowBudgetExhaustion: true } : {}),
+      ...(input.allowNewProjects ? { allowNewProjects: true } : {}),
+      candidateProject: candidate.project,
+      currentProject: input.currentProject,
+      ...(input.visitedProjects ? { visitedProjects: input.visitedProjects } : {}),
+    })
+    if (stop.stop) return { kind: "stop", code: stop.code, reason: stop.reason }
+    return { kind: "start", candidate }
+  }
+
+  const announce = announceDue(input.announce, input.now, input.cooldownMs)
+  if (announce.due) return { kind: "announce" }
+  return { kind: "hold", reason: announce.reason }
+}

package/src/engine/owner-intent.ts

@@ -0,0 +1,71 @@
+/** Bounded owner-command spellings, not an NLP interpreter. The agent still
+ * selects a typed action/target. Tool-supplied text is never consent: this
+ * message must be fetched from the host's own session history. */
+export function explicitResume(text: string): boolean {
+  const value = text.trim()
+  if (/\b(?:do not|don't|not|never)\s+(?:resume|continue)\b|\b(?:if|when|unless|until)\b/i.test(value)) return false
+  return /^(?:please\s+)?(?:resume|continue)[.!]?$/i.test(value)
+    || /^(?:please\s+)?(?:resume|continue)\s+(?:(?:the|my|your)\s+)?goal[.!]?$/i.test(value)
+    || /^I (?:approve|authorize) you to resume[.!](?:\s|$)/i.test(value)
+}
+
+export function ownerResumeMessage(messages: readonly any[], generationAt: number, review?: { createdAt: number; expiresAt: number; expiryPolicy?: "time" | "target" }) {
+  for (const message of [...messages].reverse()) {
+    if (message?.type !== "user" || message.metadata?.goal) continue
+    if (typeof message.id !== "string" || typeof message.text !== "string" || typeof message.time?.created !== "number") return undefined
+    if (message.time.created < generationAt) return undefined
+    const text = message.text.trim()
+    // Steering/questions and background synthetics do not revoke the owner's
+    // existing directive. A later stop, contradiction or conditional does.
+    if (/^(?:cancel|stop|pause|abort|reject)\b|\b(?:do not|don't|never)\s+(?:resume|continue)\b|\b(?:withdraw|revoke)\b.*\b(?:approval|consent)\b/i.test(text)
+      || /^(?:resume|continue)\b.*\b(?:if|when|unless|until)\b/i.test(text)) return undefined
+    // Caller must still match the exact live target; elapsed time alone is
+    // not a revocation of a target-bound lifecycle question.
+    const acceptsReview = review && message.time.created >= review.createdAt && (review.expiryPolicy === "target" || message.time.created <= review.expiresAt)
+      && /^(?:I\s+)?(?:accept|approve)[.!]?$/i.test(text)
+    if (explicitResume(text) || acceptsReview) return { id: message.id, text: message.text, createdAt: message.time.created }
+  }
+}
+
+/** A typed amendment action still needs the host's actual latest owner
+ * message. Quoted/design/conditional text and old replies are not consent. */
+export function ownerAmendmentMessage(messages: readonly any[], review: { createdAt: number; expiresAt: number; expiryPolicy?: "time" | "target" }, action: "accept" | "reject" | "comment") {
+  const message = [...messages].reverse().find((m) => m?.type === "user" && !m.metadata?.goal)
+  if (!message || typeof message.id !== "string" || typeof message.text !== "string" || typeof message.time?.created !== "number"
+    || message.time.created < review.createdAt || review.expiryPolicy !== "target" && message.time.created > review.expiresAt) return undefined
+  const value = message.text.trim()
+  if (!value || action !== "comment" && /["“”`]|\b(?:if|when|unless|until|do not|don't|never|not yet)\b/i.test(value)) return undefined
+  const subject = "(?:\\s+(?:(?:this|that|the)\\s+)?(?:amendment|ammendment|proposal|review|change|it))?"
+  const continuation = "(?:[,.]?\\s+(?:(?:and|then)\\s+)?(?:please\\s+)?(?:resume(?:\\s+(?:the\\s+)?goal)?|continue(?:\\s+(?:the\\s+)?goal)?|get\\s+it\\s+done|finish\\s+(?:it|the\\s+goal)))?"
+  const accepting = new RegExp(`^(?:(?:yes|okay|ok)[,.]?\\s+)?(?:please\\s+)?(?:I\\s+)?(?:accept|approve)${subject}(?:\\s+now)?${continuation}[.!]?$`, "i").test(value)
+  const rejecting = new RegExp(`^(?:please\\s+)?(?:I\\s+)?(?:reject|decline)${subject}[.!]?$`, "i").test(value)
+  if (action === "accept" && !accepting || action === "reject" && !rejecting || action === "comment" && (accepting || rejecting)) return undefined
+  return { id: message.id, text: message.text, createdAt: message.time.created,
+    explicitAmendment: /\b(?:amendment|ammendment)\b/i.test(value),
+    continueGoal: accepting && /\b(?:resume|continue|finish|get\s+it\s+done)\b/i.test(value) }
+}
+
+/** A new explicit chat directive authorizes the last actually displayed
+ * contract, not an expired form answer or a worker-supplied consent string. */
+export function ownerLaunchMessage(messages: readonly unknown[], displayed: readonly { id: string; slug: string; lock: string; fresh: boolean; at: number }[], target: { slug: string; lock: string; fresh: boolean }) {
+  const latest = [...displayed].sort((a, b) => b.at - a.at)[0]
+  if (!latest || latest.slug !== target.slug || latest.lock !== target.lock || latest.fresh !== target.fresh) return undefined
+  for (const value of [...messages].reverse()) {
+    if (!value || typeof value !== "object") continue
+    const message = value as { type?: unknown; id?: unknown; text?: unknown; time?: { created?: unknown }; metadata?: { goal?: unknown } }
+    if (message.type !== "user" || message.metadata?.goal) continue
+    if (typeof message.id !== "string" || typeof message.text !== "string" || typeof message.time?.created !== "number") return undefined
+    const text = message.text.trim()
+    if (/^(?:cancel|stop|pause|abort|reject)\b|\b(?:do not|don't|never)\s+(?:start|launch|resume|continue)\b|\b(?:withdraw|revoke)\b.*\b(?:approval|consent)\b/i.test(text)) return undefined
+    if (/\b(?:start|launch|resume|continue)\b.*\b(?:if|when|unless|until)\b/i.test(text)) return undefined
+    if (/["“”`]|\b(?:if|when|unless|until|not yet)\b/i.test(text)) continue
+    const explicit = /^(?:please\s+)?(?:start|launch)\s+(?:(?:the|this|my|your)\s+)?(?:goal|plan)(?:\s+now)?[.!]?$/i.test(text)
+      || /^(?:please\s+)?continue\s+(?:(?:the|my|your)\s+)?goal[.!]?$/i.test(text)
+      || /^Just go ahead and start the plan[.!]\s*I approve[.!]?$/i.test(text)
+    if (!explicit) continue
+    const at = message.time.created
+    const review = displayed.filter((p) => p.at <= at).sort((a, b) => b.at - a.at)[0]
+    if (!review || review.slug !== target.slug || review.lock !== target.lock || review.fresh !== target.fresh) return undefined
+    return { id: message.id, text: message.text, createdAt: message.time.created, reviewId: review.id }
+  }
+}