@cleocode/goal 0.0.0-stage → 0.9.2

package/src/tui/manager.ts

@@ -0,0 +1,94 @@
+import type { GoalSummary, GoalTarget, LaunchView, ManageAction } from "../rpc"
+import { priorityWeight } from "../contract/types"
+import type { Tone } from "./format"
+
+const terminal = new Set(["complete", "failed", "aborted", "superseded"])
+export const goalKey = (goal: GoalSummary) => goal.key ?? `${goal.archived ? "archive" : "live"}:${goal.slug}:${goal.runId ?? "draft"}`
+const graphemes = new Intl.Segmenter(undefined, { granularity: "grapheme" })
+const columns = (text: string) => Bun.stringWidth(text, { ambiguousIsNarrow: false })
+
+/** Column-fit, not UTF-16-length-fit. Don't split combining characters or
+ * emoji sequences; full labels remain available in the manager details. */
+export function fitColumns(text: string, width: number): string {
+  const flat = text.replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "").replace(/[\u0000-\u001f\u007f-\u009f]/g, " ").replace(/\s+/g, " ").trim()
+  const limit = Math.max(1, Math.floor(width))
+  if (columns(flat) <= limit) return flat
+  const suffix = columns("…") <= limit ? "…" : "."
+  let out = ""
+  for (const { segment } of graphemes.segment(flat)) {
+    if (columns(out + segment + suffix) > limit) break
+    out += segment
+  }
+  return out + suffix
+}
+
+export const targetOf = (goal: GoalSummary): GoalTarget => ({ key: goalKey(goal), lock: goal.lock ?? "", ...(goal.runId ? { runId: goal.runId } : {}), ...(goal.sessionID ? { sessionID: goal.sessionID } : {}) })
+
+/** Admission is visible progress, not a fabricated running/proven state. */
+export function launchStatusText(launch?: LaunchView, current?: Pick<GoalSummary, "slug" | "sessionID" | "lock" | "runId" | "status"> | null): string | undefined {
+  if (!launch || launch.status === "succeeded") return undefined
+  if (current?.runId && current.sessionID === launch.sessionID && current.slug === launch.slug && current.lock === launch.lock && !terminal.has(current.status))
+    return `Goal ${current.slug} · ${current.status} · last launch attempt ${launch.status}; existing run unchanged`
+  if (launch.status === "executing") return `Starting ${launch.slug} · ${launch.activity?.detail ?? "owner-approved admission"} · no run yet`
+  if (launch.status === "pending" || launch.status === "interrupted") return `Launch review ${launch.slug} · pending in Composer · nothing started`
+  return `Launch ${launch.slug} · ${launch.status} · ${launch.result ?? "nothing started; inspect the review"}`
+}
+export type ManagerAction = { label: string; description: string; action: ManageAction | "jump" | "back" }
+export function managerActions(goal: GoalSummary, actorSessionID: string, actorHasGoal: boolean): ManagerAction[] {
+  const rows: ManagerAction[] = []
+  if (goal.sessionID && goal.sessionState === "present") rows.push({ label: "Open goal session", description: "Deliberately jump after viewing these details", action: "jump" })
+  if (goal.valid !== false && !goal.archived && goal.runId) {
+    if (["running", "waiting", "verifying"].includes(goal.status)) rows.push({ label: "Pause selected goal", description: "Stop only this goal's loop", action: "pause" })
+    if (["paused", "blocked", "needs_review"].includes(goal.status)) rows.push({ label: "Resume selected goal", description: "Continue this stopped run", action: "resume" })
+    if (!terminal.has(goal.status) && goal.status !== "verifying") rows.push({ label: "Verify selected goal", description: "Run its declared host checks and verifier", action: "verify" })
+    if (goal.attachable && !actorHasGoal && goal.sessionID !== actorSessionID) rows.push({ label: "Attach selected goal here", description: "Move its ownership; preserve history and progress", action: "attach" })
+    if (!terminal.has(goal.status)) rows.push({ label: "Abort selected goal", description: "Requires a native confirmation; preserves history", action: "abort" })
+    else rows.push({ label: "Archive selected goal", description: "Requires a native confirmation; preserves history", action: "archive" })
+  }
+  rows.push({ label: "Back to all goals", description: "Collapse details without changing sessions", action: "back" })
+  return rows
+}
+
+export function wrapColumns(text: string, width: number): string[] {
+  const limit = Math.max(2, Math.floor(width))
+  const result: string[] = []
+  for (const line of text.split("\n")) {
+    let out = ""
+    for (const { segment } of graphemes.segment(line)) {
+      if (out && columns(out + segment) > limit) { result.push(out); out = "" }
+      out += segment
+    }
+    result.push(out)
+  }
+  return result
+}
+
+/** Current first, then the declared priority/recency order. Never sort or
+ * mutate the server's inventory in place, or manufacture a task hierarchy. */
+export function orderedGoals(goals: readonly GoalSummary[], sessionID: string): GoalSummary[] {
+  const here = (g: GoalSummary) => !g.archived ? g.sessionID === sessionID ? 2 : g.handoff?.fromSessionID === sessionID || !g.runId && g.launch?.sessionID === sessionID ? 1 : 0 : 0
+  return [...goals].sort((a, b) => here(b) - here(a) || priorityWeight(b.priority) - priorityWeight(a.priority) || (b.updatedAt ?? 0) - (a.updatedAt ?? 0))
+}
+
+export function sidebarCards(goals: readonly GoalSummary[], sessionID: string, width = 40, maxLines = 12) {
+  const active = orderedGoals(goals.filter((g) => !g.archived && !g.terminal && !terminal.has(g.status)), sessionID)
+  // Header + (one gap, two selectable lines, progress, optional handoff
+  // slug/session pointer) per card; reserve for the largest card shape.
+  // reserve a final SELECTABLE manager pointer whenever anything overflows.
+  const capacity = Math.max(1, Math.floor((maxLines - 2) / 5))
+  const visible = active.slice(0, capacity)
+  return {
+    total: active.length, hidden: Math.max(0, active.length - visible.length),
+    cards: visible.map((goal) => {
+      const here = goal.sessionID === sessionID
+      const where = !goal.sessionID ? goal.launch?.sessionID === sessionID ? "author here" : "draft" : here ? "here" : "elsewhere"
+      const tone: Tone = goal.status === "blocked" ? "error" : ["running", "waiting", "verifying"].includes(goal.status) ? "success" : "warning"
+      const steps = goal.steps ?? []
+      const plan = steps.length ? `${steps.filter((s) => s.status === "done").length}/${steps.length} plan · ` : ""
+      const handoffPointer = goal.handoff?.fromSessionID === sessionID && goal.sessionID
+        ? `${fitColumns(goal.slug, Math.max(1, width - 17))} · ses…${goal.sessionID.slice(-8)}` : undefined
+      return { key: goalKey(goal), goal, tone, title: fitColumns(goal.title, Math.max(1, width - 2)), description: fitColumns(`${goal.status}${goal.launch?.status === "executing" ? " · starting" : goal.launch?.status === "expired" ? " · review expired" : ""} · ${where}`, Math.max(1, width - 2)), progress: fitColumns(`${goal.handoff?.fromSessionID === sessionID ? "from here · " : ""}${plan}${goal.proven}/${goal.total} proven · ${goal.agent ?? "agent unknown"}`, width), handoffPointer: handoffPointer ? fitColumns(handoffPointer, width) : undefined }
+    }),
+    pointer: fitColumns(active.length > visible.length ? `+${active.length - visible.length} ${active.length - visible.length === 1 ? "goal" : "goals"} — F9 manager` : "F9 goals manager", width),
+  }
+}

