@cleocode/goal 0.0.0-stage → 0.9.2

package/src/engine/owner-reviews.ts

@@ -0,0 +1,178 @@
+import { randomUUID } from "node:crypto"
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs"
+import { dirname } from "node:path"
+
+export type ReviewRequest = {
+  id: string
+  sessionID: string
+  slug: string
+  lock: string
+  title: string
+  question: string
+  createdAt: number
+  expiresAt: number
+  /** Target-bound lifecycle decisions have no clock expiry; legacy records
+   * and sealed launch approvals remain timed by default. */
+  expiryPolicy?: "time" | "target"
+  issuerPID: number
+  status: "pending" | "interrupted" | "executing" | "succeeded" | "rejected" | "commented" | "cancelled" | "expired" | "failed"
+  formID?: string
+  fieldKey?: string
+  choiceValues?: Record<string, string>
+  result?: string
+  comment?: string
+  /** Authenticated owner-message identity, when this is a direct owner command. */
+  ownerMessageID?: string
+}
+type ReviewData<T> = { version: 1; requests: Record<string, T> }
+export type ReviewChoice = { value: string; label: string; description: string }
+
+/** Clock expiry is reserved for explicitly timed/legacy reviews. */
+export function reviewExpired(request: Pick<ReviewRequest, "expiresAt" | "expiryPolicy">, now = Date.now()): boolean {
+  return request.expiryPolicy !== "target" && request.expiresAt < now
+}
+
+/** Interpret only the values actually offered in the bound field. Internal
+ * aliases typed as custom commentary are not selectable owner consent. */
+export function selectedReviewChoice(request: ReviewRequest, choices: readonly ReviewChoice[], answer: Record<string, unknown>): ReviewChoice | undefined {
+  const value = request.fieldKey ? answer[request.fieldKey] : undefined
+  return typeof value === "string" ? choices.find((c) => request.choiceValues?.[c.value] === value) : undefined
+}
+
+export const processAlive = (pid: number): boolean => {
+  try { process.kill(pid, 0); return true } catch (error: any) { return error?.code === "EPERM" }
+}
+
+/** The host-owned sidecar is outside individual runs, so authoring sessions
+ * can recover approvals before any run exists. A short cross-process lock
+ * makes reservation one-use even when two servers share a project folder. */
+export class OwnerReviewStore<T extends ReviewRequest> {
+  constructor(readonly file: string, readonly choices: readonly ReviewChoice[]) {}
+  protected reviewChoices(_request: T): readonly ReviewChoice[] { return this.choices }
+
+  private read(): ReviewData<T> {
+    if (!existsSync(this.file)) return { version: 1, requests: {} }
+    const data = JSON.parse(readFileSync(this.file, "utf8"))
+    if (data?.version !== 1 || !data.requests || Array.isArray(data.requests)) throw new Error("Owner decision store is invalid; refusing consent")
+    return data
+  }
+  protected mutate<R>(fn: (data: ReviewData<T>) => R): R {
+    mkdirSync(dirname(this.file), { recursive: true })
+    const lock = `${this.file}.lock`
+    // Do not steal an active lock. An abandoned lock can be recovered only
+    // after its recorded process has exited, never merely because it is old.
+    if (existsSync(lock)) {
+      const pid = Number(readFileSync(lock, "utf8"))
+      if (Number.isInteger(pid) && pid > 0 && !processAlive(pid)) unlinkSync(lock)
+    }
+    const fd = openSync(lock, "wx", 0o600)
+    try {
+      writeFileSync(fd, String(process.pid))
+      const data = this.read()
+      const result = fn(data)
+      const tmp = `${this.file}.${randomUUID()}.tmp`
+      const output = openSync(tmp, "wx", 0o600)
+      try { writeFileSync(output, `${JSON.stringify(data, null, 2)}\n`); fsyncSync(output) } finally { closeSync(output) }
+      renameSync(tmp, this.file)
+      return result
+    } finally { closeSync(fd); unlinkSync(lock) }
+  }
+  all(sessionID?: string): T[] {
+    return Object.values(this.read().requests).filter((p) => !sessionID || p.sessionID === sessionID)
+  }
+  get(id: string): T | undefined { return this.read().requests[id] }
+  /** Host-only source binding, never tool-supplied approval text. Failed
+   * attempts spend the source too; cross-process duplicates cannot rebind. */
+  bindOwnerMessage(id: string, ownerMessageID: string): T | undefined {
+    return this.mutate((data) => {
+      const p = data.requests[id]
+      if (!p || !["pending", "interrupted"].includes(p.status) || p.ownerMessageID || reviewExpired(p)
+        || p.issuerPID !== process.pid && processAlive(p.issuerPID)
+        || Object.values(data.requests).some((r) => r.ownerMessageID === ownerMessageID)) return undefined
+      p.ownerMessageID = ownerMessageID
+      p.status = "pending"
+      return p
+    })
+  }
+  create(input: Omit<T, "id" | "status">, options: { keepOthers?: boolean } = {}): T {
+    return this.mutate((data) => {
+      if (!options.keepOthers) for (const p of Object.values(data.requests))
+        if (p.sessionID === input.sessionID && ["pending", "interrupted"].includes(p.status)) p.status = "cancelled"
+      const p = { ...input, id: randomUUID(), status: "pending" } as T
+      // The nonce is in the displayed question and must match the actual
+      // question field. A matching label in an unrelated form is not enough.
+      p.question += `\nDecision: ${p.id}`
+      data.requests[p.id] = p
+      return p
+    })
+  }
+  bind(form: { id: string; sessionID: string; fields?: Array<{ key?: string; title?: string; description?: string; options?: Array<{ value: string; label: string }> }> }): T | undefined {
+    const matches = (p: T) => {
+      const choices = this.reviewChoices(p)
+      return p.sessionID === form.sessionID && p.status === "pending" && !p.formID && !reviewExpired(p) && form.fields?.length === 1 && form.fields.some((f) => !!f.key && (f.title === p.question || f.description === p.question) && f.options?.length === choices.length && choices.every((c) => f.options?.some((o) => o.label === c.label && (o.value === c.value || o.value === c.label))))
+    }
+    // Most forms have nothing to do with this store. Do not fsync an empty
+    // sidecar on every unrelated form; revalidate under the lock if matched.
+    if (!this.all(form.sessionID).some(matches)) return undefined
+    return this.mutate((data) => {
+      const p = Object.values(data.requests).find(matches)
+      if (!p) return undefined
+      if (p.issuerPID !== process.pid && processAlive(p.issuerPID)) return undefined
+      p.formID = form.id
+      const field = form.fields?.find((f) => f.title === p.question || f.description === p.question)
+      p.fieldKey = field?.key
+      p.choiceValues = Object.fromEntries(this.reviewChoices(p).map((c) => [c.value, field!.options!.find((o) => o.label === c.label)!.value]))
+      return p
+    })
+  }
+  byForm(sessionID: string, formID: string): T | undefined {
+    return this.all(sessionID).find((p) => p.formID === formID)
+  }
+  update(id: string, change: Partial<Pick<ReviewRequest, "status" | "result" | "comment">>): T {
+    return this.mutate((data) => {
+      const p = data.requests[id]
+      if (!p) throw new Error("Unknown owner decision")
+      Object.assign(p, change)
+      return p
+    })
+  }
+  reopenForm(id: string): T | undefined {
+    return this.mutate((data) => {
+      const p = data.requests[id]
+      if (!p || !["pending", "interrupted"].includes(p.status)) return undefined
+      p.status = "pending"
+      delete p.formID
+      delete p.fieldKey
+      delete p.choiceValues
+      return p
+    })
+  }
+  interruptForm(id: string): T | undefined {
+    return this.mutate((data) => {
+      const p = data.requests[id]
+      if (!p || p.status !== "pending") return undefined
+      p.status = "interrupted"
+      p.result = "The form was dismissed or interrupted by the host; no operation was authorized."
+      delete p.formID
+      delete p.fieldKey
+      delete p.choiceValues
+      return p
+    })
+  }
+  reserve(id: string): T | undefined {
+    return this.mutate((data) => {
+      const p = data.requests[id]
+      if (!p || p.status !== "pending") return undefined
+      // Different processes can create separate proposals for the same real
+      // message. Enforce consumption under THIS cross-process lock, not only
+      // with an earlier all() read in the caller.
+      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 (reviewExpired(p)) { p.status = "expired"; return undefined }
+      if (p.issuerPID !== process.pid && processAlive(p.issuerPID)) return undefined
+      p.status = "executing"
+      p.issuerPID = process.pid
+      return p
+    })
+  }
+}

