docks-kit 0.10.1 → 0.11.0

package/AGENTS.md

@@ -20,9 +20,9 @@ launcher can fall back to Bun source.
 | Path | Purpose |
 |------|---------|
 | `docks-kit` | CLI launcher: on supported hosts, runs the platform binary in `cli/dist/` only when its `--version` matches `package.json`, otherwise Bun-from-source (auto-installs Bun + `node_modules`). Unsupported hosts fail before source fallback. No-Bun recovery is the standalone platform release binary |
-| `cli/src/engine-native/` | EngineNative implementation for `sync`, `model`, `workflow`, and `toolchain`; idempotent, flag-gated for destructive reconciliation |
+| `cli/src/engine-native/` | EngineNative implementation for `sync`, `model`, and `toolchain`; idempotent, flag-gated for destructive reconciliation |
 | `cli/` | Effect-TS CLI + bundled docs topics |
-| `SoT/models.json` | Kit-verified model catalog plus the strict Docks workflow-role registry |
+| `SoT/models.json` | Kit-verified Claude and Codex model catalog |
 | `SoT/toolchain.json` | Toolchain floors manifest (verified pins consumed by EngineNative) |
 | `SoT/.claude/bin/` | Dependency-free Bun runtime programs for Claude's statusline, SessionStart, and Notification |
 | `install.sh` | Global installer |
@@ -42,8 +42,6 @@ Codex SoT notes:
 - `SoT/.codex/plugins/marketplace.json` deploys to Codex's personal marketplace path at `~/.agents/plugins/marketplace.json`; when the `codex` CLI is available, sync reruns `codex plugin add <plugin@marketplace>` for enabled SoT plugins so stale cached installs are refreshed.
 - `docks-kit status` verifies Session Relay only through the supported `codex plugin list --json` inventory. `ready` means installed and enabled for a newly started Codex session; it is not evidence about an old process, lifecycle state, receive-path health, or worker quiescence. The global prompt SoTs carry the owner's standing authorization for Docks cross-company plan review, which never overrides host or platform denial.
 - Claude and Codex sync call `sessionRelayCli.ts ensureSessionRelayCli` immediately before their plugin passes. It installs the exact source-pinned precompiled command at `~/.local/bin/session-relay` for Linux/macOS x64/arm64 only, requires committed digest = same-release `SHA256SUMS` row = downloaded bytes, smoke-tests the staged version, and atomically replaces the stable path. `agents`-only sync never enters this boundary. The four pinned production digests correspond to the stable `session-relay--v0.12.0` assets and its `SHA256SUMS`.
-- Both global prompt SoTs carry one byte-identical compact `Docks-workflow-models:` record. Root `--model-orchestrator` / `--model-reviewer` / `--model-implementer` / review-bound flags update only that deployed record; `docks-kit models workflow` lists the closed selectors, and a flag-less sync restores defaults.
-- Codex workflow selectors use the closed `<tool>:<model>@<effort>[+fast]` routing grammar. Fast is intentionally absent from the global SoT: no suffix means Standard and keeps the backward-compatible schema-1 record; `+fast` emits a schema-2 candidate with `service_tier: "fast"`. Docks and Session Relay consumers must explicitly launch unsuffixed Codex roles with the default service tier so a user's global Fast preference cannot leak into workflows.
 - The `codex` CLI binary is upstream-owned, not kit-owned. The official standalone installer keeps package metadata under `$CODEX_HOME/packages/standalone` and places the `codex` symlink in `~/.local/bin` by default; sync only warns with a download-then-run installer command when the CLI is missing. Existing installs can self-update with `codex update`; npm and Homebrew remain upstream alternatives.
 - Neither global prompt SoT imports `@RTK.md`; Claude uses the hook-backed RTK integration, while Codex has no kit-managed RTK integration.
 - Claude runtime settings are an authoring template with sentinels. `claudeRuntime.ts` materializes absolute Bun/script paths only after the shared `bun.ts` bootstrap is ready; `claudeSync.ts` writes all runtime assets before atomically committing settings, then prunes the legacy shell scripts and Stop hook. Native `rate_limits` is the sole quota source, so jq/curl/OAuth caches are not runtime dependencies. A missing Bun defers only this cutover and preserves legacy pointers/files.