package/src/tui/navigation.ts

@@ -0,0 +1,11 @@
+import type { Plugin } from "@opencode/plugin/tui"
+
+/** Explicit navigation only. Selection/expansion must never call this. V2
+ * opens without focus, then focuses by SESSION id; no invented tab IDs. */
+export function openGoalSession(ui: Plugin.Context["ui"], sessionID: string): "tab" | "route" {
+  try {
+    if (ui.tabs?.enabled() && ui.tabs.open(sessionID) && ui.tabs.focus(sessionID)) return "tab"
+  } catch { /* Disabled/unavailable tabs use the verified router fallback. */ }
+  ui.router.navigate({ type: "session", sessionID })
+  return "route"
+}

package/src/tui/pointer-select.ts

@@ -0,0 +1,20 @@
+import type { MouseEvent, SelectRenderable } from "@opentui/core"
+
+/** OpenTUI 0.5.14 Select is keyboard-only. Add pointer activation for our
+ * plain one/two-line rows, retaining its real selection and keyboard path.
+ * Its visible slice is centered on the selected index; derive that slice
+ * from public geometry rather than accessing private scrollOffset. */
+export function pointerSelect(control: SelectRenderable, event: MouseEvent, rowHeight: 1 | 2): void {
+  if (event.button !== 0 || event.isDragging) return
+  const row = Math.floor((event.y - control.y) / rowHeight)
+  const visible = Math.max(1, Math.floor(control.height / rowHeight))
+  if (row < 0 || row >= visible || event.x < control.x || event.x >= control.x + control.width) return
+  const first = Math.max(0, Math.min(control.getSelectedIndex() - Math.floor(visible / 2), control.options.length - visible))
+  const index = first + row
+  if (index >= control.options.length) return
+  event.stopPropagation()
+  event.preventDefault()
+  control.focus()
+  control.setSelectedIndex(index)
+  control.selectCurrent()
+}

package/src/tui/tracer.ts