package/src/engine/peer-announce.ts

@@ -0,0 +1,67 @@
+// v0.8.0 — when the loop may tell peers it is available.
+//
+// Owner policy: announce on an idle transition, always, but never nag. The two
+// brakes are mechanical:
+//   1. one outstanding announcement at a time — while a peer has not answered,
+//      another announcement is spam, not availability;
+//   2. a cooldown floor after the last announcement — a rapid sequence of idle
+//      transitions (complete → resume → complete) is one idle period, not five.
+//
+// Pure. The transport (AgentMBX) lives in peer-transport.ts and is injected, so
+// the unit suite never touches the network.
+
+export type AnnounceState = {
+  /** When this run last announced. */
+  lastAt?: number
+  /** The announcement still waiting for an answer, if any. */
+  outstanding?: { id: string; at: number }
+}
+
+export type AnnounceDecision =
+  | { due: true }
+  | { due: false; reason: "outstanding" | "cooldown" }
+
+export function announceDue(state: AnnounceState, now: number, cooldownMs: number): AnnounceDecision {
+  if (state.outstanding) return { due: false, reason: "outstanding" }
+  if (state.lastAt !== undefined && now - state.lastAt < cooldownMs) return { due: false, reason: "cooldown" }
+  return { due: true }
+}
+
+/** What a peer reads. Short, factual, no task invention and no secrets. */
+export function announcementText(input: { project: string; slug: string; taskId?: string }): string {
+  const task = input.taskId ? ` (CLEO ${input.taskId})` : ""
+  return `Available for work. Project: ${input.project}. Last goal: ${input.slug}${task}. Reply with a task id or a one-line work request; I will treat it as a candidate, not as consent.`
+}
+
+export type PeerReply = {
+  id: string
+  from: string
+  text: string
+  at: number
+  project?: string
+}
+
+/** The injectable transport. The policy above never imports this. */
+export type PeerChannel = {
+  announce(input: { text: string; sessionID?: string }): Promise<{ id: string } | undefined>
+  replies(input: { since: number; sessionID?: string }): Promise<PeerReply[]>
+}
+
+/**
+ * A reply becomes CANDIDATE work, never an instruction. A task id in the text
+ * is recorded so the next-work decision can offer it; the body is kept verbatim
+ * and labelled as a peer claim.
+ */
+export function candidateFromReply(reply: PeerReply, currentProject: string) {
+  const task = /\bT\d{1,7}\b/.exec(reply.text)?.[0]
+  const firstLine = reply.text.split("\n").map((l) => l.trim()).filter(Boolean)[0] ?? "(empty reply)"
+  return {
+    source: "peer" as const,
+    project: reply.project ?? currentProject,
+    ...(task ? { taskId: task } : {}),
+    title: firstLine.slice(0, 200),
+    from: reply.from,
+    messageId: reply.id,
+    at: reply.at,
+  }
+}