@@ -93,11 +91,9 @@ When a kit-mechanic skill, its `references/`, or a wrapper agent (`.claude/agent
 
 ## Plans
 
-<constraint>
-Multi-commit work plans live in `docs/plans/active/` (status is a frontmatter field) and `docs/plans/finished/` (archive). Every plan file is a complete cold-handoff document — goal, context & rationale, environment & how-to-run, steps with exact paths, executable acceptance criteria, and a binary cold-handoff checklist — so any agent (or a weaker model) can pick one up cold without guessing. Skills handle every operation: `plan-init` (bootstrap/migrate), `plan-manager` (list/show/start/block/ship/new, auto-commit on transition, self-review on draft), `plan-review` (verification). Trigger by natural language or the matching `plan-*` skill. `active/` is multi-occupancy.
-</constraint>
+Canonical plans live in `docs/plans/active/`; status is frontmatter and `docs/plans/finished/` is terminal. Exactly three skills are live: `plan-workspace` maintains the workspace; main-context `plan-manager` classifies, drafts, reviews, repairs once, executes, verifies, and archives; internal `plan-reviewer` returns read-only `PlanReviewV1` evidence from one immutable bundle. Only the reviewer has Claude/Codex wrappers.
 
-The full convention (frontmatter schema, body sections, one-pass local checklist self-review, schema-5 role `primary`, GPT-5.6-sol/high/`service_tier:"default"` (Standard) → Fable/high → Opus/xhigh availability-only fallback, exact eight-criterion evidence checklist, primary-role waivers, one full round plus at most one accepted-blocker repair, open questions, and age tokens) lives in `docs/plans/AGENTS.md`. `docs/plans/CLAUDE.md` is a one-line `@AGENTS.md` import for Claude Code's nested discovery. If `.codex/agents/plan-manager.toml` and `.codex/agents/plan-review.toml` exist, Codex may use them for explicit subagent delegation; otherwise run the matching `plan-*` skill inline.
+Current plans carry one compact-JCS `Plan-run: PlanRunV1` record. Schemas 1–6 are historical validation/quarantine only and never authorize current dispatch or external effects. Persisted requested effects are intent, not authority; any probe, production access, publish, push, release, or deploy requires matching live authority from the exact current-user request. The full contract lives in `docs/plans/AGENTS.md`.
 
 Distinct from per-tool **Open Concerns** sections (wait-on-upstream
 blockers tied to a vendor shipping a fix — these live inside the per-tool

package/README.md

@@ -43,7 +43,7 @@ RTK/Bun download boundaries, not as a global sync prerequisite.
 docks-kit sync [claude] [codex] [agents]   deploy the SoT (default: all three)
 docks-kit update [--no-sync]               self-update the kit (autodetects checkout vs global install), then sync
 docks-kit model <claude|codex> [value]     get/set the DEPLOYED model (TTY picker)
-docks-kit models [claude|codex|workflow]   model and workflow-role catalogs (`--json`)
+docks-kit models [claude|codex]            model catalogs (`--json`)
 docks-kit toolchain [check|ensure <tool>]  verified-version floors for external tools
 docks-kit status [--json]                  deployed-vs-SoT drift + toolchain + counts
 docks-kit plugins list [--json]            enabledPlugins tri-state vs installed
@@ -76,23 +76,6 @@ golden-regression coverage for dry-run output, mutation snapshots, and argv logs
 and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
 (includes the old→new rename table for the pre-CLI `sync.sh` flags).
 
-### Docks workflow roles (root flags)
-
-| Flag | Effect |
-|------|--------|
-| `--model-orchestrator=<selector>` | Override the Docks orchestrator candidate/profile |
-| `--model-reviewer=<selector>` | Override the Docks reviewer candidate/profile |
-| `--model-implementer=<selector>` | Override the Docks implementer candidate/profile |
-| `--review-min-score=<0..100>` | Override the completion-review target |
-| `--review-max-rounds=<1..10>` | Bound completion-review batches |
-
-Selectors are strict `profile:<name>` or `<tool>:<model>@<effort>[+fast]`
-values from `docks-kit models workflow`; `+fast` is Codex-only. A selector
-without `+fast` means Standard, while `+fast` writes a schema-2 candidate with
-`service_tier: "fast"`. These root flags update only the identical compact record
-in `~/.claude/CLAUDE.md` and `~/.codex/AGENTS.md`; omitted fields retain their
-current valid values, while a later flag-less sync restores all defaults.
-
 ## How syncing works
 
 - **Additive by default** — user-only settings keys, plugins, and skills
@@ -112,7 +95,7 @@ current valid values, while a later flag-less sync restores all defaults.
   command. The four production digests are pinned for the stable
   `session-relay--v0.12.0` assets and match the same-release `SHA256SUMS`.
 - **Model catalog** — `SoT/models.json` is the research-verified source for
-  model validation, listings, pickers, and the Docks workflow-role registry.
+  model validation, listings, and pickers.
 - **Claude runtime** — sync materializes three dependency-free Bun `.mjs`
   programs for statusline, SessionStart, and Notification. Quota display uses
   Claude's native `rate_limits`; there is no OAuth fetch, shared usage cache,
@@ -126,7 +109,7 @@ current valid values, while a later flag-less sync restores all defaults.
 | `SoT/.claude/` | Claude Code SoT (settings template, Bun runtime programs, CLAUDE.md) |
 | `SoT/.codex/` | Codex SoT (config.toml, rules, AGENTS.md, marketplace) |
 | `SoT/.agents/` | Universal-skill manifest |
-| `SoT/models.json` | Kit-verified model and Docks workflow-role catalog |
+| `SoT/models.json` | Kit-verified Claude and Codex model catalog |
 | `SoT/toolchain.json` | Verified-version floors |
 | `cli/src/engine-native/` | EngineNative sync/model/toolchain implementation |
 | `cli/src/generated/sotPayload.ts` | Generated in-memory payload used by standalone and npm installs |

package/cli/docs/flags.md

@@ -40,26 +40,6 @@ Bare model, effort, or advisor modifiers print the relevant valid-value catalog
 and exit 2. A modifier for a target not selected by the positional arguments is
 ignored with a warning; Claude modifiers never touch Codex config and vice versa.
 
-## Docks workflow root flags
-
-These flags belong at the root (`docks-kit --model-reviewer=...`), not after
-`sync`. They update only the shared deployed workflow record.
-
-| Flag | Accepted value |
-|------|----------------|
-| `--model-orchestrator=<selector>` | `profile:<name>` or `<tool>:<model>@<effort>[+fast]` |
-| `--model-reviewer=<selector>` | same strict selector grammar |
-| `--model-implementer=<selector>` | same strict selector grammar |
-| `--review-min-score=<n>` | base-10 integer `0..100` |
-| `--review-max-rounds=<n>` | base-10 integer `1..10` |
-
-Use `docks-kit models workflow [--json]` for the closed registry. Bare, empty,
-unknown, or malformed values print that helper and exit 2 before either prompt
-file changes. `+fast` is accepted only on Codex exact targets and writes
-`service_tier: "fast"` in workflow record schema 2. Without `+fast`, the role is
-Standard and the record remains schema 1 unless another role is Fast. Shell
-quotes are optional but recommended around selectors containing `+fast`.
-
 ## Renamed legacy flags (pre-CLI sync.sh)
 
 Old flags exit with a rename hint — there is no compat behavior.

package/cli/docs/models.md

@@ -31,35 +31,8 @@ docks-kit models claude --json    # machine-readable
 docks-kit model claude            # current deployed + SoT + picker (TTY)
 docks-kit model claude opus       # per-machine override from the Fable SoT
 docks-kit sync claude --claude-model=opus   # same, as part of a sync
-docks-kit models workflow             # Docks workflow profiles and defaults
-docks-kit models workflow --json      # closed machine-readable registry
 ```
 
-## Docks workflow-role registry
-
-The `workflow` section is strict even though ordinary tool-model modifiers are
-forward-compatible. It accepts only known `profile:<name>` values or exact
-`<tool>:<model>@<effort>[+fast]` targets whose model and effort both appear in
-the catalog. `+fast` is accepted only for Codex exact targets. The defaults are:
-
-- orchestrator: `profile:claude-best`, ordered as `claude:fable@high` then
-  `claude:opus@xhigh`;
-- reviewer and implementer: `codex:gpt-5.6-sol@high`;
-- review minimum score 90 and maximum 3 rounds.
-
-`claude:best@high` is Claude's native one-model alias. It is deliberately not
-the same as the Docks-managed `profile:claude-best` candidate chain.
-Availability is `checked_when_used`: Docks classifies each launch attempt;
-docks-kit neither probes providers nor promises provider-wide fallback.
-
-The default and every unsuffixed selector emit the backward-compatible schema-1
-record with no service-tier field; absence means Standard. A `+fast` selector
-promotes the complete record to schema 2 and adds `service_tier: "fast"` only to
-the selected Codex candidate. Replacing the last Fast selector with an
-unsuffixed selector demotes the record back to schema 1. Docks and Session Relay
-must support schema 2 before `+fast` is deployed, and must explicitly select the
-default tier for unsuffixed roles so global Codex configuration cannot leak in.
-
 ## Advisor pairing note (Claude)
 
 The SoT ships `model: fable` with advisor off (`advisorModel` unset).

package/cli/docs/modifiers.md

@@ -33,13 +33,6 @@ owns that key for the run: `on` writes `fable`; `off` and `default` delete it.
 Codex has no advisor modifier because its documented config has no advisor
 setting; `review_model` applies only to `/review`.
 
-Codex Fast mode is intentionally not a global SoT default or per-machine
-modifier. It is role-scoped through the root workflow flags: append `+fast` to a
-Codex exact selector to emit `service_tier: "fast"` in record schema 2. Without
-the suffix, the role means Standard and emits no tier field. Docks and Session
-Relay consumers must map that absence to an explicit default-tier process
-override rather than inherit a user's global Fast preference.
-
 ## Standalone get/set (no full sync)
 
 ```
@@ -52,32 +45,6 @@ docks-kit model codex gpt-5.5     # codex flavor
 The set path calls the same engine functions as the sync flags —
 one implementation, two entry points.
 
-## Workflow-role overrides (root, no full sync)
-
-The root workflow flags are deployed modifiers for Docks rather than one tool:
-
-```text
-docks-kit --model-orchestrator=profile:claude-best \
-  --model-reviewer="codex:gpt-5.6-sol@high+fast" \
-  --model-implementer=codex:gpt-5.6-sol@high \
-  --review-min-score=80 --review-max-rounds=5
-```
-
-They atomically write one byte-identical complete record to
-`~/.claude/CLAUDE.md` and `~/.codex/AGENTS.md`. Omitted fields retain the
-current valid record; a missing side is repaired. Invalid or conflicting state
-stops before mutation, a repeated request is a no-op, and failure on the second
-atomic write restores both snapshots. A later flag-less sync restores the
-embedded defaults. Start fresh sessions after changing the record.
-
-Selectors are strict `profile:<name>` or `<tool>:<model>@<effort>[+fast]`
-entries from `docks-kit models workflow`. `+fast` is Codex-only and quotes are
-optional; its absence means Standard. `profile:claude-best` is the ordered Docks
-Fable-high then Opus-xhigh chain; `claude:best@high` is instead Claude's native
-single-model alias. Docks checks each candidate when used—there is no docks-kit
-provider preflight. Install schema-2 support in Docks and Session Relay before
-using a Fast selector.
-
 ## Sticky opt-ins are NOT modifiers
 
 `--claude-plugin=<name>` installs+enables an optional plugin and it STAYS

package/cli/src/commands/models.ts

@@ -2,10 +2,9 @@ import { Args, Command, Options } from "@effect/cli"
 import { Console, Effect, Option } from "effect"
 import { bail } from "../engine"
 import { modelCatalog, type Tool } from "../manifests"
-import { workflowCatalog, workflowRegistryJson } from "../workflowModels"
 
 const tool = Args.text({ name: "tool" }).pipe(
-  Args.withDescription("claude | codex | workflow (omit for both tool catalogs)"),
+  Args.withDescription("claude | codex (omit for both tool catalogs)"),
   Args.optional
 )
 const json = Options.boolean("json").pipe(
@@ -25,11 +24,8 @@ const renderTool = (t: Tool) =>
 export const modelsCommand = Command.make("models", { tool, json }, (config) =>
   Effect.gen(function* () {
     const requested = Option.getOrUndefined(config.tool)
-    if (requested === "workflow") {
-      return yield* Console.log(config.json ? workflowRegistryJson() : workflowCatalog())
-    }
     if (requested !== undefined && requested !== "claude" && requested !== "codex") {
-      return yield* bail(`Unknown tool '${requested}' (valid: claude, codex, workflow)`)
+      return yield* bail(`Unknown tool '${requested}' (valid: claude, codex)`)
     }
     const tools: Array<Tool> = requested !== undefined ? [requested as Tool] : ["claude", "codex"]
 
@@ -46,5 +42,5 @@ export const modelsCommand = Command.make("models", { tool, json }, (config) =>
     )
   })
 ).pipe(
-  Command.withDescription("List kit-verified tool models or the Docks workflow role registry (SoT/models.json).")
+  Command.withDescription("List kit-verified Claude and Codex models (SoT/models.json).")
 )

package/cli/src/engine-native/claudeSync.ts

@@ -31,7 +31,6 @@ import { ExitError } from "./parseArgs"
 import { mergeSettings, reconcileSettings } from "./settings"
 import { ensure, field } from "./toolchain"
 import { payloadBytes, payloadDisplayPath, payloadText } from "../payload"
-import { renderDefaultWorkflowInstructions } from "./workflowDeploy"
 import { ensureSessionRelayCli } from "./sessionRelayCli"
 
 export type ClaudeRuntimeState =
@@ -207,7 +206,7 @@ function syncClaudeMd(ctx: Ctx, claudeDir: string): void {
     return
   }
 
-  const source = renderDefaultWorkflowInstructions(payloadText("SoT/.claude/CLAUDE.md"))
+  const source = payloadText("SoT/.claude/CLAUDE.md")
   if (writeTextIfChanged(p(claudeDir, "CLAUDE.md"), source)) {
     change("CLAUDE.md synced")
   } else {

package/cli/src/engine-native/codexSync.ts

@@ -12,7 +12,6 @@ import type { Ctx } from "./index"
 import { compareCodepoints, isObject, jqStringify, parseJson, type Json } from "./jq"
 import { sessionRelayReadiness } from "./sessionRelayReadiness"
 import { payloadBytes, payloadDisplayPath, payloadPaths, payloadText, type PayloadPath } from "../payload"
-import { renderDefaultWorkflowInstructions } from "./workflowDeploy"
 import { ensureSessionRelayCli } from "./sessionRelayCli"
 
 export function codexSync(ctx: Ctx): void {
@@ -26,7 +25,7 @@ export function codexSync(ctx: Ctx): void {
   syncCodexModel(ctx, ctx.codexModel)
   syncCodexEffort(ctx, ctx.codexEffort)
   syncRules(ctx, payloadPaths("SoT/.codex/rules/"), p(codexDir, "rules"))
-  syncAgentsMd(ctx, renderDefaultWorkflowInstructions(payloadText("SoT/.codex/AGENTS.md")), p(codexDir, "AGENTS.md"))
+  syncAgentsMd(ctx, payloadText("SoT/.codex/AGENTS.md"), p(codexDir, "AGENTS.md"))
   syncMarketplace(ctx, payloadText("SoT/.codex/plugins/marketplace.json"), p(ctx.agentsDir, "plugins", "marketplace.json"))
   removeLegacyDocksMarketplace(ctx, userConfig)
   ensureSessionRelayCli(ctx)

package/cli/src/engine-native/index.ts

@@ -15,8 +15,7 @@ import { claudeNextSteps, claudeSummary, claudeSync } from "./claudeSync"
 import { codexNextSteps, codexSummary, codexSync } from "./codexSync"
 import { skillsNextSteps, skillsSummary, skillsSync } from "./skillsSync"
 import { modeModel, modeToolchain } from "./modes"
-import { ExitError, parseArgs, parseWorkflowArgs, printWorkflowUsage, validateModifierFlags } from "./parseArgs"
-import { deployWorkflowOverrides } from "./workflowDeploy"
+import { ExitError, parseArgs, validateModifierFlags } from "./parseArgs"
 
 export type ModifierFlag =
   | "--claude-model"
@@ -127,18 +126,6 @@ function engineSync(ctx: Ctx, args: ReadonlyArray<string>): number {
   return 0
 }
 
-function engineWorkflow(ctx: Ctx, args: ReadonlyArray<string>): number {
-  try {
-    const overrides = parseWorkflowArgs(ctx, args)
-    deployWorkflowOverrides(ctx, overrides)
-    return 0
-  } catch (error) {
-    if (error instanceof ExitError) throw error
-    printWorkflowUsage(ctx)
-    ctx.services.logger.err(error instanceof Error ? error.message : String(error))
-    throw new ExitError(2)
-  }
-}
 
 export function runEngineNative(argv: ReadonlyArray<string>, services?: EngineServices): number {
   let ctx!: Ctx
@@ -165,8 +152,6 @@ export function runEngineNative(argv: ReadonlyArray<string>, services?: EngineSe
         return modeModel(ctx, argv.slice(1))
       case "toolchain":
         return modeToolchain(ctx, argv.slice(1))
-      case "workflow":
-        return engineWorkflow(ctx, argv.slice(1))
       case "sync":
         return engineSync(ctx, argv.slice(1))
       default:

package/cli/src/engine-native/parseArgs.ts

@@ -16,11 +16,6 @@ import {
   isEffortModifierValue
 } from "../efforts"
 import { printModels, validateClaudeModel, validateCodexModel } from "./models"
-import {
-  buildWorkflowRecord,
-  workflowCatalog,
-  type WorkflowOverrides
-} from "../workflowModels"
 
 export class ExitError extends Error {
   constructor(readonly code: number) {
@@ -268,64 +263,6 @@ function printCatalog(ctx: Ctx, catalog: string): void {
   for (const line of catalog.split("\n")) ctx.services.logger.echo(line)
 }
 
-const WORKFLOW_FLAGS = {
-  "--model-orchestrator": "orchestrator",
-  "--model-reviewer": "reviewer",
-  "--model-implementer": "implementer",
-  "--review-min-score": "minimumScore",
-  "--review-max-rounds": "maxRounds"
-} as const satisfies Readonly<Record<string, keyof WorkflowOverrides>>
-
-function workflowUsage(ctx: Ctx): void {
-  printCatalog(ctx, workflowCatalog())
-  ctx.services.logger.echo("")
-  ctx.services.logger.echo("Workflow override flags:")
-  ctx.services.logger.echo("  --model-orchestrator=<profile:name|tool:model@effort[+fast]>")
-  ctx.services.logger.echo("  --model-reviewer=<profile:name|tool:model@effort[+fast]>")
-  ctx.services.logger.echo("  --model-implementer=<profile:name|tool:model@effort[+fast]>")
-  ctx.services.logger.echo("  --review-min-score=<0..100>")
-  ctx.services.logger.echo("  --review-max-rounds=<1..10>")
-}
-
-export function parseWorkflowArgs(ctx: Ctx, args: ReadonlyArray<string>): WorkflowOverrides {
-  const overrides: Partial<Record<keyof WorkflowOverrides, string>> = {}
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index] ?? ""
-    if (arg === "-h" || arg === "--help") {
-      workflowUsage(ctx)
-      throw new ExitError(0)
-    }
-
-    const equals = arg.indexOf("=")
-    const flag = equals === -1 ? arg : arg.slice(0, equals)
-    const key = WORKFLOW_FLAGS[flag as keyof typeof WORKFLOW_FLAGS]
-    if (key === undefined) throw new Error(`Unknown workflow arg: ${arg}`)
-
-    let value: string
-    if (equals !== -1) {
-      value = arg.slice(equals + 1)
-    } else {
-      const next = args[index + 1]
-      if (next === undefined || next.startsWith("--")) {
-        throw new Error(`${flag} requires a value: ${flag}=<value>`)
-      }
-      value = next
-      index += 1
-    }
-    if (value === "") throw new Error(`${flag} requires a value: ${flag}=<value>`)
-    overrides[key] = value
-  }
-
-  if (Object.keys(overrides).length === 0) {
-    throw new Error("At least one workflow override flag is required")
-  }
-  buildWorkflowRecord(overrides)
-  return overrides
-}
-
-export function printWorkflowUsage(ctx: Ctx): void {
-  workflowUsage(ctx)
-}
 
 export function validateModifierFlags(ctx: Ctx): void {
   const { err, warn } = ctx.services.logger

package/cli/src/engine-native/sessionRelayCli.ts

@@ -16,9 +16,7 @@ import type { Ctx } from "./index"
 import { ExitError } from "./parseArgs"
 import { payloadText } from "../payload"
 
-const VERSION = "0.12.0"
 const REPOSITORY = "DocksDocks/docks"
-const TAG = "session-relay--v0.12.0"
 const PLUGIN_ID = "session-relay@docks"
 const INSTALL_PATH = "~/.local/bin/session-relay"
 const TARGETS = [
@@ -33,11 +31,11 @@ export type SessionRelayTarget = typeof TARGETS[number]
 export interface SessionRelayManifest {
   readonly kind: "managed-release"
   readonly policy: "exact"
-  readonly verified: typeof VERSION
+  readonly verified: string
   readonly repository: typeof REPOSITORY
-  readonly tag: typeof TAG
+  readonly tag: string
   readonly plugin_id: typeof PLUGIN_ID
-  readonly plugin_version: typeof VERSION
+  readonly plugin_version: string
   readonly install_path: typeof INSTALL_PATH
   readonly assets: Readonly<Record<SessionRelayTarget, string>>
 }
@@ -83,14 +81,18 @@ export function parseSessionRelayManifest(text: string): SessionRelayManifest {
     ["kind", "policy", "verified", "repository", "tag", "plugin_id", "plugin_version", "install_path", "assets"],
     "Session Relay manifest"
   )
+  const version = value["verified"]
+  if (typeof version !== "string" || !/^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/.test(version)) {
+    throw new Error("Session Relay manifest verified must be a canonical stable SemVer core")
+  }
   const expected = {
     kind: "managed-release",
     policy: "exact",
-    verified: VERSION,
+    verified: version,
     repository: REPOSITORY,
-    tag: TAG,
+    tag: `session-relay--v${version}`,
     plugin_id: PLUGIN_ID,
-    plugin_version: VERSION,
+    plugin_version: version,
     install_path: INSTALL_PATH
   } as const
   for (const [key, wanted] of Object.entries(expected)) {
@@ -132,9 +134,9 @@ function trimOneLineEnding(text: string): string {
   return text
 }
 
-function exactVersion(ops: SessionRelayInstallOps, path: string): boolean {
+function exactVersion(ops: SessionRelayInstallOps, path: string, version: string): boolean {
   const result = ops.runVersion(path)
-  return result.ok && trimOneLineEnding(result.stdout) === `session-relay ${VERSION}`
+  return result.ok && trimOneLineEnding(result.stdout) === `session-relay ${version}`
 }
 
 function selectedChecksum(text: string, assetName: string): string {
@@ -182,7 +184,7 @@ export function installSessionRelayCli(
   }
 
   const stable = join(input.home, ".local", "bin", "session-relay")
-  if (existsSync(stable) && exactVersion(ops, stable)) return
+  if (existsSync(stable) && exactVersion(ops, stable, manifest.verified)) return
 
   const parent = dirname(stable)
   try {
@@ -221,13 +223,15 @@ export function installSessionRelayCli(
     } catch (error) {
       fail(input, `Failed to chmod staged Session Relay CLI: ${error instanceof Error ? error.message : String(error)}`)
     }
-    if (!exactVersion(ops, stage)) fail(input, `Staged Session Relay CLI did not report exact version session-relay ${VERSION}`)
+    if (!exactVersion(ops, stage, manifest.verified)) {
+      fail(input, `Staged Session Relay CLI did not report exact version session-relay ${manifest.verified}`)
+    }
     try {
       ops.rename(stage, stable)
     } catch (error) {
       fail(input, `Failed to atomically replace Session Relay CLI: ${error instanceof Error ? error.message : String(error)}`)
     }
-    input.log(`Session Relay CLI ready (${VERSION})`)
+    input.log(`Session Relay CLI ready (${manifest.verified})`)
   } finally {
     try {
       rmSync(stage, { force: true })