@ccmsg/cli 0.2.13 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccmsg/cli",
-  "version": "0.2.13",
+  "version": "0.3.1",
   "description": "The ccmsg daemon, CLI and agent plugins for one instance (= one config home)",
   "license": "MIT",
   "author": "kawaz",
@@ -20,7 +20,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ccmsg/protocol": "1.9.0"
+    "@ccmsg/protocol": "1.10.0"
   },
   "devDependencies": {
     "@types/bun": "^1.3.0",

package/src/cli.ts

@@ -9,6 +9,7 @@ import {
   connect,
   expectedInstances,
   follow,
+  harnessFor,
   idOf,
   labelled,
   list as listInstances,
@@ -23,10 +24,23 @@ import {
   type Target,
   targetFor,
 } from "./daemon/index.ts";
-import { join } from "node:path";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { currentSession, DEFAULT_HARNESS, HARNESS, HARNESSES, isHarness } from "./harness/index.ts";
+
+/** The variables a session is named by, for the help and for the message a
+ * command answers with when it finds none of them. */
+const SESSION_ENV = HARNESSES.flatMap((harness) => [...HARNESS[harness].sessionEnv]);
 import { hookEvent, type StatedMeta, statedMeta } from "./greeting/index.ts";
-import { isRunning, resolveConfigHome, resolvePaths, start } from "./instance/index.ts";
 import {
+  isRunning,
+  resolveConfigHome,
+  resolvePaths,
+  resolvePathsFor,
+  start,
+} from "./instance/index.ts";
+import {
+  type Agent,
   AGENTS,
   install,
   type Outcome,
@@ -36,6 +50,16 @@ import {
 import { type Run, runCommand, serviceFor } from "./service/index.ts";
 import { VERSION } from "./version.ts";
 
+/** The session this process runs inside, as its environment says (§3.8).
+ *
+ * One reading for every command that speaks as a session: which harness
+ * claimed the process settles both who the sender is and which instance it
+ * reaches, and a command that took the two from different places could greet
+ * one instance as a session of the other. */
+function ownSid(): string | undefined {
+  return currentSession(process.env)?.sid;
+}
+
 /** Where a hook event is read from. Named for the same reason a speech binary
  * is: a test drives the two commands a harness fires without a standard input
  * of its own to write to. */
@@ -117,8 +141,14 @@ const ROOT: Command = {
         {
           name: "add",
           summary: "共通 config の instances[] に足し、監督者が居れば起こさせる",
-          usage: "ccmsg daemon add <dir>",
-          run: (args) => added(args[0]),
+          usage: "ccmsg daemon add <dir> [--harness <種別>]",
+          options: [
+            [
+              "--harness <種別>",
+              `config home が動かすもの: ${HARNESSES.join(" | ")} (既定 ${DEFAULT_HARNESS})`,
+            ],
+          ],
+          run: (args) => added(args),
         },
         {
           name: "remove",
@@ -261,7 +291,10 @@ const ROOT: Command = {
           name: "install",
           summary: "そのエージェントに ccmsg のプラグインを入れる",
           usage: "ccmsg plugin install <agent>",
-          options: [["", "開いているセッションには /reload-plugins で反映される"]],
+          options: [
+            ["claude", "開いているセッションには /reload-plugins で反映される"],
+            ["codex", "config home に直接置く。hook は codex 側で trust してから効く"],
+          ],
           run: (args) => plugin("install", args[0]),
         },
         {
@@ -286,7 +319,7 @@ const ROOT: Command = {
       options: [
         ["--all", "mesh 越しの instance が言っている分も含める"],
         ["--json", "JSON で答える (既定、この CLI は常に JSON で答える)"],
-        ["--sid <sid>", "自分のセッション ID (既定は CLAUDE_CODE_SESSION_ID)"],
+        ["--sid <sid>", `自分のセッション ID (既定は ${SESSION_ENV.join(" / ")})`],
       ],
       env: sessionEnv(),
       run: (args) => peers(args),
@@ -306,7 +339,7 @@ const ROOT: Command = {
       name: "post",
       summary: "別のセッションへメッセージを送る",
       usage: "ccmsg post <sid> <text> [--sid <自分の sid>]",
-      options: [["--sid <sid>", "自分のセッション ID (既定は CLAUDE_CODE_SESSION_ID)"]],
+      options: [["--sid <sid>", `自分のセッション ID (既定は ${SESSION_ENV.join(" / ")})`]],
       env: sessionEnv(),
       run: (args) => post(args),
     },
@@ -315,7 +348,7 @@ const ROOT: Command = {
       summary: "受け取ったメッセージに返信する",
       usage: "ccmsg reply <mid> <text> [--to <相手の sid>]",
       options: [
-        ["--sid <sid>", "自分のセッション ID (既定は CLAUDE_CODE_SESSION_ID)"],
+        ["--sid <sid>", `自分のセッション ID (既定は ${SESSION_ENV.join(" / ")})`],
         ["--to <sid>", "宛先セッション (封筒の ccmsg-from)。省略すると人への返信"],
       ],
       env: sessionEnv(),
@@ -326,7 +359,7 @@ const ROOT: Command = {
       summary: "見ている人へ一行知らせる (保持されない、返事も来ない)",
       usage: "ccmsg notify <text> [--about <sid>]",
       options: [
-        ["--sid <sid>", "自分のセッション ID (既定は CLAUDE_CODE_SESSION_ID)"],
+        ["--sid <sid>", `自分のセッション ID (既定は ${SESSION_ENV.join(" / ")})`],
         ["--about <sid>", "知らせるセッション (既定は自分)"],
       ],
       env: sessionEnv(),
@@ -338,7 +371,7 @@ const ROOT: Command = {
       usage: "ccmsg stopping [--reason <text>] [--hook]",
       bare: true,
       options: [
-        ["--sid <sid>", "自分のセッション ID (既定は CLAUDE_CODE_SESSION_ID)"],
+        ["--sid <sid>", `自分のセッション ID (既定は ${SESSION_ENV.join(" / ")})`],
         ["--reason <text>", "終わる理由 (表示用、任意)"],
         ["--hook", "harness の hook イベント JSON を標準入力から読む"],
       ],
@@ -351,7 +384,7 @@ const ROOT: Command = {
       usage: "ccmsg hello [--cwd <path>] [--repo <name>] ... [--hook]",
       bare: true,
       options: [
-        ["--sid <sid>", "自分のセッション ID (既定は CLAUDE_CODE_SESSION_ID)"],
+        ["--sid <sid>", `自分のセッション ID (既定は ${SESSION_ENV.join(" / ")})`],
         ["--cwd <path>", "作業ディレクトリ"],
         ["--repo <name>", "リポジトリの表示名"],
         ["--ws <name>", "ワークスペース名"],
@@ -370,7 +403,7 @@ const ROOT: Command = {
       usage: "ccmsg say [say-options] [text...]",
       options: [["", `引数は ${SYSTEM_SAY} へそのまま渡す (単独の --help だけが例外)`]],
       env: [
-        ["CLAUDE_CODE_SESSION_ID", "喋ったセッションの名乗り"],
+        [SESSION_ENV.join(" / "), "喋ったセッションの名乗り"],
         ["CCMSG_SAY_BIN", `発声に使うバイナリ (既定は ${SYSTEM_SAY})`],
       ],
       raw: (args) => say(args),
@@ -379,7 +412,7 @@ const ROOT: Command = {
 };
 
 function sessionEnv(): readonly Doc[] {
-  return [["CLAUDE_CODE_SESSION_ID", "自分のセッション ID"]];
+  return [[SESSION_ENV.join(" / "), "自分のセッション ID"]];
 }
 
 /** Walk the tree, and answer at the level the arguments reach.
@@ -471,8 +504,13 @@ function section(lines: string[], title: string, docs: readonly Doc[] | undefine
 
 /** `ccmsg daemon run [dir]`: this config home's instance, in the foreground. */
 async function runInstance(dir: string | undefined): Promise<unknown> {
-  const home = configHome(dir ?? resolveConfigHome());
-  const outcome = await start({ env: { ...process.env, CLAUDE_CONFIG_DIR: home } });
+  const named = dir ?? resolveConfigHome();
+  const home = configHome(named, harnessFor(process.env, named));
+  // The directory is handed over rather than put in the environment: the
+  // instance would otherwise read it back through the question "which session
+  // is this process inside", and a `daemon run` issued from a session of
+  // another harness would answer for that session's config home (§3.8).
+  const outcome = await start({ configHome: home });
   if (!isRunning(outcome)) {
     throw new CommandError(
       "file_exists",
@@ -515,9 +553,17 @@ async function supervise(): Promise<unknown> {
  * next supervisor starts it. Told rather than left to be discovered, because
  * the supervisor reads the list once (DV-Q8) and would otherwise not know
  * until it is restarted. */
-async function added(dir: string | undefined): Promise<unknown> {
-  if (dir === undefined) throw new CommandError("invalid_args", "使い方: ccmsg daemon add <dir>");
-  const row = addToConfig(process.env, dir);
+async function added(args: readonly string[]): Promise<unknown> {
+  const { named, rest } = options(args, ["harness"]);
+  const dir = rest[0];
+  const stated = named.get("harness");
+  if (dir === undefined) {
+    throw new CommandError("invalid_args", "使い方: ccmsg daemon add <dir> [--harness <種別>]");
+  }
+  if (stated !== undefined && !isHarness(stated)) {
+    throw new CommandError("invalid_args", `--harness は ${HARNESSES.join(" | ")} のどれかです`);
+  }
+  const row = addToConfig(process.env, dir, stated ?? DEFAULT_HARNESS);
   if (!(await reachable())) return { ...row, supervised: false };
   const started = (await ask({ op: "supervise_add", dir: row.dir })) as Record<string, unknown>;
   return { ...started, supervised: true };
@@ -735,7 +781,7 @@ function never(release: () => void): Promise<void> {
  * the same list minus that field. */
 function peers(args: readonly string[]): Promise<unknown> {
   const parsed = options(args, ["sid"], ["all", "json"]);
-  const sid = parsed.named.get("sid") ?? process.env["CLAUDE_CODE_SESSION_ID"];
+  const sid = parsed.named.get("sid") ?? ownSid();
   return topic(
     "peers",
     parsed.flags.has("all"),
@@ -884,7 +930,7 @@ export async function hello(args: readonly string[], read?: Read): Promise<unkno
     ["hook"],
   );
   const event = parsed.flags.has("hook") ? await hookEvent(read) : {};
-  const sid = parsed.named.get("sid") ?? event.sid ?? process.env["CLAUDE_CODE_SESSION_ID"];
+  const sid = parsed.named.get("sid") ?? event.sid ?? ownSid();
   if (sid === undefined || sid === "") return { greeted: false, reason: "no_session_id" };
   const meta = stated(parsed.named, event);
   const paths = resolvePaths();
@@ -936,6 +982,18 @@ function only(field: keyof StatedMeta, value: string | undefined): StatedMeta {
   return value === undefined || value === "" ? {} : { [field]: value };
 }
 
+/** The config home of one agent, as that agent's own variable names it.
+ *
+ * Its own and no other's: the point of naming the agent is to install into the
+ * home that agent reads, and a fallback to somebody else's variable would put
+ * the files where the agent will never look. Unset means the agent's own
+ * default home, which is where that agent looks when nobody says otherwise. */
+function homeOf(agent: Agent): string {
+  const named = process.env[HARNESS[agent].homeEnv];
+  if (named !== undefined && named !== "" && isAbsolute(named)) return named;
+  return join(homedir(), agent === "codex" ? ".codex" : ".claude");
+}
+
 /** `ccmsg plugin <what> <agent>`: what ccmsg installs into an agent, and what
  * it takes back out.
  *
@@ -946,10 +1004,10 @@ async function plugin(
   what: "install" | "status" | "uninstall",
   agent: string | undefined,
 ): Promise<unknown> {
-  if (agent !== undefined && agent !== "claude") {
+  if (agent !== undefined && !isHarness(agent)) {
     throw new CommandError(
       "invalid_args",
-      `${agent} 用のプラグインはまだありません (今あるのは ${AGENTS.join(", ")})`,
+      `${agent} 用のプラグインはありません (今あるのは ${AGENTS.join(", ")})`,
     );
   }
   if (what !== "status" && agent === undefined) {
@@ -958,13 +1016,22 @@ async function plugin(
       `使い方: ccmsg plugin ${what} <agent> (今あるのは ${AGENTS.join(", ")})`,
     );
   }
-  const paths = resolvePaths();
+  // `status` with no agent named answers for the config home this process
+  // belongs to, which is what the instance there runs.
+  const which = agent ?? harnessFor(process.env, resolvePaths().configHome);
+  // The config home is that agent's own, and not whichever variable happens to
+  // be set: a Codex session started from a Claude Code session carries both,
+  // and an install that read the wrong one would write Codex's hooks into
+  // Claude Code's config home (§3.8). The marker check is what says the
+  // directory really is that agent's.
+  const home = configHome(homeOf(which), which);
+  const paths = resolvePathsFor(home);
   const outcome: Outcome =
     what === "install"
-      ? await install(paths, VERSION)
+      ? await install(paths, which, VERSION)
       : what === "status"
-        ? await pluginStatus(paths)
-        : await uninstall(paths);
+        ? await pluginStatus(paths, which)
+        : await uninstall(paths, which);
   // A refused step is an error rather than an answer, so the command's exit
   // code says what happened without the report having to be read. The report
   // itself travels with it: what was done before the refusal is what the next
@@ -1009,11 +1076,11 @@ async function call(
   request: Record<string, unknown>,
   meta: StatedMeta = statedMeta(),
 ): Promise<unknown> {
-  const sid = named ?? process.env["CLAUDE_CODE_SESSION_ID"];
+  const sid = named ?? ownSid();
   if (sid === undefined || sid === "") {
     throw new CommandError(
       "invalid_args",
-      "自分のセッション ID が分かりません (--sid か CLAUDE_CODE_SESSION_ID)",
+      `自分のセッション ID が分かりません (--sid か ${SESSION_ENV.join(" / ")})`,
     );
   }
   const paths = resolvePaths();
@@ -1091,7 +1158,7 @@ export async function say(args: readonly string[], spawn: Spawn = spawnSpeech):
  * contract will not take — a bare `say` reading its text from stdin has none —
  * is nothing to record either. */
 async function posted(text: string): Promise<void> {
-  const sid = process.env["CLAUDE_CODE_SESSION_ID"];
+  const sid = ownSid();
   if (text === "" || sid === undefined || sid === "") return;
   const conn = await connect(resolvePaths().socket);
   if (conn === undefined) return;

package/src/daemon/registry.ts

@@ -1,36 +1,54 @@
 import { existsSync, mkdirSync, watch } from "node:fs";
 import { basename, isAbsolute, join, resolve } from "node:path";
 import type { Endpoint, InstanceId, InstancePingResult } from "@ccmsg/protocol";
+import { DEFAULT_HARNESS, type Harness, HARNESS, isHarness } from "../harness/index.ts";
 import {
   type InstanceEntry,
   loadShared,
   saveShared,
+  settingsFor,
   type SharedConfig,
 } from "../instance/config.ts";
 import { instanceIdentity } from "../instance/identity.ts";
 import { alive, lockHolder } from "../instance/lock.ts";
-import { type Env, type InstancePaths, resolvePaths } from "../instance/paths.ts";
+import { type Env, type InstancePaths, resolvePaths, resolvePathsFor } from "../instance/paths.ts";
 import { prepareSocketDir } from "../instance/socket.ts";
 import { connect, greetAsUser } from "./control.ts";
 import { CommandError } from "./link.ts";
 
 /** What a config home has to be for an instance to answer for it.
  *
- * `settings.json` is the harness's own file, so its presence is what says the
- * directory is a config home rather than any directory somebody typed. Checked
- * where a directory is named — `add` and `run` — rather than at every use, so
- * the mistake is caught when it is made. */
-export function configHome(dir: string): string {
+ * The harness's own settings file is what says the directory is a config home
+ * rather than any directory somebody typed, so which file is looked for
+ * follows which harness the directory runs (§3.8). Checked where a directory
+ * is named — `add` and `run` — rather than at every use, so the mistake is
+ * caught when it is made. */
+export function configHome(dir: string, harness: Harness = DEFAULT_HARNESS): string {
   const path = isAbsolute(dir) ? dir : resolve(dir);
-  if (!existsSync(join(path, "settings.json"))) {
+  const marker = HARNESS[harness].marker;
+  if (!existsSync(join(path, marker))) {
     throw new CommandError(
       "not_found",
-      `${path} は Claude Code の config home ではありません (settings.json がありません)`,
+      `${path} は ${harness} の config home ではありません (${marker} がありません)`,
     );
   }
   return path;
 }
 
+/** Which harness a registered config home runs, as the shared file records it.
+ *
+ * Read from the same entry the instance itself will read (§8.2), so a command
+ * that has to know before anything is running — `run`, and the supervisor's
+ * own start — reaches the same answer the instance does. A directory the file
+ * does not list runs the default, which is what an unregistered `daemon run`
+ * is. */
+export function harnessFor(env: Env, dir: string): Harness {
+  const path = isAbsolute(dir) ? dir : resolve(dir);
+  const settings = settingsFor(loadShared(resolvePaths(env).configFile), path);
+  const named = settings["harness"];
+  return isHarness(named) ? named : DEFAULT_HARNESS;
+}
+
 /** One row of `daemon list`: which config home, and whether anything answers
  * for it right now. */
 export interface InstanceRow {
@@ -58,7 +76,7 @@ export interface Target {
 }
 
 export function targetFor(env: Env, dir: string): Target {
-  return { dir, paths: resolvePaths({ ...env, CLAUDE_CONFIG_DIR: dir }) };
+  return { dir, paths: resolvePathsFor(dir, env) };
 }
 
 /** The config homes the shared file lists, in the order it lists them. */
@@ -68,15 +86,20 @@ export function registered(env: Env): Target[] {
 }
 
 /** Add a config home to the shared file. The settings it will run with are the
- * defaults until somebody edits its entry, so the entry starts empty. */
-export function add(env: Env, dir: string): InstanceRow {
-  const home = configHome(dir);
+ * defaults until somebody edits its entry, so the entry starts empty — save
+ * for the harness, which is written down when it is not the default because it
+ * is the one setting the directory itself cannot be asked for (§3.8). */
+export function add(env: Env, dir: string, harness: Harness = DEFAULT_HARNESS): InstanceRow {
+  const home = configHome(dir, harness);
   const file = resolvePaths(env).configFile;
   const shared = loadShared(file);
   if (shared.instances.some((entry) => entry.dir === home)) {
     throw new CommandError("file_exists", `${home} は既に登録されています`);
   }
-  const entry: InstanceEntry = { dir: home, settings: {} };
+  const entry: InstanceEntry = {
+    dir: home,
+    settings: harness === DEFAULT_HARNESS ? {} : { harness },
+  };
   saveShared(file, { ...shared, instances: [...shared.instances, entry] });
   const target = targetFor(env, home);
   // The id is made here rather than at the first start, so that what `add`
@@ -203,9 +226,13 @@ export interface Child {
 export type SpawnInstance = (dir: string, env: Env) => Child;
 
 export const spawnInstance: SpawnInstance = (dir, env) => {
+  // The directory is an argument and not an environment variable: `daemon run`
+  // takes it from there and hands it to the instance by value, so which config
+  // home the child answers for cannot depend on which session the supervisor
+  // was started from (§3.8).
   const proc = Bun.spawn([process.execPath, ENTRY, "daemon", "run", dir], {
     stdio: ["ignore", "ignore", "ignore"],
-    env: { ...env, CLAUDE_CONFIG_DIR: dir } as Record<string, string>,
+    env: { ...env } as Record<string, string>,
   });
   return {
     pid: proc.pid,

package/src/daemon/supervise.ts

@@ -7,6 +7,7 @@ import {
   awaitSocket,
   type Child,
   configHome,
+  harnessFor,
   prepareFor,
   registered,
   rowFor,
@@ -304,7 +305,7 @@ export class Supervisor {
    * behind it is the state `add` exists to leave behind only when there is no
    * supervisor to tell. */
   async addOne(dir: string): Promise<StatusRow> {
-    const home = configHome(dir);
+    const home = configHome(dir, harnessFor(this.#env, dir));
     if (this.#units.has(home)) {
       throw new CommandError("file_exists", `${home} は既に見ています`);
     }

package/src/harness/index.ts

@@ -0,0 +1,96 @@
+/** Which harness a config home runs, and the few facts that differ with it.
+ *
+ * A harness is an attribute of an instance rather than of the contract: an
+ * instance answers for one config home (M6), that config home belongs to one
+ * program, and every difference below is a place where that program keeps
+ * something ccmsg reads. The protocol never names a harness, so nothing a
+ * client sees changes with this — what changes is which directory is walked,
+ * what says a session is there, and how route (a) is spoken.
+ *
+ * The facts live together because they are one table: adding a harness is
+ * filling a row, and a difference that has no row here is a difference nobody
+ * declared. */
+
+export const HARNESSES = ["claude", "codex"] as const;
+export type Harness = (typeof HARNESSES)[number];
+
+/** What a config home runs when nothing says otherwise. Claude Code, because
+ * it is the harness ccmsg was read off and the one an unmarked config home in
+ * an existing setup belongs to. */
+export const DEFAULT_HARNESS: Harness = "claude";
+
+export interface HarnessFacts {
+  /** The file whose presence says a directory is this harness's config home
+   * rather than any directory somebody typed. Both harnesses keep their own
+   * settings in one, so this is the harness's own word for "mine". */
+  readonly marker: string;
+  /** The directory under the config home where transcripts are kept. Claude
+   * Code files them per working directory, Codex per date, so what this names
+   * is the root of the tree and not the directory a file is in. */
+  readonly transcripts: string;
+  /** The environment variable that names this harness's config home, which is
+   * what a session's own processes are run with. */
+  readonly homeEnv: string;
+  /** The variables that name the session a process is running inside, in the
+   * order they are believed. Set by the harness for the commands its session
+   * runs, and by nothing else — which is what makes them the answer to "whose
+   * session is this". */
+  readonly sessionEnv: readonly string[];
+}
+
+export const HARNESS: Record<Harness, HarnessFacts> = {
+  claude: {
+    marker: "settings.json",
+    transcripts: "projects",
+    homeEnv: "CLAUDE_CONFIG_DIR",
+    sessionEnv: ["CLAUDE_CODE_SESSION_ID"],
+  },
+  codex: {
+    marker: "config.toml",
+    transcripts: "sessions",
+    homeEnv: "CODEX_HOME",
+    sessionEnv: ["CODEX_THREAD_ID", "CODEX_SESSION_ID"],
+  },
+};
+
+/** The session a process is running inside, where its environment says so.
+ *
+ * Which harness is asked first cannot be the order two config-home variables
+ * happen to be listed in: a session of one harness started from a session of
+ * the other inherits the whole environment of its parent, so both homes are
+ * named at once and the outer one is named first. Measured, and not a corner:
+ * a Codex session started from a Claude Code session inherits
+ * `CLAUDE_CONFIG_DIR`, `CLAUDE_CODE_SESSION_ID` and the rest of it.
+ *
+ * So what decides is the session variables, and the config home follows from
+ * whichever harness claimed the process — one answer used both for "who am I"
+ * and for "which instance do I speak to", so the two can never disagree.
+ *
+ * Where more than one claims it, the order below decides, and it is not the
+ * order the harnesses are listed in. Claude Code exports its session id into
+ * everything the session starts, another harness included; Codex names its
+ * thread to the commands of its own turn. The narrower claim is the truer one,
+ * so it is asked first. The reverse nesting — a Claude Code session started
+ * from inside a Codex turn — reads as Codex. `--sid` overrides only the sid a
+ * command speaks as, and not which instance it speaks to (§3.8).
+ *
+ * A process no session runs inside — a person at a terminal, a supervisor —
+ * matches nothing here, and the caller falls back to what it would have done
+ * before being asked. */
+const CLAIM_ORDER: readonly Harness[] = ["codex", "claude"];
+
+export function currentSession(
+  env: Record<string, string | undefined>,
+): { harness: Harness; sid: string } | undefined {
+  for (const harness of CLAIM_ORDER) {
+    for (const variable of HARNESS[harness].sessionEnv) {
+      const sid = env[variable];
+      if (sid !== undefined && sid !== "") return { harness, sid };
+    }
+  }
+  return undefined;
+}
+
+export function isHarness(value: unknown): value is Harness {
+  return HARNESSES.includes(value as Harness);
+}

package/src/instance/config.ts

@@ -1,6 +1,7 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute } from "node:path";
 import type { Endpoint } from "@ccmsg/protocol";
+import { DEFAULT_HARNESS, type Harness, HARNESSES, isHarness } from "../harness/index.ts";
 import { parseCidr } from "./client.ts";
 
 /** Where the instance accepts WebSocket connections, and from whom.
@@ -91,6 +92,13 @@ export interface UpstreamConfig {
 }
 
 export interface InstanceConfig {
+  /** Which harness this config home runs (§3.8).
+   *
+   * A setting rather than something discovered, because it decides where the
+   * instance looks before there is anything there to look at: an empty config
+   * home says nothing about the program it belongs to, and an instance that
+   * guessed would walk the wrong tree for the whole of its first session. */
+  readonly harness: Harness;
   /** Every mesh endpoint, this instance's own among them (§7.1). The same list
    * goes to every instance and names none of them in particular: which entry is
    * this one is settled at startup by the probe, so one file can be copied to
@@ -133,6 +141,7 @@ export class ConfigError extends Error {
  * one that is there and unreadable states something wrong — only the second is
  * the fail-fast case. */
 export const DEFAULT_CONFIG: InstanceConfig = {
+  harness: DEFAULT_HARNESS,
   peers: [],
   upstream: {},
   direct_delivery: true,
@@ -233,6 +242,7 @@ export function settingsFor(shared: SharedConfig, dir: string): Record<string, u
 /** One instance's settings, read at the shape the instance uses them. */
 export function parseConfig(file: string, fields: Record<string, unknown>): InstanceConfig {
   return {
+    harness: harnessOf(file, fields["harness"]),
     peers: peersOf(file, fields["peers"]),
     ...(fields["entry"] === undefined ? {} : { entry: entryOf(file, fields["entry"]) }),
     upstream: upstreamOf(file, fields["upstream"]),
@@ -246,6 +256,14 @@ export function parseConfig(file: string, fields: Record<string, unknown>): Inst
   };
 }
 
+function harnessOf(file: string, raw: unknown): Harness {
+  if (raw === undefined) return DEFAULT_HARNESS;
+  if (!isHarness(raw)) {
+    throw new ConfigError(file, `harness must be one of ${HARNESSES.join(", ")}`);
+  }
+  return raw;
+}
+
 function flagOf(file: string, at: string, raw: unknown, fallback: boolean): boolean {
   if (raw === undefined) return fallback;
   if (typeof raw !== "boolean") throw new ConfigError(file, `${at} must be true or false`);
@@ -268,6 +286,21 @@ function endpointOf(file: string, at: string, raw: unknown): Endpoint {
   return raw as Endpoint;
 }
 
+/** `terminal_gateway`'s shape, matched to the contract's `HelloResult` so a
+ * value this instance would refuse to report is refused here instead, at
+ * startup, rather than on the first `hello`. */
+const TERMINAL_GATEWAY = /^https?:\/\/[^/?#\s]+(\/[^?#\s]*[^/?#\s])?$/;
+
+function terminalGatewayOf(file: string, raw: string): string {
+  if (!TERMINAL_GATEWAY.test(raw)) {
+    throw new ConfigError(
+      file,
+      `upstream.terminal_gateway must be an http:// or https:// base URL with no trailing slash, got ${raw}`,
+    );
+  }
+  return raw;
+}
+
 function peersOf(file: string, raw: unknown): readonly Endpoint[] {
   if (raw === undefined) return [];
   if (!Array.isArray(raw)) throw new ConfigError(file, "peers must be an array of endpoint URLs");
@@ -316,6 +349,9 @@ function upstreamOf(file: string, raw: unknown): UpstreamConfig {
     }
     config[name] = value;
   }
+  if (config["terminal_gateway"] !== undefined) {
+    config["terminal_gateway"] = terminalGatewayOf(file, config["terminal_gateway"]);
+  }
   const launcher = fields["launcher"];
   return {
     ...(config as UpstreamConfig),