package/src/engine/peer-transport.ts

@@ -0,0 +1,78 @@
+// v0.8.0 — the AgentMBX transport behind the pure announcement policy.
+//
+// One process boundary, one place that can fail. Every failure is returned as
+// "no id"/"no replies" and journalled by the caller; it is never invented. The
+// channel is only constructed when an identity is configured, so a project with
+// no mailbox does not shell out to a command whose side effects nobody asked for.
+
+import type { PeerChannel, PeerReply } from "./peer-announce"
+
+export type PeerTransportOptions = {
+  bin: string
+  identity: string
+  cli: string
+  timeoutMs?: number
+}
+
+const asText = (v: unknown) => (typeof v === "string" ? v : "")
+
+/** The id from `{"id": "..."}`, a plain id line, or `id: ...`; undefined if absent. */
+export function parseMessageId(stdout: string): string | undefined {
+  const text = stdout.trim()
+  if (!text) return undefined
+  try {
+    const parsed = JSON.parse(text)
+    const id = asText(parsed?.id ?? parsed?.data?.id)
+    if (id) return id
+  } catch { /* not JSON */ }
+  return /(?:^|\s)(?:id|messageId)[:=]\s*"?([A-Za-z0-9_-]{6,})"?/i.exec(text)?.[1]
+    ?? /^([A-Za-z0-9_-]{20,})$/.exec(text)?.[1]
+}
+
+export function createPeerChannel(options: PeerTransportOptions): PeerChannel {
+  const timeoutMs = options.timeoutMs ?? 10_000
+  const run = async (args: string[]): Promise<{ stdout: string; exit: number }> =>
+    new Promise((resolve) => {
+      const child = Bun.spawn([options.bin, ...args], { stdout: "pipe", stderr: "ignore" })
+      const timer = setTimeout(() => child.kill(), timeoutMs)
+      Promise.all([new Response(child.stdout).text(), child.exited])
+        .then(([stdout, exit]) => resolve({ stdout, exit: Number(exit) }))
+        .catch(() => resolve({ stdout: "", exit: 1 }))
+        .finally(() => clearTimeout(timer))
+    })
+
+  const sessionArgs = (sessionID?: string) =>
+    sessionID ? ["--cli", options.cli, "--session", sessionID] : []
+
+  return {
+    async announce(input) {
+      const result = await run([
+        "send", "--as", options.identity, "--to", "*",
+        "--subject", "Available for work", "--kind", "message",
+        "-m", input.text, ...sessionArgs(input.sessionID),
+      ])
+      if (result.exit !== 0) return undefined
+      const id = parseMessageId(result.stdout)
+      return id ? { id } : undefined
+    },
+    async replies(input) {
+      const result = await run([
+        "inbox", "--as", options.identity, "--all", "--json",
+        ...sessionArgs(input.sessionID),
+      ])
+      if (result.exit !== 0) return []
+      let parsed: unknown
+      try { parsed = JSON.parse(result.stdout) } catch { return [] }
+      const rows = Array.isArray(parsed) ? parsed : Array.isArray((parsed as any)?.messages) ? (parsed as any).messages : []
+      return rows.flatMap((m: any): PeerReply[] => {
+        const id = asText(m?.id)
+        const from = asText(m?.from)
+        const at = Date.parse(asText(m?.ts))
+        if (!id || !from || from === options.identity || Number.isNaN(at) || at <= input.since) return []
+        // The list endpoint has no body; the subject is the first line of what
+        // the peer said. A fuller read is the next step, never an invention.
+        return [{ id, from, at, text: asText(m?.subject) || "(no subject)" }]
+      })
+    },
+  }
+}