@@ -0,0 +1,51 @@
+// T053 — the live activity tracer. A pure formatter that renders what the
+// engine is doing RIGHT NOW with elapsed time and countdowns — verifying,
+// the verifier child running, goal_wait countdowns, turn cooldowns — for
+// the composer-top slot and the panel. Fed by the view's activity field
+// (updated on every persist); zero model cost. Snapshot-tested so the
+// wording cannot drift silently.
+import type { GoalView } from "../rpc"
+import { fit, fmtDuration, type Line, type Tone } from "./format"
+
+const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]
+
+/** Countdowns keep their seconds — "2m 10s", not "2m" — while the clock ticks. */
+export const fmtCountdown = (ms: number) => {
+  const s = Math.max(0, Math.ceil(ms / 1000))
+  if (s < 60) return `${s}s`
+  const m = Math.floor(s / 60)
+  return `${m}m ${String(s % 60).padStart(2, "0")}s`
+}
+
+export type TracerTone = Tone
+
+/** The animated frame for a running activity (ticks once per second via the TUI clock). */
+export const spinFrame = (now: number) => SPINNER[Math.floor(now / 120) % SPINNER.length]!
+
+export function tracerLines(view: GoalView, now: number, width = 40): Line[] {
+  const a = view.activity
+  // a tracer only shows while the engine is actively working — never a stale
+  // line on stopped or terminal statuses
+  if (!["running", "waiting", "verifying"].includes(view.status)) return []
+  if (!a) {
+    // active statuses without a recorded activity still deserve a pulse
+    return [{ text: fit(`◎ goal ${view.status} · turn ${view.turn}`, width), tone: "muted" }]
+  }
+  const elapsed = Math.max(0, Math.floor((now - a.since) / 1000))
+  const elapsedText = `${fmtDuration(elapsed * 1000)}`
+  const left = a.until ? Math.max(0, a.until - now) : undefined
+  const leftText = left !== undefined ? fmtCountdown(left) : undefined
+  switch (a.kind) {
+    case "verifier-child":
+      return [{ text: fit(`${spinFrame(now)} verifier child running — ${elapsedText}${a.detail ? ` · ${a.detail}` : ""}`, width), tone: "info" }]
+    case "verifying":
+      return [{ text: fit(`${spinFrame(now)} verifying the claim — ${elapsedText}${a.detail ? ` · ${a.detail}` : " (host checks, then the verifier child)"}`, width), tone: "info" }]
+    case "waiting":
+      return [{ text: fit(`◷ waiting — ${leftText ?? elapsedText}${left !== undefined ? " left" : ""}${a.detail ? ` · ${a.detail}` : ""}`, width), tone: "info" }]
+    case "cooldown":
+      return [{ text: fit(`· cooldown — next turn in ${leftText ?? "…"}`, width), tone: "muted" }]
+    case "turn":
+    default:
+      return [{ text: fit(`${spinFrame(now)} turn ${view.turn} in progress — ${elapsedText}${a.detail ? ` · ${a.detail}` : ""}`, width), tone: "success" }]
+  }
+}

package/src/util/git.ts

