@cleocode/goal 0.9.4 → 0.9.5

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.9.5 — 2026-10-28
+
+- **Every run records which harness produced it (T125).** `RunState.harness` is `{name, version, capabilities[]}`: the OpenCode engine records `name: "opencode"`, its serving package version, and the surfaces it can actually drive. The ledger's `start` event carries the same identity, so a repaired run keeps its producer. `goal_status`, the RPC snapshot/view and `goal_provenance` expose it. The field is optional and additive — `schemaVersion` stays 1, and a run written before it existed parses unchanged and is not retro-labelled.
+- **`cleo-goal status --json` reports the harness (T130).** Present when the run recorded one, omitted when it did not; no schema bump. A CLEO that has not yet landed T13875 ignores it.
+- **The Stop-dispatched tick records the harness CLEO declares (T131).** `CLEO_HOOK_PROVIDER=claude-code` records `claude`, `codex` records `codex`, and absent or any other value records `unknown`. Version and capabilities stay `null` on that path because the dispatcher does not supply them, and the Stop payload/transcript is never consulted for identity. The first writer wins: a later tick never renames the harness that produced the run. No `OCGOAL_HARNESS` variable and no `--harness` flag.
+- **`scripts/check-installed-goal.ts` works for a workspace-bound goal (T124).** The check now compares the serving runtime's location with the project checkout (where the plugin actually serves), not the linked worktree the host checks run in. A non-workspace goal is unaffected (`projectRoot === root`), and the check still rejects a runtime serving any other project.
+- **Documentation.** `docs/research/harness-identity.md` records the field, the dispatcher signal, every capability's meaning, the CLEO T13875 contract quote, and the current `cleo doctor goal-runtime` output.
+
 ## 0.9.4 — 2026-10-28
 
 - **Fixed — a contract locked before a validator tightening no longer bricks its run (D10).** A run whose locked generation carries a key the current validator rejects (the reported case: a free-text `budget.rationale` locked under 0.9.2) used to be unresumable: resume called it read-only, `goal_propose_amendment` claimed the disk differed, and `goal_recover_divergence` correctly said nothing differed. The locked bytes are now read leniently **only** to form the prior side of a repair amendment, the repair can be staged and owner-reviewed, and the resume refusal names the failing key and the exact `goal_propose_amendment` call instead of a generic read-only message. Strict validation of new and repaired contracts is unchanged.

package/dist/cli.js

