compoundingtech
diff --git a/‎README.md‎
Lines changed: 7 additions & 0 deletions b/‎README.md‎
Lines changed: 7 additions & 0 deletions
diff --git a/‎context/.decisions/0008-a-harness-is-a-record-not-an-enum-member.md‎
Lines changed: 117 additions & 0 deletions b/‎context/.decisions/0008-a-harness-is-a-record-not-an-enum-member.md‎
Lines changed: 117 additions & 0 deletions
diff --git a/‎src/agent-file.ts‎
Lines changed: 13 additions & 8 deletions b/‎src/agent-file.ts‎
Lines changed: 13 additions & 8 deletions
diff --git a/‎src/agent-spec.ts‎
Lines changed: 9 additions & 6 deletions b/‎src/agent-spec.ts‎
Lines changed: 9 additions & 6 deletions
diff --git a/‎src/command-table.ts‎
Lines changed: 7 additions & 1 deletion b/‎src/command-table.ts‎
Lines changed: 7 additions & 1 deletion
@@ -113,6 +113,13 @@ convoy is **declarative** (the Nomad model): **`add` declares** (writes an agent
 - `convoy pretrust <dir> [<dir>...] [--config-dir <path>]` — batch **pre-trust** agent working dirs in one atomic write, so a caller that spawns **multiple agents back-to-back** doesn't hit the workspace-trust race (see below). Call it once, with every dir, before the first `convoy add`. Config-dir-agnostic (writes the ambient `~/.claude.json`); pass `--config-dir` only for agents that will run under `CLAUDE_CONFIG_DIR`.
 - `convoy install-cli [--bin <dir>]` — symlink `convoy` + `st` + `pty` (from their sibling repos) onto your PATH (default `~/.local/bin`), **reliably + idempotently, without `npm link`** (the global-symlink footgun that once broke ding delivery network-wide). Run it the first time via `node <convoy-clone>/bin/convoy install-cli`; it verifies the links and prints the shell-specific PATH line if the dir isn't on PATH yet. Portable (macOS + Linux).
 - `convoy init [dir]` — create + wire a smalltalk network folder (ST_ROOT, bus layout, hooks).
+**Harness support tiers.** `claude` and `codex` are fully supported: convoy selects their account (via
+`CLAUDE_CONFIG_DIR` / `CODEX_HOME`), pre-trusts their workspace, runs a doctor checkup, and probes their
+auth. `opencode` and `pi` **launch** with correct, verified flags but are partial citizens — no account
+selection (neither harness has a config-relocation variable), no doctor checkup, no auth probe, no MCP
+transport. A green `convoy doctor` does not cover them. See
+[decision 0008](context/.decisions/0008-a-harness-is-a-record-not-an-enum-member.md).
+
 - `convoy doctor [--quick] [--full]` — the **setup-readiness suite**: proves your machine can do real agent work. A fast **preflight gate** (`st`/`pty` on PATH, bus round-trips, PTY_ROOT length, hooks discoverable + `/compact`-safe, personas present, and a **real signed-in auth probe** per installed harness — a tiny live call, because a credential can be present on disk but revoked, so a file check would pass while actually signed out) — `--quick` stops here — then the **readiness checks**, each spun in an isolated throwaway network that never touches your prod network (it snapshots prod pty sessions before/after and asserts zero delta): a tmp network stands up + tears down; inbox+ding delivery works end-to-end; agent state externalizes + is reconstructed after a cold restart; inbox processing stays exactly-once across a restart; and a CoS→supervisor→worker tree fixes a real bundled bug, graded held-out (the fix behaves + is mutation-valid, delegation is visible on the bus, only the worker commits). These use **thin deterministic stand-ins** for the two upper tiers — fast per-mechanism health. **`--full`** is the complementary **real-org proof**: your **real** chief-of-staff + supervisor + worker, hosted under `convoy up`, run the whole lifecycle autonomously end-to-end — hands-off bring-up (first-run interview pre-seeded away, dirs pre-trusted, no prompts), an autonomous CoS→supervisor→worker delegation chain visible on the bus, a mutation-valid graded worker fix, restart-continuity (a cold no-`--resume` restart reconstructs from externalized `now.md` state and *straddles* the restart), and a clean teardown that leaves prod **sessions, durable crons, and trust config** untouched. Run the default for fast mechanism health; run `--full` (opt-in — a real multi-agent run takes minutes) when you want the real-org assurance that "when *you* `convoy init` + `convoy up`, it works." Every check is self-cleaning; failures are named + localize to a gate.
 - `convoy ls [--live-only]` — list the convoy's members.
 - `convoy personas <status|install>` — the base personas convoy installs for roles. `init`/`add`/`cos` auto-install them if missing (footgun-proof setup); this is explicit control.
 
@@ -0,0 +1,117 @@
+# 0008 — A harness is a record of capabilities, not an enum member
+
+Status: accepted
+
+Supersedes the "widen the union" option rejected in
+[0005](0005-bin-replaces-the-harness-binary.md), and narrows that decision's scope
+rather than reversing it.
+
+## Context
+
+`Harness` was `"claude" | "codex"`. Two things were blocked on it.
+
+**Codex account selection.** Reported as "a codex agent has no way to select an
+account". This turned out to be mostly wrong: decision 0004 put credential
+selection in the spec's `env` block, and `env` is spread verbatim into the
+derived harness session, so `CODEX_HOME` already reached a codex agent. The
+missing half was that convoy did not *know* the config had moved. `configDir` —
+the projection of `env` that the imperative CLI and pre-trust both read — was
+hardcoded to `CLAUDE_CONFIG_DIR`. Three consequences, all silent:
+
+- `--config-dir` on a codex session set `CLAUDE_CONFIG_DIR`, which codex does not
+  read. The flag reported success and selected nothing; the agent ran as whatever
+  account was ambient.
+- A codex spec's `CODEX_HOME` never became `configDir`, so pre-trust seeded
+  `~/.codex/config.toml` while the agent read `$CODEX_HOME/config.toml`. codex's
+  `--dangerously-bypass-approvals-and-sandbox` does *not* skip the directory-trust
+  prompt, so the agent stalls on a dialog rather than failing.
+- `convoy pretrust` refused `--config-dir` for codex on the grounds that it
+  "applies only to claude". That was true of the implementation, not of codex.
+
+**opencode and pi could not be declared.** 0005 anticipated this and offered an
+escape hatch: set `bin` to the wrapper and `harness` to "the nearest
+CLI-compatible flavor", accepting that "a wrapper must accept the harness's
+flags."
+
+## Options
+
+**Keep the union closed; rely on `bin` (0005's answer).** Checked against the
+real binaries, "nearest compatible flavor" has no referent for these two:
+
+- opencode's positional argument is a **project path**. `exec opencode '<boot
+  prompt>'` does not pass a prompt opencode ignores — it asks opencode to start
+  in a directory named after the entire boot ritual. The prompt must ride
+  `--prompt`.
+- Neither opencode nor pi accepts `--permission-mode` or
+  `--dangerously-bypass-approvals-and-sandbox`.
+- `--model` is not portable: opencode wants `provider/model`, pi wants a pattern
+  plus `--provider`.
+
+A wrapper script could swallow the flags, but it cannot rescue a prompt that has
+already been consumed as a path. The escape hatch works for a wrapped *claude* or
+*codex* — which is what it was built for, and what dev3's CoS uses today — and
+not for a harness whose CLI is a different shape.
+
+**Add members to the union.** Adding a member was silent: exactly one site
+(`HARNESS_SESSION_KEY`) was typed tightly enough to fail the build. Every other
+branch was `if (harness === "codex") … else <the claude form>`, so a new harness
+would have been treated as claude everywhere — and `doctor`/`auth` kept their own
+*shadow* copies of the union, so they would not even have failed to compile.
+Verified on main: rendering an unlisted harness emits `[sessions.undefined]`.
+
+**Make a harness a record.**
+
+## Decision
+
+A harness is a `HarnessDescriptor` in one table (`src/harness.ts`): its pty
+session key, its config-relocation env var (`null` = it has none), whether it
+supports MCP, whether convoy can run a doctor checkup or an auth probe for it,
+and a function deriving its argument tail. `HARNESSES` is widened to
+`claude | codex | opencode | pi`.
+
+Every consumer reads the table. `doctor` and `auth` import the canonical type
+instead of shadowing it, and their per-harness records are `Partial` — because
+they *are* partial — so an unsupported harness is absent rather than defaulted
+into another harness's entry.
+
+`configDir` becomes "the harness's own config dir": `CLAUDE_CONFIG_DIR` for
+claude, `CODEX_HOME` for codex, and refused for a harness whose `configEnv` is
+`null`. `env` remains the general seam of 0004; `configDir` is the projection of
+it convoy needs as a single value.
+
+0005 is otherwise unchanged: `bin` still replaces only the binary name, and every
+flag is still derived. `bin` is additionally exposed on `convoy run`, which
+replaces the ad-hoc launcher aliases — those aliases *were* wrappers, so the path
+replacing them must be able to point at one.
+
+## Consequences
+
+- opencode and pi are **partial citizens, by declaration**. They launch with
+  correct flags. They get no account selection (neither has a config-relocation
+  variable, so convoy cannot select one and says so instead of accepting a
+  `--config-dir` that would do nothing), no doctor checkup, no auth probe, and no
+  MCP transport. `harnessLimitations()` derives this list from the table, so the
+  documentation of a limitation cannot drift from the limitation.
+- A green `convoy doctor` does **not** cover opencode or pi. This is a real
+  reduction in what a clean doctor run means, and is reported by name rather than
+  inferred.
+- pi's `--approve` trusts project-local files; it is **not** a tool-permission
+  bypass. A pi agent may still stall on a tool prompt where a claude or codex
+  agent under bypass would not.
+- Convoy now encodes flag opinions for harnesses it cannot test in CI — the cost
+  0005 named. It is bounded to one reviewable table, and the alternative was
+  encoding a *wrong* opinion (the claude branch) for them silently.
+- `permissionMode` does not reach opencode or pi. Convoy's posture is currently
+  the constant `bypassPermissions` for every agent, so nothing is lost today; a
+  future per-agent posture must not silently map onto `--auto` / `--approve`.
+- Adding the next harness is a data change that fails to typecheck until every
+  capability is decided.
+
+## Evidence
+
+- Flag surfaces read from `opencode 1.18.3 --help` and `pi 0.80.10 --help`, not
+  from documentation.
+- `src/harness.test.ts`. Tests marked `LOCK` pass on main and pin behavior that
+  was reported missing but was already present; every other test fails on main.
+  The six current defects were each reproduced against a clean `origin/main`
+  checkout before being fixed.
@@ -10,7 +10,8 @@ import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { stringify as tomlStringify } from "smol-toml";
 import { parseRole, type Role } from "./role.ts";
-import { isValidModel, type AgentSpec, type Harness, type Transport } from "./agent-spec.ts";
+import { isValidModel, type AgentSpec, type Transport } from "./agent-spec.ts";
+import { HARNESS_LIST, harnessDescriptor, isHarness, type Harness } from "./harness.ts";
 import { identityErrors, type IdentityContext } from "./identity.ts";
 import { asArray, decodeSpecText, formatOfPath, type SpecDoc, type SpecFormat } from "./spec-format.ts";
 
@@ -26,7 +27,8 @@ export interface AgentFile {
   host?: string;
   /** The repo/worktree the agent runs in — where render materializes the overlay. `--dir` overrides it. */
   workspace?: string;
-  /** claude | codex. Omit → claude. */
+  /** claude | codex | opencode | pi. Omit → claude. See src/harness.ts for what convoy supports per
+   *  harness — opencode and pi launch, but get no account selection, doctor checkup, or auth probe. */
   harness?: Harness;
   /** Per-agent model id (`claude --model <id>` / `codex --model <id>`). Omit → the harness default (today's
    *  behavior). Free-form (model ids churn) but charset-validated on parse — it lands in the launch command. */
@@ -141,7 +143,7 @@ export function parseAgentFile(text: string, format: SpecFormat = "toml", idCont
   if (!role) throw new Error(`invalid \`role\` "${roleRaw}" (want: chief-of-staff | supervisor | worker | technical-manager)`);
 
   const harnessRaw = str("harness");
-  if (harnessRaw !== undefined && harnessRaw !== "claude" && harnessRaw !== "codex") throw new Error(`invalid \`harness\` "${harnessRaw}" (want: claude | codex)`);
+  if (harnessRaw !== undefined && !isHarness(harnessRaw)) throw new Error(`invalid \`harness\` "${harnessRaw}" (want: ${HARNESS_LIST})`);
   const transportRaw = str("transport");
   if (transportRaw !== undefined && transportRaw !== "ding" && transportRaw !== "mcp") throw new Error(`invalid \`transport\` "${transportRaw}" (want: ding | mcp)`);
   const strategyRaw = str("strategy");
@@ -294,7 +296,9 @@ export function readAgentFile(path: string, idContext?: IdentityContext): AgentF
 /** Compile an AgentFile (+ its network + an optional workspace override) DOWN to the AgentSpec that the
  *  overlay writers consume. This is render's core mapping. Defaults: harness=claude, transport=ding; host →
  *  the host-prefix (null → this machine's short hostname); strategy=permanent → permanentOverride. `tier`
- *  is derived from role by the writers (v1), and `env` is not yet materialized — both carried forward-compat. */
+ *  is derived from role by the writers (v1) and carried forward-compat. `env` IS materialized: it is
+ *  carried onto the spec and spread into the derived harness session (see writePtyToml), which is what
+ *  makes `CODEX_HOME` — and any other harness's credential variable — work with no convoy change. */
 export function agentFileToSpec(af: AgentFile, opts: { networkRoot: string | null; workspace?: string | undefined }): AgentSpec {
   return {
     harness: af.harness ?? "claude",
@@ -306,10 +310,11 @@ export function agentFileToSpec(af: AgentFile, opts: { networkRoot: string | nul
     workingDir: opts.workspace ?? af.workspace ?? null,
     permanentOverride: af.strategy === "permanent" ? true : null,
     prefix: af.prefix ?? af.host ?? null,
-    // CLAUDE_CONFIG_DIR is CREDENTIAL SELECTION, and credentials ride in `env` — there is no separate
-    // `account` field to fall out of sync with it. Read it back out of `env` so the derived pty.toml and
-    // the spec agree by construction.
-    configDir: af.env?.["CLAUDE_CONFIG_DIR"] ?? null,
+    // `env` is the GENERAL credential seam (decision 0004) and is carried verbatim below; `configDir` is
+    // the narrower projection of it that the imperative CLI (`--config-dir`) and pre-trust both need as a
+    // single value. Read it back out of `env`, per harness, so the declaration and the derived pty.toml
+    // cannot disagree — and so a codex spec's CODEX_HOME reaches pre-trust the same way claude's does.
+    configDir: (harnessDescriptor(af.harness ?? "claude").configEnv && af.env?.[harnessDescriptor(af.harness ?? "claude").configEnv!]) || null,
     model: af.model ?? null,
     bin: af.bin ?? null,
     env: af.env ?? null,
 
@@ -5,13 +5,16 @@ import { existsSync, statSync } from "node:fs";
 import { hostname } from "node:os";
 import { baseFile } from "./personas.ts";
 import { permanentByRole, type PermissionMode, type Role } from "./role.ts";
+import { harnessDescriptor, HARNESS_SUFFIX_RE, type Harness } from "./harness.ts";
 
 // Closed enums as const ARRAYS with the type derived from them, so the CLI's `--transport`/`--harness`
 // completions can read the real list instead of retyping it (a type alone is not iterable at runtime).
 export const TRANSPORTS = ["ding", "mcp"] as const;
 export type Transport = (typeof TRANSPORTS)[number];
-export const HARNESSES = ["claude", "codex"] as const;
-export type Harness = (typeof HARNESSES)[number];
+// `Harness` and its capability table live in src/harness.ts — one record per harness, so adding one is a
+// data change that fails to typecheck until every field is decided. Re-exported here because this module
+// is the established import site for the spec vocabulary.
+export { HARNESSES, harnessDescriptor, isHarness, HARNESS_LIST, harnessLimitations, type Harness } from "./harness.ts";
 
 export interface AgentSpec {
   harness: Harness;
@@ -64,7 +67,7 @@ export function specPrefix(s: AgentSpec): string {
 }
 /** The agent's short name — the bus identity minus the harness suffix (`convoy-claude` → `convoy`). */
 export function agentShort(identity: string): string {
-  return identity.replace(/-(claude|codex)$/i, "");
+  return identity.replace(HARNESS_SUFFIX_RE, "");
 }
 /** The pinned pty session id for the claude session: `<prefix>.<agentShort>` (e.g. `silber.convoy`).
  *  The ding session appends `.ding`. Stable across respawns so ding + name refs never drift. */
@@ -140,11 +143,11 @@ export function preflight(s: AgentSpec, existing: string[]): Preflight {
   if (s.workingDir !== null && !isDir(s.workingDir)) {
     errors.push(`working directory does not exist: ${s.workingDir}`);
   }
-  if (s.harness === "codex" && s.transport === "mcp") {
-    warnings.push("codex has no MCP transport — it always runs ding-mode; ignoring --transport mcp");
+  if (!harnessDescriptor(s.harness).supportsMcp && s.transport === "mcp") {
+    warnings.push(`${s.harness} has no MCP transport — it always runs ding-mode; ignoring --transport mcp`);
   }
 
-  const effectiveTransport: Transport = s.harness === "codex" ? "ding" : s.transport;
+  const effectiveTransport: Transport = harnessDescriptor(s.harness).supportsMcp ? s.transport : "ding";
   const derived: [string, string][] = [
     ["harness", s.harness],
     ["identity", s.identity],
 
@@ -56,7 +56,9 @@ const IDENTITY_FLAG: FlagSpec = { name: "identity", desc: "Agent identity", kind
 const HARNESS_FLAG: FlagSpec = { name: "harness", desc: "Coding-agent harness", kind: "value", values: HARNESSES };
 const TRANSPORT_FLAG: FlagSpec = { name: "transport", desc: "Bus transport", kind: "value", values: TRANSPORTS };
 const PERSONA_FLAG: FlagSpec = { name: "persona", desc: "Persona file", kind: "value", takesPath: true };
-const CONFIG_DIR_FLAG: FlagSpec = { name: "config-dir", desc: "CLAUDE_CONFIG_DIR for the session", kind: "value", takesPath: true };
+// Not "CLAUDE_CONFIG_DIR" — the flag names the HARNESS's own config-relocation dir (CLAUDE_CONFIG_DIR for
+// claude, CODEX_HOME for codex), which is how an account is selected (decision 0004).
+const CONFIG_DIR_FLAG: FlagSpec = { name: "config-dir", desc: "Config dir for the session (selects the account)", kind: "value", takesPath: true };
 
 const NETWORK_POSITIONAL: PositionalSpec = { desc: "Network", dynamic: "networks" };
 const IDENTITY_POSITIONAL: PositionalSpec = { desc: "Agent identity", dynamic: "identities" };
@@ -164,6 +166,10 @@ export const COMMANDS: readonly CommandSpec[] = [
       PERSONA_FLAG,
       { name: "prefix", desc: "Session-id prefix (default: short hostname)", kind: "value" },
       CONFIG_DIR_FLAG,
+      // `--bin` on the ad-hoc path too: a deployment that wraps its harness wraps it for ad-hoc sessions
+      // as well, and `convoy run` is the replacement for exactly those launcher aliases. Without it, the
+      // ad-hoc path is the one place a convoy session escapes the deployment's boundary.
+      { name: "bin", desc: "Run this in place of the bare harness binary", kind: "value", takesPath: true },
       DRY_RUN_FLAG,
       { name: "force", desc: "Overwrite a foreign pty.toml in the workspace", kind: "bool" },
     ],