package/src/engine/policy.ts

@@ -0,0 +1,42 @@
+// Owner-set autonomy policy. The OWNER lists change classes in the launched
+// contract (autonomy.amend); the agent may apply a change itself only when
+// every difference falls inside those classes. Criteria statements, checks
+// (other than their timeout), roles, protect, scope, verification, stop
+// rules and the policy itself are never agent-applicable.
+import type { AmendClass, Contract, Criterion } from "../contract/types"
+import { canonical } from "./amendment"
+
+export type ChangeClassification = { classes: AmendClass[]; blocked: string[] }
+
+const withoutTimeout = (c: Criterion) => ({ ...c, check: { ...c.check, timeout: undefined } })
+
+export function classifyChange(prior: Contract, next: Contract): ChangeClassification {
+  const classes = new Set<AmendClass>()
+  const blocked: string[] = []
+  for (const key of ["criteria", "invariants"] as const) {
+    const a = prior[key], b = next[key]
+    if (a.length !== b.length || a.some((c, i) => c.id !== b[i]!.id)) { blocked.push(`${key} added, removed or reordered`); continue }
+    a.forEach((c, i) => {
+      const d = b[i]!
+      if (canonical(c) === canonical(d)) return
+      if (canonical(withoutTimeout(c)) === canonical(withoutTimeout(d))) classes.add("timeout")
+      else blocked.push(`${c.id} statement, check or role changed`)
+    })
+  }
+  if (canonical(prior.budget) !== canonical(next.budget)) classes.add("budget")
+  if (canonical(prior.plan) !== canonical(next.plan) || canonical(prior.assumptions) !== canonical(next.assumptions)) classes.add("plan")
+  if (canonical(prior.autonomy) !== canonical(next.autonomy)) blocked.push("the autonomy policy itself changed (owner only)")
+  const handled = new Set<string>(["criteria", "invariants", "budget", "plan", "assumptions", "autonomy"])
+  for (const key of new Set([...Object.keys(prior), ...Object.keys(next)]))
+    if (!handled.has(key) && canonical((prior as any)[key]) !== canonical((next as any)[key])) blocked.push(`${key} changed`)
+  return { classes: [...classes], blocked }
+}
+
+/** Whether `policy` lets the agent apply this change (or recovery) itself. */
+export function policyAllows(policy: readonly AmendClass[], change: ChangeClassification, recovery = false): { ok: boolean; reasons: string[] } {
+  const reasons = [...change.blocked]
+  if (recovery && !policy.includes("recover")) reasons.push("divergence recovery is not in the policy")
+  for (const c of change.classes) if (!policy.includes(c)) reasons.push(`${c} changes are not in the policy`)
+  if (!change.classes.length && !change.blocked.length) reasons.push("no change")
+  return { ok: policy.length > 0 && reasons.length === 0, reasons }
+}