@@ -6910,7 +6910,7 @@ import { readFileSync as readFileSync4 } from "node:fs";
 // package.json
 var package_default = {
   name: "@cleocode/goal",
-  version: "0.9.4",
+  version: "0.9.5",
   description: "CLEO Goal: persistent, host-verified goal mode for OpenCode 2 (and any harness through cleo-goal tick), with a structured goal contract and a live TUI.",
   type: "module",
   license: "MIT",
@@ -7706,6 +7706,7 @@ function goalStatus(store, now = Date.now()) {
     title: run.title,
     status: run.status,
     ...run.priority ? { priority: run.priority } : {},
+    ...run.harness ? { harness: run.harness } : {},
     turn: run.turn,
     reason: run.reason ?? null,
     criteria,
@@ -8251,6 +8252,22 @@ function recordTurn(state, _contract, inputs) {
   return { turn: state.turn, changed, progress, claimHonoured, ...mined ? { mined } : {}, couldNotSee };
 }
 
+// src/engine/harness-identity.ts
+var CLEO_HOOK_PROVIDER = "CLEO_HOOK_PROVIDER";
+function harnessFromHookProvider(value) {
+  switch ((value ?? "").trim()) {
+    case "claude-code":
+      return "claude";
+    case "codex":
+      return "codex";
+    default:
+      return "unknown";
+  }
+}
+function dispatcherIdentity(env = {}) {
+  return { name: harnessFromHookProvider(env[CLEO_HOOK_PROVIDER]), version: null, capabilities: null };
+}
+
 // src/engine/tick.ts
 var TICK_LIMITS = { blockerRepeats: 3, stallTurns: 3, recoveryAt: 2, backstopTurns: 200 };
 var TICK_COOLDOWN_MS = 1500;
@@ -8316,6 +8333,14 @@ async function tick(deps) {
   const record = recordTurn(live, contract, { fingerprint: deps.fingerprint ?? (() => {
     return;
   }), ...deps.payload ? { payload: deps.payload } : {}, ...deps.readTranscript ? { readTranscript: deps.readTranscript } : {}, now });
+  const identity = dispatcherIdentity(deps.env ?? process.env);
+  if (!live.harness) {
+    live.harness = identity;
+    deps.store.ledger(live.slug, { type: "harness", name: identity.name, version: identity.version, capabilities: identity.capabilities, source: "tick" });
+    log.push(`recorded harness ${identity.name}${identity.name === "unknown" ? " (no CLEO_HOOK_PROVIDER declared)" : ""}`);
+  } else if (live.harness.name !== identity.name && identity.name !== "unknown") {
+    log.push(`harness is already recorded as ${live.harness.name}; the dispatcher declared ${identity.name} - keeping the producer`);
+  }
   deps.store.ledger(live.slug, {
     type: "turn",
     turn: live.turn,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/goal",
-  "version": "0.9.4",
+  "version": "0.9.5",
   "description": "CLEO Goal: persistent, host-verified goal mode for OpenCode 2 (and any harness through cleo-goal tick), with a structured goal contract and a live TUI.",
   "type": "module",
   "license": "MIT",

package/src/cli/status.ts

@@ -4,6 +4,7 @@
 import { parseContract } from "../contract/parse"
 import type { Contract } from "../contract/types"
 import { budgetUse, isTerminal, type RunState, type Status } from "../engine/state"
+import type { HarnessIdentity } from "../engine/harness-identity"
 import type { Store } from "../engine/store"
 
 export const STATUS_SCHEMA_VERSION = 1
@@ -25,6 +26,12 @@ export type GoalStatusJson = {
   title: string
   status: Status | "none"
   priority?: "low" | "medium" | "high"
+  /**
+   * v0.9.5: which harness produced this run and what it can do. Optional and
+   * additive: `schemaVersion` stays 1 and a run that predates the field simply
+   * omits it, so an older CLEO reads the same shape it always did.
+   */
+  harness?: HarnessIdentity
   turn: number
   reason: string | null
   criteria: StatusCriterion[]
@@ -103,6 +110,7 @@ export function goalStatus(store: Store, now = Date.now()): GoalStatusJson {
     title: run.title,
     status: run.status,
     ...(run.priority ? { priority: run.priority } : {}),
+    ...(run.harness ? { harness: run.harness } : {}),
     turn: run.turn,
     reason: run.reason ?? null,
     criteria,

package/src/engine/harness-identity.ts

@@ -0,0 +1,95 @@
+// v0.9.5 - which harness produced a run, and what that harness can actually do.
+//
+// Every run records a declared identity: `{name, version, capabilities[]}`. It is
+// additive and optional — `schemaVersion` stays 1 and a run written before this
+// field existed still parses. Two paths declare it, and neither ever guesses:
+//
+//   opencode   the in-process engine knows its own harness, its serving package
+//              version and the surfaces it can actually drive (`OPENCODE_CAPABILITIES`)
+//   claude /   CLEO's Stop dispatcher names the harness in `CLEO_HOOK_PROVIDER`
+//   codex      (CLEO T13884). It knows nothing else, so version and capabilities
+//              stay null — the run says "not known on this path", never an empty
+//              array pretending to be a set
+//
+// Anything else is `unknown`. A transcript (a Stop payload) is data the harness
+// wrote; it never renames the harness. There is deliberately no second
+// convention: no `OCGOAL_HARNESS` variable and no `--harness` flag.
+//
+// The capability names are the seam vocabulary the adapter-seam goal (0.10.0)
+// formalises into a matrix; this goal declares the OpenCode set only. The list
+// is documented in `docs/research/harness-identity.md`.
+
+/** The harnesses this version names. `unknown` is a real answer, not a fallback. */
+export type HarnessName = "opencode" | "claude" | "codex" | "unknown"
+
+/** The identity a run records. Optional and additive: old runs never had one. */
+export type HarnessIdentity = {
+  name: HarnessName
+  /** The serving harness's own version, when that path knows it. */
+  version: string | null
+  /** What the harness can deliver here; null means "not known on this path". */
+  capabilities: string[] | null
+}
+
+/**
+ * What the OpenCode in-process engine can actually deliver. Each name is a
+ * surface this code base really drives:
+ *
+ *   start         admit a goal into a session (goal_start, owner-approved)
+ *   continuation  keep the agent working after a turn (session.execution.* → admit)
+ *   events        a live turn/usage event stream (not just a Stop-time notification)
+ *   tools         the agent calls the goal_* tools by name
+ *   forms         a native owner form in the composer (ask tool)
+ *   verifier      an independent verifier child session
+ *   tui           the in-process dashboard/manager UI
+ *   steering      an owner message reaches the run mid-turn
+ *   version       the harness reports its own serving version
+ *
+ * `transcript` is absent on purpose: OpenCode reports events, so the engine never
+ * reads a transcript to learn what happened.
+ */
+export const OPENCODE_CAPABILITIES: readonly string[] = ["start", "continuation", "events", "tools", "forms", "verifier", "tui", "steering", "version"]
+
+/** The identity the OpenCode engine records at goal start. */
+export function opencodeIdentity(version: string | null | undefined): HarnessIdentity {
+  return { name: "opencode", version: version ?? null, capabilities: [...OPENCODE_CAPABILITIES] }
+}
+
+/** CLEO's dispatcher sets this on the `cleo-goal tick` child (CLEO T13884). */
+export const CLEO_HOOK_PROVIDER = "CLEO_HOOK_PROVIDER"
+
+/**
+ * Map the dispatcher's provider id onto a harness name. Only the two values CLEO
+ * actually sets are mapped; everything else — including absent — is `unknown`.
+ * Nothing is inferred from the Stop payload or the transcript.
+ */
+export function harnessFromHookProvider(value: string | undefined): HarnessName {
+  switch ((value ?? "").trim()) {
+    case "claude-code":
+      return "claude"
+    case "codex":
+      return "codex"
+    default:
+      return "unknown"
+  }
+}
+
+/**
+ * The identity a Stop-dispatched tick records: the declared name only. CLEO does
+ * not tell the dispatcher the harness version or its capabilities, so they stay
+ * null rather than being invented from what the payload happens to contain.
+ */
+export function dispatcherIdentity(env: Record<string, string | undefined> = {}): HarnessIdentity {
+  return { name: harnessFromHookProvider(env[CLEO_HOOK_PROVIDER]), version: null, capabilities: null }
+}
+
+/** A recorded identity is usable only if it has the documented shape. */
+export function isHarnessIdentity(value: unknown): value is HarnessIdentity {
+  if (!value || typeof value !== "object") return false
+  const identity = value as Partial<HarnessIdentity>
+  return (
+    (identity.name === "opencode" || identity.name === "claude" || identity.name === "codex" || identity.name === "unknown") &&
+    (identity.version === null || typeof identity.version === "string") &&
+    (identity.capabilities === null || (Array.isArray(identity.capabilities) && identity.capabilities.every((c) => typeof c === "string")))
+  )
+}

package/src/engine/state.ts

@@ -2,6 +2,7 @@
 // model can report progress, claim, block, flag and wait; only the owner (or the
 // host acting on owner policy) can start, resume, pause, abort or approve.
 import type { Contract } from "../contract/types"
+import type { HarnessIdentity } from "./harness-identity"
 
 export type Status =
   | "running"
@@ -39,6 +40,12 @@ export type RunState = {
   title: string
   /** T061: copied from the contract at start so the registry/rebuild keep it. */
   priority?: "low" | "medium" | "high"
+  /**
+   * v0.9.5: which harness produced this run and what it can deliver. Optional
+   * and additive — a run written before this field existed has none and still
+   * parses as `version: 1`.
+   */
+  harness?: HarnessIdentity
   sessionID: string
   runId: string
   lock: string
@@ -83,13 +90,14 @@ export type RunState = {
   }
 }
 
-export function initialRun(contract: Contract, args: { sessionID: string; runId: string; lock: string; commit?: string; now?: number }): RunState {
+export function initialRun(contract: Contract, args: { sessionID: string; runId: string; lock: string; commit?: string; harness?: HarnessIdentity; now?: number }): RunState {
   const now = args.now ?? Date.now()
   return {
     version: 1,
     slug: contract.id,
     title: contract.title,
     ...(contract.priority ? { priority: contract.priority } : {}),
+    ...(args.harness ? { harness: args.harness } : {}),
     sessionID: args.sessionID,
     runId: args.runId,
     lock: args.lock,

package/src/engine/tick.ts

@@ -22,6 +22,7 @@ import { renderTailNote } from "../contract/render"
 import { budgetUse, setStatus, TERMINAL as TERMINAL_STATUSES, type RunState } from "./state"
 import { continuationTail, decide, type LoopLimits, type LoopSignals } from "./loop"
 import { recordTurn } from "./tick-record"
+import { dispatcherIdentity } from "./harness-identity"
 import type { VerifyOutcome } from "../verify/pipeline"
 
 /** The plugin's own defaults, so a tick agrees with the adapter unless overridden. */
@@ -49,6 +50,8 @@ export type TickDeps = {
   verify?: (state: RunState, contract: Contract, contractText: string) => Promise<VerifyOutcome>
   /** The raw harness Stop payload, when the harness passed one. */
   payload?: string
+  /** The dispatcher's environment. Defaults to the real one. */
+  env?: Record<string, string | undefined>
   readTranscript?: (path: string) => string | undefined
   limits?: LoopLimits
   cooldownMs?: number
@@ -130,6 +133,18 @@ export async function tick(deps: TickDeps): Promise<TickResult> {
 
   // ── 1. RECORD the turn, through OCG's own store, in the adapter's own shape.
   const record = recordTurn(live, contract, { fingerprint: deps.fingerprint ?? (() => undefined), ...(deps.payload ? { payload: deps.payload } : {}), ...(deps.readTranscript ? { readTranscript: deps.readTranscript } : {}), now })
+  // ── 1a. DECLARE the harness that produced this run, once. CLEO's dispatcher
+  // names it (`CLEO_HOOK_PROVIDER`); absent or unrecognised is `unknown`, never a
+  // guess from the payload. A run already carries its producer, so it is never
+  // renamed by a later tick.
+  const identity = dispatcherIdentity(deps.env ?? process.env)
+  if (!live.harness) {
+    live.harness = identity
+    deps.store.ledger(live.slug, { type: "harness", name: identity.name, version: identity.version, capabilities: identity.capabilities, source: "tick" })
+    log.push(`recorded harness ${identity.name}${identity.name === "unknown" ? " (no CLEO_HOOK_PROVIDER declared)" : ""}`)
+  } else if (live.harness.name !== identity.name && identity.name !== "unknown") {
+    log.push(`harness is already recorded as ${live.harness.name}; the dispatcher declared ${identity.name} - keeping the producer`)
+  }
   deps.store.ledger(live.slug, {
     type: "turn",
     turn: live.turn,

package/src/rpc.ts

@@ -2,6 +2,7 @@
 // function), so neither side needs @opencode/plugin at runtime.
 const anyObject = { type: "object", additionalProperties: true } as const
 import type { Handoff } from "./engine/state"
+import type { HarnessIdentity } from "./engine/harness-identity"
 import type { LaunchView } from "./engine/launches"
 export type { LaunchView } from "./engine/launches"
 // V2 RPC's schema adapter rejects regex patterns. Length is declared here;
@@ -120,6 +121,8 @@ export type GoalView = {
   /** T106: the tuple goal_manage accepts, so a caller never loses a round to
    * discovery after a generation change — key, runId, sessionID and lock. */
   target?: GoalTarget
+  /** v0.9.5: the harness that produced this run (absent on older runs). */
+  harness?: HarnessIdentity
   turn: number
   timeline: TimelineEntry[]
   activeMs: number

package/src/server/app.ts

@@ -12,6 +12,7 @@ import type { Contract } from "../contract/types"
 import { isHostCheck } from "../contract/types"
 import { GoalRpc, type GoalSummary, type GoalTarget, type GoalView, type ManageAction } from "../rpc"
 import { account, budgetUse, initialRun, isActive, isTerminal, modelCan, ownerCan, setStatus, type Handoff, type PendingKind, type RunState, type Status } from "../engine/state"
+import { isHarnessIdentity, opencodeIdentity } from "../engine/harness-identity"
 import { Store } from "../engine/store"
 import { Registry, byPriorityThenRecency } from "../engine/registry"
 import { LaunchStore, launchChoices, launchView, processAlive, type LaunchActivity, type LaunchRequest } from "../engine/launches"
@@ -329,7 +330,7 @@ export class GoalApp {
 
     const kept = this.store.keepCorruptRun(slug, text)
     const lastTurn = this.store.recent(slug, 5000).filter((e) => e.type === "turn" && typeof e.turn === "number").at(-1)
-    const state = initialRun(parsed.contract, { sessionID, runId, lock, ...(typeof start.commit === "string" ? { commit: start.commit } : {}) })
+    const state = initialRun(parsed.contract, { sessionID, runId, lock, ...(typeof start.commit === "string" ? { commit: start.commit } : {}), ...(isHarnessIdentity(start.harness) ? { harness: start.harness } : {}) })
     state.turn = Number(lastTurn?.turn ?? 0)
     for (const id of Object.keys(state.criteria)) {
       const recorded = this.store.recent(slug, 5000).findLast((e) => e.type === "criterion" && e.criterion === id) as any
@@ -560,6 +561,7 @@ export class GoalApp {
       runId: state.runId,
       sessionID: state.sessionID,
       lock: state.lock,
+      ...(state.harness ? { harness: state.harness } : {}),
       target: this.targetOf(state),
       turn: state.turn,
       timeline: this.timelineOf(state),
@@ -1838,7 +1840,7 @@ export class GoalApp {
         const current = this.load(slug, true)
         if ("error" in current || current.lock !== options.expectedLock) return "Refused: contract changed during launch rehearsal; no run created. Prepare a new review."
       }
-      const state = initialRun(contract, { sessionID, runId: newRunId(), lock, commit: headCommit(exec) })
+      const state = initialRun(contract, { sessionID, runId: newRunId(), lock, commit: headCommit(exec), harness: opencodeIdentity(this.packageVersion) })
       if (options.handoff) state.handoff = options.handoff
       state.fingerprint = fingerprint(exec)
       if (rehearsal.length) {
@@ -1851,7 +1853,7 @@ export class GoalApp {
       this.store.evidence(slug, state.runId, "contract", { lock, text })
       await Bun.write(join(this.store.dir(slug), "evidence", state.runId, "contract.yaml"), text)
       this.runs.set(sessionID, state)
-      this.store.ledger(slug, { type: "start", runId: state.runId, sessionID, source, lock, commit: state.base.commit, ...(options.decisionId ? { decisionId: options.decisionId } : {}) })
+      this.store.ledger(slug, { type: "start", runId: state.runId, sessionID, source, lock, commit: state.base.commit, ...(state.harness ? { harness: state.harness } : {}), ...(options.decisionId ? { decisionId: options.decisionId } : {}) })
       // T027 / v0.5.0: record the CLEO linkage and health (CLI-only). A project
       // with no CLEO CLI records nothing and behaves EXACTLY as before; a project
       // with the CLI gets an honest state, and nothing is ever installed here.
@@ -3224,7 +3226,7 @@ export class GoalApp {
       artifacts: this.artifacts,
       status: entry?.state?.status ?? "unknown",
       features: { server: entry?.features?.server === true, tui: entry?.features?.tui === true, rpc: entry?.features?.rpc === true },
-      ...(state ? { sessionID: state.sessionID, runId: state.runId, lock: state.lock } : {}),
+      ...(state ? { sessionID: state.sessionID, runId: state.runId, lock: state.lock, ...(state.harness ? { harness: state.harness } : {}) } : {}),
     }
     // T115: this is a READ-ONLY probe. It returns the runtime identity and
     // writes NOTHING under .opencode/goals, so no read can look like an agent

package/src/verify/artifact.ts

@@ -5,6 +5,7 @@
 import { createHash } from "node:crypto"
 import { lstatSync, readFileSync, readdirSync } from "node:fs"
 import { join } from "node:path"
+import type { HarnessIdentity } from "../engine/harness-identity"
 
 export type ArtifactHashes = Record<string, string>
 export type ArtifactSource = { type: string; target?: string; version?: string; outdated?: boolean; path?: string }
@@ -24,6 +25,8 @@ export type RuntimeProvenance = {
   sessionID?: string
   runId?: string
   lock?: string
+  /** v0.9.5: the harness serving this run, as the run recorded it. */
+  harness?: HarnessIdentity
 }
 
 const entrypoints = ["package.json", "server.ts", "tui.tsx", "rpc.ts"]