@@ -0,0 +1,102 @@
+// Worktree fingerprints: progress is measured by authoritative state change,
+// not by how much the model talked.
+import { spawnSync } from "node:child_process"
+import { createHash } from "node:crypto"
+import { statSync } from "node:fs"
+
+const GOAL_STATE = ":(exclude).opencode/goals"
+
+function git(cwd: string, args: string[]): { ok: boolean; out: string } {
+  // node:child_process so the bin also runs on plain Node (Bun implements it too).
+  const result = spawnSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 64 * 1024 * 1024 })
+  return { ok: result.status === 0, out: result.stdout ?? "" }
+}
+
+export const isRepo = (cwd: string) => git(cwd, ["rev-parse", "--is-inside-work-tree"]).out.trim() === "true"
+
+/** T100: the working-tree root for `cwd` (the linked worktree's own root when
+ *  cwd is inside one). Used to require a bound workspace to BE a work-tree root
+ *  rather than any subdirectory of the project. */
+export const topLevel = (cwd: string): string | undefined => {
+  const r = git(cwd, ["rev-parse", "--show-toplevel"])
+  return r.ok ? r.out.trim() : undefined
+}
+
+export const headCommit = (cwd: string): string | undefined => {
+  const r = git(cwd, ["rev-parse", "HEAD"])
+  return r.ok ? r.out.trim() : undefined
+}
+
+/** T116: linked worktrees live under the project but their commits are invisible
+ * to the root worktree's diff, so the last goal run recorded changed:false and
+ * tripped the stall auto-pause three times. `git worktree list --porcelain`
+ * names every worktree's HEAD and branch; a commit in any of them changes it. */
+export function worktreeSignature(cwd: string): string {
+  return git(cwd, ["worktree", "list", "--porcelain"])
+    .out.split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .join("\n")
+}
+
+/** Hash of HEAD + staged/unstaged diff + untracked file list + linked-worktree HEADs, excluding goal state. */
+export function fingerprint(cwd: string): string | undefined {
+  if (!isRepo(cwd)) return undefined
+  const head = git(cwd, ["rev-parse", "HEAD"]).out
+  const diff = git(cwd, ["diff", "HEAD", "--no-color", "--", ".", GOAL_STATE]).out
+  const untracked = git(cwd, ["ls-files", "--others", "--exclude-standard", "--", ".", GOAL_STATE]).out
+  const contents = untracked
+    .split("\n")
+    .filter(Boolean)
+    .slice(0, 500)
+    .map((file) => {
+      try {
+        const stat = statSync(`${cwd}/${file}`)
+        return `${file}:${stat.size}:${Math.trunc(stat.mtimeMs)}`
+      } catch {
+        return file
+      }
+    })
+  return createHash("sha256").update(head).update(diff).update(contents.join("\n")).update(worktreeSignature(cwd)).digest("hex").slice(0, 20)
+}
+
+/** T109: a bounded, host-computed git history digest. The verifier child has only
+ * read/glob/grep (no shell), so a criterion that asks about commit history was
+ * unanswerable and burned the round budget. The host supplies this text; the
+ * verifier judges from it and from the copy the host saves under evidence/. */
+export function gitDigest(cwd: string, limit = 20): string {
+  if (!isRepo(cwd)) return "(not a git repository)"
+  const head = git(cwd, ["rev-parse", "HEAD"]).out.trim()
+  const branch = git(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]).out.trim()
+  const log = git(cwd, ["log", "-n", String(limit), "--no-color", "--pretty=format:%h %ad %s", "--date=short"]).out.trim()
+  const trees = worktreeSignature(cwd)
+  return [`HEAD ${head}`, `branch ${branch}`, log, trees ? `linked worktrees:\n${trees}` : ""].filter(Boolean).join("\n")
+}
+
+/** Files changed relative to `base` (committed, staged, unstaged and untracked). */
+export function changedSince(cwd: string, base: string | undefined): string[] {
+  if (!isRepo(cwd)) return []
+  const files = new Set<string>()
+  if (base) for (const f of git(cwd, ["diff", "--name-only", base, "--", ".", GOAL_STATE]).out.split("\n")) if (f) files.add(f)
+  for (const f of git(cwd, ["diff", "--name-only", "HEAD", "--", ".", GOAL_STATE]).out.split("\n")) if (f) files.add(f)
+  for (const f of git(cwd, ["ls-files", "--others", "--exclude-standard", "--", ".", GOAL_STATE]).out.split("\n")) if (f) files.add(f)
+  return [...files].sort()
+}
+
+/** Minimal glob → RegExp (supports **, *, ?). */
+export function globToRegExp(glob: string): RegExp {
+  let re = ""
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i]!
+    if (c === "*") {
+      if (glob[i + 1] === "*") {
+        re += glob[i + 2] === "/" ? "(?:.*/)?" : ".*"
+        i += glob[i + 2] === "/" ? 2 : 1
+      } else re += "[^/]*"
+    } else if (c === "?") re += "[^/]"
+    else re += c.replace(/[.+^${}()|[\]\\]/g, "\\$&")
+  }
+  return new RegExp(`^${re}$`)
+}
+
+export const matchesAny = (file: string, globs: string[]) => globs.some((g) => globToRegExp(g.replace(/^\.\//, "")).test(file))

package/src/util/ids.ts

@@ -0,0 +1,20 @@
+// Message ids in OpenCode 2's native ascending format (12 hex chars of
+// timestamp*4096+counter, then 14 base62 chars), so continuation prompts sort
+// correctly in session history. Mirrors @opencode/schema identifier.ts.
+const CHARS = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
+let lastTimestamp = 0
+let counter = 0
+
+export function ascendingId(prefix: string, timestamp = Date.now()): string {
+  if (timestamp !== lastTimestamp) {
+    lastTimestamp = timestamp
+    counter = 0
+  }
+  counter++
+  const value = BigInt(timestamp) * 0x1000n + BigInt(counter)
+  const time = Array.from({ length: 6 }, (_, i) => Number((value >> BigInt(40 - 8 * i)) & 0xffn).toString(16).padStart(2, "0")).join("")
+  const bytes = crypto.getRandomValues(new Uint8Array(14))
+  return `${prefix}_${time}${Array.from(bytes, (b) => CHARS[b % 62]).join("")}`
+}
+
+export const runId = () => ascendingId("run").slice(4, 16)

package/src/util/shell.ts

@@ -0,0 +1,42 @@
+// Runs owner-declared check commands in the owner's login shell, so PATH and
+// toolchains match their terminal rather than the background service.
+import { spawn } from "node:child_process"
+
+export type ShellResult = { exit: number; stdout: string; stderr: string; timedOut: boolean; ms: number }
+
+const LIMIT = 64 * 1024
+
+/** Keep head and tail of oversized output so a runaway log never floods the verdict. */
+const clip = (out: string) =>
+  out.length > LIMIT ? `${out.slice(0, LIMIT / 4)}\n…[truncated ${out.length - LIMIT / 2} chars]…\n${out.slice(-LIMIT / 4)}` : out
+
+export async function runShell(command: string, cwd: string, timeoutSeconds = 300, extraEnv: Record<string, string> = {}): Promise<ShellResult> {
+  const shell = process.env.SHELL && process.env.SHELL.startsWith("/") ? process.env.SHELL : "/bin/sh"
+  const started = Date.now()
+  // node:child_process so the bin also runs on plain Node (Bun implements it too).
+  const child = spawn(shell, ["-lc", command], { cwd, stdio: ["ignore", "pipe", "pipe"], env: { ...process.env, ...extraEnv, CI: process.env.CI ?? "1" } })
+  let stdout = ""
+  let stderr = ""
+  child.stdout.setEncoding("utf8").on("data", (chunk: string) => {
+    if (stdout.length < LIMIT * 2) stdout += chunk
+  })
+  child.stderr.setEncoding("utf8").on("data", (chunk: string) => {
+    if (stderr.length < LIMIT * 2) stderr += chunk
+  })
+  let timedOut = false
+  const timer = setTimeout(() => {
+    timedOut = true
+    child.kill("SIGKILL")
+  }, Math.max(1, timeoutSeconds) * 1000)
+  const exit = await new Promise<number>((resolve) => {
+    child.on("error", () => resolve(127))
+    child.on("close", (code, signal) => resolve(code ?? (signal ? 128 : 1)))
+  })
+  clearTimeout(timer)
+  return { exit: timedOut ? 124 : exit, stdout: clip(stdout), stderr: clip(stderr), timedOut, ms: Date.now() - started }
+}
+
+export const tail = (text: string, lines = 12, chars = 1200) => {
+  const t = text.trimEnd().split("\n").slice(-lines).join("\n")
+  return t.length > chars ? `…${t.slice(-chars)}` : t
+}

package/src/verify/artifact.ts

@@ -0,0 +1,95 @@
+// Runtime provenance belongs to the plugin instance that is executing the
+// goal, not whichever shared service an unscoped `opencode api` happens to
+// find. Pin the loaded bytes once at setup; registry metadata is re-read
+// through that instance's own location-scoped API.
+import { createHash } from "node:crypto"
+import { lstatSync, readFileSync, readdirSync } from "node:fs"
+import { join } from "node:path"
+
+export type ArtifactHashes = Record<string, string>
+export type ArtifactSource = { type: string; target?: string; version?: string; outdated?: boolean; path?: string }
+export type RuntimeProvenance = {
+  schema: "opencode-goal/provenance/v1"
+  serverPID: number
+  openCodeVersion: string
+  location: string
+  packageRoot: string
+  packageVersion: string
+  capturedAt: number
+  observedAt: number
+  source: ArtifactSource
+  status: string
+  features: { server: boolean; tui: boolean; rpc: boolean }
+  artifacts: ArtifactHashes
+  sessionID?: string
+  runId?: string
+  lock?: string
+}
+
+const entrypoints = ["package.json", "server.ts", "tui.tsx", "rpc.ts"]
+const directories = ["src", "skills", "dist"]
+export const isArtifactPath = (path: string) => entrypoints.includes(path) || directories.some((dir) => path.startsWith(`${dir}/`))
+export const hashArtifact = (bytes: Uint8Array) => createHash("sha256").update(bytes).digest("hex")
+
+export function captureArtifactHashes(root: string): ArtifactHashes {
+  const files = [...entrypoints]
+  const walk = (relative: string) => {
+    for (const item of readdirSync(join(root, relative), { withFileTypes: true })) {
+      const path = `${relative}/${item.name}`
+      if (item.isSymbolicLink()) throw new Error(`Artifact symlink is not a loaded-byte proof: ${path}`)
+      if (item.isDirectory()) walk(path)
+      else if (item.isFile()) files.push(path)
+    }
+  }
+  for (const dir of directories) walk(dir)
+  return Object.fromEntries(files.sort().map((path) => {
+    if (!lstatSync(join(root, path)).isFile()) throw new Error(`Missing artifact file: ${path}`)
+    return [path, hashArtifact(readFileSync(join(root, path)))]
+  }))
+}
+
+/** Return all discrepancies, never let a matching semantic label substitute
+ * for a Git revision or the actual bytes. Absent outdated means no update is
+ * reported by V2; an absent revision is still an error. */
+export function artifactDiscrepancies(actual: RuntimeProvenance, expected: {
+  revision: string
+  artifacts: ArtifactHashes
+  location?: string
+  serverPID?: number
+  sessionID?: string
+  runId?: string
+  lock?: string
+  minVersion?: string
+}): string[] {
+  const errors: string[] = []
+  if (actual.schema !== "opencode-goal/provenance/v1") errors.push("missing runtime provenance schema")
+  if (!/^[a-f0-9]{40}$/.test(expected.revision)) errors.push("expected revision must be a full immutable Git SHA")
+  if (actual.source.type !== "package") errors.push("the running plugin is not a package install")
+  if (actual.source.version !== expected.revision) errors.push(`running revision ${actual.source.version ?? "unknown"} differs from ${expected.revision}`)
+  if (actual.source.outdated === true) errors.push("the running plugin reports outdated=true")
+  if (actual.status !== "active" || !actual.features?.server || !actual.features?.tui || !actual.features?.rpc) errors.push("the serving plugin is not active with server/TUI/RPC features")
+  for (const key of ["location", "serverPID", "sessionID", "runId", "lock"] as const) {
+    if (expected[key] !== undefined && actual[key] !== expected[key]) errors.push(`runtime ${key} does not match the goal/check caller`)
+  }
+  const required = ["package.json", "server.ts", "tui.tsx", "rpc.ts", "dist/tui.js", "src/server/app.ts", "src/tui/index.tsx", "src/tui/dashboard.ts", "skills/write-goal/SKILL.md"]
+  for (const path of required) if (!expected.artifacts[path]) errors.push(`release manifest omits ${path}`)
+  const paths = new Set([...Object.keys(expected.artifacts), ...Object.keys(actual.artifacts)])
+  for (const path of paths) {
+    if (!isArtifactPath(path) || !/^[a-f0-9]{64}$/.test(expected.artifacts[path] ?? "") || actual.artifacts[path] !== expected.artifacts[path])
+      errors.push(`artifact mismatch: ${path}`)
+  }
+  if (expected.minVersion && !versionAtLeast(actual.packageVersion, expected.minVersion)) errors.push(`package ${actual.packageVersion} is below ${expected.minVersion}`)
+  return errors
+}
+
+export function versionAtLeast(actual: string, minimum: string): boolean {
+  const parse = (s: string) => /^(\d+)\.(\d+)\.(\d+)(-[\w.-]+)?(?:\+[\w.-]+)?$/.exec(s)
+  const a = parse(actual), b = parse(minimum)
+  if (!a || !b) return false
+  for (let i = 1; i <= 3; i++) {
+    if (Number(a[i]) !== Number(b[i])) return Number(a[i]) > Number(b[i])
+  }
+  // A prerelease is below its corresponding stable minimum. This checker
+  // deliberately does not rank arbitrary prerelease identifiers.
+  return !a[4] || a[4] === b[4]
+}

package/src/verify/pipeline.ts

@@ -0,0 +1,200 @@
+// Completion is decided here, never by the worker. Order: contract integrity →
+// host-run checks → independent verifier (with quotes the host re-reads) →
+// owner sign-off for human criteria.
+import { existsSync, readFileSync } from "node:fs"
+import { isAbsolute, join, normalize, relative } from "node:path"
+import type { Check, Contract, Criterion } from "../contract/types"
+import { isHostCheck } from "../contract/types"
+import { lockOf } from "../contract/parse"
+import type { RunState } from "../engine/state"
+import { changedSince, isRepo, matchesAny } from "../util/git"
+import { runShell, tail, type ShellResult } from "../util/shell"
+
+export type CheckResult = { id: string; pass: boolean; by: "host" | "verifier" | "verifier-fallback" | "human"; detail: string; raw?: unknown }
+
+export type VerifierVerdict = { id: string; verdict: "proven" | "not_proven" | "contradicted"; reason?: string; evidence: Array<{ path: string; quote: string }> }
+export type VerifierRun = (input: { contract: Contract; state: RunState; criteria: Criterion[]; host: CheckResult[] }) => Promise<{ verdicts: VerifierVerdict[]; by?: "verifier" | "verifier-fallback"; error?: string }>
+
+export type VerifyOutcome = {
+  passed: boolean
+  needsHuman: string[]
+  results: CheckResult[]
+  integrity: string[]
+  lines: string[]
+}
+
+const inside = (root: string, path: string) => {
+  const full = normalize(isAbsolute(path) ? path : join(root, path))
+  const rel = relative(root, full)
+  return rel && !rel.startsWith("..") && !isAbsolute(rel) ? full : rel === "" ? full : undefined
+}
+
+export async function runHostCheck(check: Check, root: string, base: string | undefined, shell = runShell): Promise<{ pass: boolean; detail: string; raw?: unknown }> {
+  switch (check.kind) {
+    case "command": {
+      const runs: ShellResult[] = []
+      for (let i = 0; i < (check.runs ?? 1); i++) {
+        const result = await shell(check.run, root, check.timeout ?? 300)
+        runs.push(result)
+        const why = failure(check, result)
+        if (why) return { pass: false, detail: `run ${i + 1}/${check.runs ?? 1}: ${why}\n${tail(result.stdout + (result.stderr ? `\n[stderr]\n${result.stderr}` : ""))}`, raw: runs }
+      }
+      const last = runs.at(-1)!
+      return { pass: true, detail: `exit ${last.exit} in ${(last.ms / 1000).toFixed(1)}s${(check.runs ?? 1) > 1 ? ` ×${check.runs}` : ""}`, raw: runs }
+    }
+    case "file": {
+      const path = inside(root, check.path)
+      if (!path) return { pass: false, detail: `${check.path} is outside the project` }
+      const exists = existsSync(path)
+      const want = check.exists !== false
+      return { pass: exists === want, detail: `${check.path} ${exists ? "exists" : "does not exist"}` }
+    }
+    case "contains": {
+      const path = inside(root, check.path)
+      if (!path || !existsSync(path)) return { pass: false, detail: `${check.path} not found` }
+      const text = readFileSync(path, "utf8")
+      const ok = check.text ? text.includes(check.text) : new RegExp(check.regex!, "m").test(text)
+      return { pass: ok, detail: ok ? `${check.path} contains the expected ${check.text ? "text" : "pattern"}` : `${check.path} lacks ${check.text ? `"${check.text}"` : `/${check.regex}/`}` }
+    }
+    case "absent": {
+      const paths = check.paths?.length ? check.paths : ["."]
+      const quoted = (s: string) => `'${s.replace(/'/g, `'\\''`)}'`
+      const cmd = isRepo(root)
+        ? `git grep -n -I -E -e ${quoted(check.pattern)} -- ${paths.map(quoted).join(" ")} ':(exclude).opencode/goals'`
+        : `grep -rnIE --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=goals -e ${quoted(check.pattern)} ${paths.map(quoted).join(" ")}`
+      const result = await shell(cmd, root, 120)
+      const matches = result.stdout.trim().split("\n").filter(Boolean)
+      if (result.exit > 1) return { pass: false, detail: `search failed (exit ${result.exit}): ${tail(result.stderr, 3)}` }
+      return { pass: matches.length === 0, detail: matches.length ? `${matches.length} match(es) remain, e.g.\n${matches.slice(0, 5).join("\n")}` : "no matches" }
+    }
+    case "diff": {
+      const changed = changedSince(root, base).filter((f) => matchesAny(f, check.paths))
+      return { pass: changed.length === 0, detail: changed.length ? `changed since start: ${changed.slice(0, 10).join(", ")}` : "unchanged since start" }
+    }
+    default:
+      return { pass: false, detail: `${check.kind} is not a host check` }
+  }
+}
+
+function failure(check: Extract<Check, { kind: "command" }>, result: ShellResult): string | undefined {
+  if (result.timedOut) return `timed out after ${check.timeout ?? 300}s`
+  const e = check.expect ?? { exit: 0 }
+  if (e.exit !== undefined && result.exit !== e.exit) return `exit ${result.exit}, expected ${e.exit}`
+  if (e.stdout_contains && !result.stdout.includes(e.stdout_contains)) return `output lacks "${e.stdout_contains}"`
+  if (e.stdout_regex && !new RegExp(e.stdout_regex, "m").test(result.stdout)) return `output does not match /${e.stdout_regex}/`
+  return undefined
+}
+
+const collapse = (s: string) => s.replace(/\s+/g, " ").trim()
+
+/** T108: JUnit/XML bytes carry entity escapes (`&#10;`, `&quot;`, `&lt;`). A
+ * verifier that quotes the *decoded* line it read (a newline, a quote mark) did
+ * not match the raw XML, so a correct round was rejected as "quoted text not
+ * found" — the live C5 failure. Decode both sides before comparing. */
+export function decodeEntities(s: string): string {
+  return s
+    .replace(/&#x([0-9a-fA-F]+);/g, (m, h) => { try { return String.fromCodePoint(parseInt(h, 16)) } catch { return m } })
+    .replace(/&#(\d+);/g, (m, d) => { try { return String.fromCodePoint(Number(d)) } catch { return m } })
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&amp;/g, "&")
+}
+
+/** The host re-reads every quote the verifier cites; an unverifiable quote is no
+ * evidence. A quote may match the raw bytes or their entity-decoded equivalent,
+ * so both the raw junit and a plain-text renderer of the same line are accepted. */
+export function checkQuotes(root: string, verdict: VerifierVerdict): { ok: boolean; why?: string } {
+  if (verdict.verdict !== "proven") return { ok: false, why: verdict.reason ?? verdict.verdict }
+  if (!verdict.evidence.length) return { ok: false, why: "verifier cited no evidence" }
+  for (const item of verdict.evidence) {
+    const path = inside(root, item.path)
+    if (!path || !existsSync(path)) return { ok: false, why: `cited file ${item.path} does not exist` }
+    if (!item.quote || collapse(item.quote).length < 8) return { ok: false, why: `quote from ${item.path} is too short to check` }
+    const raw = readFileSync(path, "utf8")
+    const hit = (hay: string, needle: string) => collapse(hay).includes(collapse(needle))
+    if (!hit(raw, item.quote) && !hit(decodeEntities(raw), decodeEntities(item.quote)))
+      return { ok: false, why: `quoted text not found in ${item.path} (raw or entity-decoded)` }
+  }
+  return { ok: true }
+}
+
+export async function verifyClaim(contract: Contract, state: RunState, deps: { root: string; contractText: string; verifier?: VerifierRun; shell?: typeof runShell; onProgress?: (activity: RunState["activity"]) => void }): Promise<VerifyOutcome> {
+  const { root } = deps
+  const integrity: string[] = []
+  if (lockOf(deps.contractText) !== state.lock)
+    integrity.push(
+      "goal.yaml changed since the run started: the contract is sha256-locked for this run. The owner re-locks an amended contract with /goal amend confirm (audit-trailed, generation-bound) or aborts and starts fresh; a worker must never edit .opencode/goals/.",
+    )
+  if (contract.protect.length) {
+    const touched = changedSince(root, state.base.commit).filter((f) => matchesAny(f, contract.protect))
+    if (touched.length) integrity.push(`protected paths were modified: ${touched.slice(0, 10).join(", ")}. Restore them; do not change the oracle to make it pass.`)
+  }
+
+  const results: CheckResult[] = []
+  // T057: an owner-approved criterion is final against HOST re-checks too —
+  // a stale check (the live C15 needle case) must never stomp an explicit
+  // sign-off. The owner outranks every automated re-verification.
+  const ownerFinal = (id: string) => state.criteria[id]?.status === "pass" && state.criteria[id]?.by === "human"
+  const checkable = [...contract.criteria, ...contract.invariants].filter((c) => isHostCheck(c.check))
+  for (const [index, c] of checkable.entries()) {
+    if (ownerFinal(c.id)) {
+      results.push({ id: c.id, pass: true, by: "human", detail: "approved by the owner (final)" })
+      continue
+    }
+    // T063: the tracer shows live per-criterion progress through the checks
+    state.activity = { kind: "verifying", since: state.activity?.since ?? Date.now(), detail: `check ${c.id} · ${index + 1}/${checkable.length}` }
+    deps.onProgress?.(state.activity)
+    const r = await runHostCheck(c.check, root, state.base.commit, deps.shell)
+    results.push({ id: c.id, pass: r.pass, by: "host", detail: r.detail, raw: r.raw })
+  }
+
+  const semantic = contract.criteria.filter((c) => c.check.kind === "verifier")
+  const strictExtra = contract.verification.mode === "strict" ? contract.criteria.filter((c) => isHostCheck(c.check) && results.find((r) => r.id === c.id)?.pass) : []
+  // T051: an owner-approved criterion (pass by:human) is final — the owner
+  // outranks the verifier, so re-verification must respect it permanently
+  // instead of re-running a child that can stomp an explicit sign-off.
+  const toVerify = (contract.verification.mode === "host" ? [] : [...semantic, ...strictExtra]).filter((c) => !ownerFinal(c.id))
+  for (const c of [...semantic, ...strictExtra]) {
+    if (ownerFinal(c.id) && !results.some((r) => r.id === c.id))
+      results.push({ id: c.id, pass: true, by: "human", detail: "approved by the owner (final)" })
+  }
+  if (toVerify.length) {
+    if (!deps.verifier) {
+      for (const c of toVerify) results.push({ id: c.id, pass: false, by: "verifier", detail: "verifier unavailable; failing closed" })
+    } else {
+      const run = await deps.verifier({ contract, state, criteria: toVerify, host: results }).catch((error) => ({ verdicts: [] as VerifierVerdict[], by: "verifier" as const, error: String(error) }))
+      for (const c of toVerify) {
+        const v = run.verdicts.find((x) => x.id === c.id)
+        const checked = v ? checkQuotes(root, v) : { ok: false, why: run.error ? `verifier failed: ${run.error}` : "verifier returned no verdict" }
+        const prior = results.findIndex((r) => r.id === c.id)
+        const entry: CheckResult = { id: c.id, pass: checked.ok, by: run.by === "verifier-fallback" ? "verifier-fallback" : "verifier", detail: checked.ok ? `proven with ${v!.evidence.length} quote(s)${run.by === "verifier-fallback" ? " (parsed fallback verdict)" : ""}` : checked.why ?? "not proven", raw: v }
+        if (prior >= 0) {
+          // strict mode: the verifier must agree with the passing host check
+          if (!checked.ok) results[prior] = { ...entry, detail: `host passed but verifier disagrees: ${entry.detail}` }
+        } else results.push(entry)
+      }
+    }
+  }
+
+  const needsHuman = contract.criteria.filter((c) => c.check.kind === "human" && !(state.criteria[c.id]?.status === "pass" && state.criteria[c.id]?.by === "human")).map((c) => c.id)
+  for (const c of contract.criteria.filter((c) => c.check.kind === "human")) {
+    const s = state.criteria[c.id]
+    results.push({ id: c.id, pass: s?.status === "pass" && s.by === "human", by: "human", detail: s?.status === "pass" ? "approved by the owner" : "awaiting owner sign-off" })
+  }
+
+  const required = new Set([...contract.criteria.filter((c) => c.essential).map((c) => c.id), ...contract.invariants.map((c) => c.id)])
+  const failed = results.filter((r) => required.has(r.id) && !r.pass && r.by !== "human")
+  const passed = integrity.length === 0 && failed.length === 0 && needsHuman.filter((id) => required.has(id)).length === 0
+
+  const lines: string[] = []
+  for (const i of integrity) lines.push(`INTEGRITY: ${i}`)
+  for (const r of results) {
+    if (r.pass) continue
+    const c = [...contract.criteria, ...contract.invariants].find((x) => x.id === r.id)
+    lines.push(`${r.id} ${required.has(r.id) ? "FAILED" : "not met (optional)"} [${r.by}] ${c?.statement ?? ""}\n    ${r.detail.replace(/\n/g, "\n    ")}`)
+  }
+  if (!lines.length) lines.push("All required criteria passed.")
+  return { passed, needsHuman, results, integrity, lines }
+}

package/tui.tsx

@@ -0,0 +1,2 @@
+// Root TUI entry (see server.ts).
+export { default } from "./dist/tui.js"