package/src/engine/registry.ts

@@ -0,0 +1,119 @@
+// T026 — the cross-project goal registry. A machine-level DERIVED index
+// (council 20261003T162655Z-800c52ca): the per-project .opencode/goals/
+// folders stay the source of truth; this file is a rebuildable cache that
+// answers "which goals exist where, in what state" without scanning every
+// project. Atomic writes (tmp + rename); OCGOAL_REGISTRY overrides the
+// location so hosts and tests never pollute the real index.
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync, statSync } from "node:fs"
+import { homedir, tmpdir } from "node:os"
+import { dirname, join } from "node:path"
+
+export type RegistryEntry = { title: string; status: string; runId?: string; lock?: string; archived?: boolean; priority?: "low" | "medium" | "high"; updatedAt: number }
+export type RegistryData = { version: 1; projects: Record<string, { goals: Record<string, RegistryEntry>; updatedAt: number }> }
+
+/** T061: priority then recency — high > medium > low > absent, ties by updatedAt descending (missing updatedAt = 0). */
+export const byPriorityThenRecency = <T extends { priority?: RegistryEntry["priority"]; updatedAt?: number }>(a: T, b: T): number => {
+  const wa = a.priority === "high" ? 3 : a.priority === "medium" ? 2 : a.priority === "low" ? 1 : 0
+  const wb = b.priority === "high" ? 3 : b.priority === "medium" ? 2 : b.priority === "low" ? 1 : 0
+  return wb - wa || (b.updatedAt ?? 0) - (a.updatedAt ?? 0)
+}
+
+export const DEFAULT_REGISTRY_PATH = join(homedir(), ".local", "share", "opencode", "goal-registry.json")
+
+export class Registry {
+  constructor(readonly path = process.env.OCGOAL_REGISTRY ?? DEFAULT_REGISTRY_PATH) {}
+
+  read(): RegistryData {
+    try {
+      const value = JSON.parse(readFileSync(this.path, "utf8"))
+      if (value?.version === 1 && value.projects && typeof value.projects === "object") return value as RegistryData
+    } catch {
+      // missing or corrupt: the index is derived, so start empty
+    }
+    return { version: 1, projects: {} }
+  }
+
+  private write(data: RegistryData) {
+    mkdirSync(dirname(this.path), { recursive: true })
+    const tmp = join(tmpdir(), `goal-registry-${process.pid}-${Date.now()}.json`)
+    writeFileSync(tmp, `${JSON.stringify(data, null, 2)}\n`)
+    renameSync(tmp, this.path)
+  }
+
+  /** Upsert one goal; skips the write when nothing changed (persist is hot). */
+  update(projectRoot: string, slug: string, entry: RegistryEntry): boolean {
+    const data = this.read()
+    const project = data.projects[projectRoot] ?? { goals: {}, updatedAt: 0 }
+    const current = project.goals[slug]
+    if (
+      current &&
+      current.title === entry.title &&
+      current.status === entry.status &&
+      current.runId === entry.runId &&
+      current.lock === entry.lock &&
+      current.archived === entry.archived &&
+      current.priority === entry.priority
+    )
+      return false
+    project.goals[slug] = entry
+    project.updatedAt = entry.updatedAt
+    data.projects[projectRoot] = project
+    this.write(data)
+    return true
+  }
+
+  remove(projectRoot: string, slug: string): boolean {
+    const data = this.read()
+    const project = data.projects[projectRoot]
+    if (!project?.goals[slug]) return false
+    delete project.goals[slug]
+    project.updatedAt = Date.now()
+    if (Object.keys(project.goals).length === 0) delete data.projects[projectRoot]
+    this.write(data)
+    return true
+  }
+
+  /** All goals across all known projects: [{project, slug, ...entry}], priority then recency. */
+  list(): Array<{ project: string; slug: string } & RegistryEntry> {
+    const out: Array<{ project: string; slug: string } & RegistryEntry> = []
+    for (const [project, p] of Object.entries(this.read().projects))
+      for (const [slug, entry] of Object.entries(p.goals)) out.push({ project, slug, ...entry })
+    return out.sort(byPriorityThenRecency)
+  }
+
+  /**
+   * Rebuild by scanning project roots; returns true when the rebuild changed
+   * the index (the parity property tests rely on: update-driven and
+   * scan-driven content must be identical for the same on-disk truth).
+   */
+  rebuild(roots: string[]): boolean {
+    const data: RegistryData = { version: 1, projects: {} }
+    for (const root of roots) {
+      const goalsDir = join(root, ".opencode", "goals")
+      if (!existsSync(goalsDir)) continue
+      const project = { goals: {} as Record<string, RegistryEntry>, updatedAt: 0 }
+      for (const dirent of readdirSync(goalsDir, { withFileTypes: true })) {
+        if (!dirent.isDirectory()) continue
+        const slug = dirent.name
+        const runPath = join(goalsDir, slug, "run.json")
+        let entry: RegistryEntry | undefined
+        try {
+          const run = JSON.parse(readFileSync(runPath, "utf8"))
+          if (run?.version !== 1) continue
+          entry = { title: run.title ?? slug, status: run.status ?? "draft", ...(run.runId ? { runId: run.runId } : {}), ...(run.lock ? { lock: run.lock } : {}), ...(run.priority ? { priority: run.priority } : {}), updatedAt: run.updatedAt ?? statSync(runPath).mtimeMs }
+        } catch {
+          // a goal folder without a readable run.json: still a draft goal
+          const contract = join(goalsDir, slug, "goal.yaml")
+          if (!existsSync(contract)) continue
+          entry = { title: slug, status: "draft", updatedAt: statSync(contract).mtimeMs }
+        }
+        project.goals[slug] = entry
+        project.updatedAt = Math.max(project.updatedAt, entry.updatedAt)
+      }
+      if (Object.keys(project.goals).length) data.projects[root] = project
+    }
+    const before = JSON.stringify(this.read())
+    this.write(data)
+    return JSON.stringify(this.read()) !== before
+  }
+}

package/src/engine/similarity.ts

@@ -0,0 +1,65 @@
+// T033 — admission-time existence and similarity probes (council
+// 20261003T162655Z-800c52ca): before a new slug is formed, /goal new checks
+// whether this intent already exists (exact slug or title) and surfaces
+// similar goals ranked, so duplicate intent is caught at the door. Pure and
+// unit-tested; the registry supplies candidates across live AND archived
+// goals (existence must survive archiving).
+
+const STOP = new Set([
+  "the", "a", "an", "to", "for", "of", "and", "or", "in", "on", "at", "is", "are", "be", "it", "its",
+  "this", "that", "with", "as", "by", "from", "you", "we", "our", "your", "make", "get", "set", "up",
+])
+
+export function tokenize(text: string): string[] {
+  return text
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((t) => t.length > 2 && !STOP.has(t))
+}
+
+/** Jaccard overlap of token sets — cheap, order-free, good enough at goal scale. */
+export function similarity(a: string, b: string): number {
+  const A = new Set(tokenize(a))
+  const B = new Set(tokenize(b))
+  if (!A.size || !B.size) return 0
+  let shared = 0
+  for (const t of A) if (B.has(t)) shared += 1
+  return shared / (A.size + B.size - shared)
+}
+
+export type Candidate = { slug: string; title: string; status?: string; archived?: boolean; project?: string }
+
+export type Match = Candidate & { score: number; matched: string[] }
+
+/** Exact existence: same slug, or a title that is the query verbatim (case-insensitive). */
+export function exactExists(query: string, slugHint: string, candidates: Candidate[]): Candidate | undefined {
+  const q = query.trim().toLowerCase()
+  return candidates.find((c) => c.slug === slugHint.trim().toLowerCase() || c.title.trim().toLowerCase() === q)
+}
+
+/** Ranked similar goals above the threshold, best first, capped. */
+export function similarGoals(query: string, candidates: Candidate[], threshold = 0.34, limit = 5): Match[] {
+  const tokens = new Set(tokenize(query))
+  return candidates
+    .map((c) => {
+      const hay = `${c.slug} ${c.title}`
+      const score = similarity(query, hay)
+      const matched = [...tokens].filter((t) => tokenize(hay).includes(t))
+      return { ...c, score, matched }
+    })
+    .filter((m) => m.score >= threshold)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit)
+}
+
+/** The note /goal new prepends when the probe finds anything worth surfacing. */
+export function admissionNote(query: string, slugHint: string, candidates: Candidate[]): string | undefined {
+  const exact = exactExists(query, slugHint, candidates)
+  const similar = similarGoals(query, candidates).filter((m) => !exact || m.slug !== exact.slug)
+  if (!exact && !similar.length) return undefined
+  const lines = ["[goal admission probe]"]
+  if (exact) lines.push(`EXISTS already: ${exact.slug} — "${exact.title}" (${exact.status ?? "draft"}${exact.archived ? ", archived" : ""}). Do not duplicate it: continue, resume or supersede it instead.`)
+  for (const m of similar) lines.push(`similar (${m.score.toFixed(2)}): ${m.slug} — "${m.title}" (${m.status ?? "draft"}${m.archived ? ", archived" : ""}) — consider superseding it with supersedes: ${m.slug}@<lock> if this replaces it.`)
+  lines.push("Surface these to the owner as options before forming a new slug: start fresh · continue/resume the existing goal · supersede it.")
+  return lines.join("\n")
+}

package/src/engine/stale-decisions.ts

@@ -0,0 +1,68 @@
+// v0.8.0 — a decision that can never legitimately be answered must never be
+// shown again.
+//
+// Three ways a stored owner question goes stale without an answer:
+//   - the target generation moved on (lock/run/session changed) or the goal was
+//     superseded — the old question is about bytes that no longer exist;
+//   - the review's own clock expired (legacy/timed reviews only);
+//   - it was already answered or otherwise settled.
+//
+// A dismissed review (`interrupted`) is NOT stale: it is unanswered and may be
+// re-presented by an explicit reload or goal_review. Pure on purpose.
+
+import { reviewExpired } from "./owner-reviews"
+
+export type DecisionLike = {
+  status: string
+  expiresAt: number
+  expiryPolicy?: "time" | "target"
+}
+
+export type TargetLike = {
+  slug: string
+  runId?: string
+  sessionID?: string
+  lock: string
+  status?: string
+}
+
+export type Staleness =
+  | { stale: false }
+  | { stale: true; code: "answered" | "expired" | "superseded" | "target-changed" | "missing"; reason: string }
+
+const OPEN = ["pending", "interrupted"]
+
+export function decisionStaleness(request: DecisionLike, current: TargetLike | undefined, now = Date.now()): Staleness {
+  if (!OPEN.includes(request.status))
+    return { stale: true, code: "answered", reason: `the decision is already ${request.status}; old choices cannot be replayed` }
+  if (reviewExpired(request, now))
+    return { stale: true, code: "expired", reason: "the review expired; a new exact review is required" }
+  if (!current)
+    return { stale: true, code: "missing", reason: "the decision's target no longer exists" }
+  if (current.status === "superseded")
+    return { stale: true, code: "superseded", reason: "the goal was superseded by a successor" }
+  return { stale: false }
+}
+
+/** Whether the target tuple the review was bound to still names the same run. */
+export function sameTarget(
+  bound: { slug: string; runId?: string; sessionID?: string; lock: string },
+  current: TargetLike | undefined,
+): boolean {
+  return !!current && current.slug === bound.slug && current.lock === bound.lock
+    && current.runId === bound.runId && current.sessionID === bound.sessionID
+}
+
+/** The full check the engine uses before re-presenting: staleness + tuple. */
+export function staleDecision(
+  request: DecisionLike,
+  bound: { slug: string; runId?: string; sessionID?: string; lock: string },
+  current: TargetLike | undefined,
+  now = Date.now(),
+): Staleness {
+  const base = decisionStaleness(request, current, now)
+  if (base.stale) return base
+  if (!sameTarget(bound, current))
+    return { stale: true, code: "target-changed", reason: "the goal generation or owning session changed; the old review is invalid" }
+  return { stale: false }
+}