viber-channel 0.5.3 → 0.6.0

package/lib/conversation.ts

@@ -26,10 +26,24 @@ export class ReattachFailedError extends Error {
   }
 }
 
+/**
+ * Non-2xx from the conversation mint/join endpoint. `.status` lets the caller
+ * react to a 401 (the instance_token was revoked → re-acquire a new instance
+ * and retry, #269) distinctly from other failures.
+ */
+export class ConversationMintError extends Error {
+  status: number;
+  constructor(status: number, detail: string) {
+    super(`Failed to mint conversation token (HTTP ${status}): ${detail}`);
+    this.name = "ConversationMintError";
+    this.status = status;
+  }
+}
+
 export async function mintConversation(
   baseUrl: string,
   projectId: number,
-  projectToken: string,
+  instanceToken: string,
   fingerprint: string,
   label: string,
   /**
@@ -55,7 +69,7 @@ export async function mintConversation(
   const resp = await fetch(`${baseUrl}/api/projects/${projectId}/conversations`, {
     method: "POST",
     headers: {
-      Authorization: `Bearer ${projectToken}`,
+      Authorization: `Bearer ${instanceToken}`,
       "X-Client-Fingerprint": fingerprint,
       "Content-Type": "application/json",
       ...cfAccessHeaders(),
@@ -64,7 +78,7 @@ export async function mintConversation(
   });
   if (!resp.ok) {
     const detail = await resp.text();
-    throw new Error(`Failed to mint conversation token (HTTP ${resp.status}): ${detail}`);
+    throw new ConversationMintError(resp.status, detail);
   }
   return (await resp.json()) as ConversationMintResponse;
 }
@@ -81,14 +95,14 @@ export async function mintConversation(
 export async function reattachConversation(
   baseUrl: string,
   projectId: number,
-  projectToken: string,
+  instanceToken: string,
   fingerprint: string,
   conversationId: string,
 ): Promise<ConversationMintResponse> {
   const resp = await fetch(`${baseUrl}/api/projects/${projectId}/conversations`, {
     method: "POST",
     headers: {
-      Authorization: `Bearer ${projectToken}`,
+      Authorization: `Bearer ${instanceToken}`,
       "X-Client-Fingerprint": fingerprint,
       "Content-Type": "application/json",
       ...cfAccessHeaders(),
@@ -237,7 +251,7 @@ export const DEFAULT_REATTACH_WINDOW_SECONDS = 3600;
  * @param sessionPath   Path returned by `sessionFilePath(baseUrl, fingerprint, sessionId, dir)`
  * @param baseUrl       Backend base URL
  * @param projectId     Project ID from auth.json
- * @param projectToken  Bearer token from auth.json
+ * @param instanceToken  Bearer token from auth.json
  * @param fingerprint   Client fingerprint from auth.json
  * @param label         Conversation label (used only when minting)
  * @param targetConversationId  Optional target for the attach-to-project flow (passed to mint)
@@ -248,7 +262,7 @@ export async function acquireConversation(
   sessionPath: string,
   baseUrl: string,
   projectId: number,
-  projectToken: string,
+  instanceToken: string,
   fingerprint: string,
   label: string,
   targetConversationId?: string | null,
@@ -265,7 +279,7 @@ export async function acquireConversation(
     if (handleAge < reattachWindowSeconds) {
       log(`[viber-channel] startup: session handle found (conv_id=${handle.conversation_id}, age=${handleAge}s < ${reattachWindowSeconds}s window), attempting reattach\n`);
       try {
-        const result = await reattachConversation(baseUrl, projectId, projectToken, fingerprint, handle.conversation_id);
+        const result = await reattachConversation(baseUrl, projectId, instanceToken, fingerprint, handle.conversation_id);
         log(`[viber-channel] startup: reattach OK, conv_id=${result.conversation_id}\n`);
         try {
           writeHandle(sessionPath, result.conversation_id);
@@ -291,7 +305,7 @@ export async function acquireConversation(
   }
 
   // Mint a new conversation
-  const result = await mintConversation(baseUrl, projectId, projectToken, fingerprint, label, targetConversationId ?? null);
+  const result = await mintConversation(baseUrl, projectId, instanceToken, fingerprint, label, targetConversationId ?? null);
   log(`[viber-channel] startup: mint OK, conv_id=${result.conversation_id}\n`);
   try {
     writeHandle(sessionPath, result.conversation_id);

package/lib/instance.ts

@@ -0,0 +1,137 @@
+/**
+ * instance.ts — acquire and use the server-issued per-instance identity (#269).
+ *
+ * The instance_token is the durable, opaque per-agent credential (D4) the channel
+ * presents to JOIN a conversation. It replaces the locally-computed
+ * client_fingerprint as the identity source. Acquisition is self-healing: an
+ * existing install with no instance_token registers one on first run with its
+ * stable project_token (no forced manual reconnect).
+ */
+import { cfAccessHeaders } from "./cfAccess.js";
+import { authFilePath, persistInstanceCredentials, type AuthJson } from "./auth.js";
+
+export interface RegisterInstanceResponse {
+  instance_id: string;
+  instance_token: string;
+}
+
+/**
+ * Non-2xx from POST /api/projects/:id/instances. `.status` lets the caller
+ * distinguish a revoked/invalid project_token (401 → reconnect) from a transient
+ * server error.
+ */
+export class InstanceRegisterError extends Error {
+  status: number;
+  constructor(status: number, detail: string) {
+    super(`Failed to register instance (HTTP ${status}): ${detail}`);
+    this.name = "InstanceRegisterError";
+    this.status = status;
+  }
+}
+
+/**
+ * POST /api/projects/:id/instances — mint a durable per-instance identity.
+ * Authenticated by the stable project_token (the orchestrator credential);
+ * the worker also wants X-Client-Fingerprint as a stored signal. Returns the
+ * opaque instance_token + its server id.
+ */
+export async function registerInstance(
+  baseUrl: string,
+  projectId: number,
+  projectToken: string,
+  fingerprint: string,
+  label?: string,
+  kind?: string,
+): Promise<RegisterInstanceResponse> {
+  const body: Record<string, string> = {};
+  if (label !== undefined) body.label = label;
+  if (kind !== undefined) body.kind = kind; // runtime: "claude-code" | "codex" | … (#280)
+  const resp = await fetch(`${baseUrl}/api/projects/${projectId}/instances`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${projectToken}`,
+      "X-Client-Fingerprint": fingerprint,
+      "Content-Type": "application/json",
+      ...cfAccessHeaders(),
+    },
+    body: JSON.stringify(body),
+  });
+  if (!resp.ok) {
+    const detail = await resp.text().catch(() => "");
+    throw new InstanceRegisterError(resp.status, detail);
+  }
+  return (await resp.json()) as RegisterInstanceResponse;
+}
+
+export interface AcquiredInstance {
+  instance_token: string;
+  /**
+   * Stable per-instance key used to namespace the conversation handle. The
+   * server `instance_id` when known; otherwise the `instance_token` itself
+   * (env-injected agents may not carry the id). Both are 1:1 with the instance
+   * and durable, so either isolates the handle correctly.
+   */
+  instance_key: string;
+  /**
+   * The real server-issued `instance_id`, or undefined when only a bare token is
+   * known (env-injected token without VIBER_INSTANCE_ID, or a persisted token with
+   * no persisted id). Distinct from `instance_key` — which may be the TOKEN as a
+   * namespacing fallback. Use THIS for the self-echo guard + sender attribution:
+   * the token must never be compared against server instance ids in
+   * `sender_instance_id`; undefined → the self-echo guard fails open (delivers everything).
+   */
+  instance_id?: string;
+}
+
+/**
+ * Resolve this channel's instance identity (#269), in priority order:
+ *   1. `VIBER_INSTANCE_TOKEN` env (orchestrator-injected, folder-less agents) —
+ *      used verbatim; `VIBER_INSTANCE_ID` keys the handle if also provided, else
+ *      the token does.
+ *   2. `VIBER_CHANNEL_LABEL` env (#280 step-25 — launcher-named agent session):
+ *      register a FRESH instance carrying that label, NOT persisted — reusing or
+ *      overwriting the shared auth.json identity would evict the user's main
+ *      channel session (the #252 instance-collision gotcha).
+ *   3. `auth.json` `instance_token` — reused (durable identity, D4 → same id).
+ *   4. register a NEW instance with the stable project_token, persisted back to
+ *      auth.json (self-healing migration — no forced manual reconnect).
+ */
+export async function acquireInstance(
+  baseUrl: string,
+  auth: AuthJson,
+  fingerprint: string,
+  log: (msg: string) => void = (m) => process.stderr.write(m),
+  cwd: string = process.cwd(),
+): Promise<AcquiredInstance> {
+  const envToken = process.env.VIBER_INSTANCE_TOKEN;
+  if (envToken !== undefined && envToken.trim() !== "") {
+    const token = envToken.trim();
+    const envId = process.env.VIBER_INSTANCE_ID;
+    const realId = envId !== undefined && envId.trim() !== "" ? envId.trim() : undefined;
+    const key = realId ?? token;
+    log(`[viber-channel] instance: using VIBER_INSTANCE_TOKEN (env-injected)\n`);
+    return { instance_token: token, instance_key: key, instance_id: realId };
+  }
+
+  const envLabel = process.env.VIBER_CHANNEL_LABEL;
+  if (envLabel !== undefined && envLabel.trim() !== "") {
+    const label = envLabel.trim();
+    log(`[viber-channel] instance: registering fresh labelled instance "${label}"\n`);
+    const reg = await registerInstance(baseUrl, auth.project_id, auth.project_token, fingerprint, label);
+    return { instance_token: reg.instance_token, instance_key: reg.instance_id, instance_id: reg.instance_id };
+  }
+
+  if (auth.instance_token !== undefined && auth.instance_token.trim() !== "") {
+    const realId =
+      auth.instance_id !== undefined && auth.instance_id.trim() !== "" ? auth.instance_id : undefined;
+    const key = realId ?? auth.instance_token;
+    log(`[viber-channel] instance: reusing persisted instance_token (id=${auth.instance_id ?? "?"})\n`);
+    return { instance_token: auth.instance_token, instance_key: key, instance_id: realId };
+  }
+
+  log(`[viber-channel] instance: none found — registering a new one via the project_token\n`);
+  const reg = await registerInstance(baseUrl, auth.project_id, auth.project_token, fingerprint);
+  persistInstanceCredentials(authFilePath(cwd), reg.instance_id, reg.instance_token, log);
+  log(`[viber-channel] instance: registered + persisted (id=${reg.instance_id})\n`);
+  return { instance_token: reg.instance_token, instance_key: reg.instance_id, instance_id: reg.instance_id };
+}

package/lib/messages.ts

@@ -71,6 +71,30 @@ export function parseArtifact(raw: unknown): ParseArtifactResult {
   return { ok: true, artifact: { content, format: rawArtifact.format as ArtifactFormat } };
 }
 
+/**
+ * GET /api/conversations/:id/messages with a conversation_token (multi-auth).
+ *
+ * Used by the bridge to CATCH UP on messages it missed while its SSE was
+ * disconnected (#280 step-06): the conversation SSE has no replay, so on each
+ * reconnect the bridge re-reads the message list and processes any it hasn't
+ * seen. Returns the raw message array (ascending id) or throws on failure /
+ * `ConversationTokenExpiredError` on 401 so the caller can refresh + retry.
+ */
+export async function fetchMessages(
+  baseUrl: string,
+  conversationId: string,
+  conversationToken: string,
+): Promise<Array<Record<string, unknown>>> {
+  const resp = await fetch(`${baseUrl}/api/conversations/${conversationId}/messages`, {
+    method: "GET",
+    headers: { Authorization: `Bearer ${conversationToken}`, ...cfAccessHeaders() },
+  });
+  if (resp.status === 401) throw new ConversationTokenExpiredError();
+  if (!resp.ok) throw new Error(`fetchMessages failed: HTTP ${resp.status}`);
+  const body = (await resp.json()) as { messages?: Array<Record<string, unknown>> };
+  return Array.isArray(body.messages) ? body.messages : [];
+}
+
 export interface MessagePostSuccess {
   ok: true;
   message_id: string;

package/lib/self_echo.ts

@@ -0,0 +1,17 @@
+/**
+ * Self-echo guard: true when a message was posted BY this session's own
+ * instance, so it isn't surfaced back to the session that sent it.
+ *
+ * The conversation SSE stream replays every message posted to the conversation,
+ * including messages posted by this session via send_message. Without this
+ * guard, Claude would receive its own replies as inbound channel events.
+ */
+
+/** True when this message was posted BY this session's own instance (self-echo). */
+export function isOwnMessage(senderInstanceId: unknown, ownInstanceId: string): boolean {
+	return (
+		ownInstanceId !== "" &&
+		typeof senderInstanceId === "string" &&
+		senderInstanceId === ownInstanceId
+	);
+}

package/lib/supervisor.ts

@@ -0,0 +1,292 @@
+/**
+ * Agent supervisor (#280 step-12, slice 2).
+ *
+ * Hosts MANY agents by spawning one OS process per agent and managing each one's
+ * lifecycle independently. This is the client-side multiplexer the control plane
+ * drives; agents still never talk directly (hub-and-spoke — the Viber server
+ * relays), so one-process-per-agent buys crash isolation for free.
+ *
+ * Design (per .claude/rules/architecture.md):
+ *   - explicit state machine per agent (no boolean soup),
+ *   - a per-agent state object in a registry (no scattered dicts),
+ *   - spawn + restart scheduling injected so the lifecycle is unit-testable
+ *     without real child processes.
+ *
+ * This module owns ONLY lifecycle (spawn / crash / restart / stop). Wiring it to a
+ * real bridge launch and to the control-plane UI is a later slice.
+ *
+ * Follow-up (real-spawn slice): harden against a synchronous spawn() throw — today
+ * spawn is injected and trusted; the real node-spawn SpawnFn should be wrapped so a
+ * launch failure transitions STARTING -> CRASHED and re-enters the backoff path
+ * instead of leaving the agent stuck in STARTING.
+ */
+
+/** Lifecycle states for a single supervised agent. */
+export enum AgentState {
+	/** Spawn requested; child not yet confirmed running. */
+	STARTING = "starting",
+	/** Child process is live. */
+	RUNNING = "running",
+	/** Child exited unexpectedly; awaiting a restart decision. */
+	CRASHED = "crashed",
+	/** Backoff window before the next spawn attempt. */
+	RESTARTING = "restarting",
+	/** Stopped on request, or crashed past the restart budget. Terminal. */
+	STOPPED = "stopped",
+}
+
+/** Legal transitions. Any attempt outside this map throws. */
+const TRANSITIONS: Record<AgentState, readonly AgentState[]> = {
+	[AgentState.STARTING]: [AgentState.RUNNING, AgentState.CRASHED, AgentState.STOPPED],
+	[AgentState.RUNNING]: [AgentState.CRASHED, AgentState.STOPPED],
+	[AgentState.CRASHED]: [AgentState.RESTARTING, AgentState.STOPPED],
+	[AgentState.RESTARTING]: [AgentState.STARTING, AgentState.STOPPED],
+	[AgentState.STOPPED]: [],
+};
+
+/** What to launch for one agent. `args`/`env` are passed to the spawned bridge. */
+export interface AgentSpec {
+	agentId: string;
+	/** Permission tier (step-11): "chat" | "read" | "write". Carried to the child env. */
+	tier: string;
+	args: string[];
+	env?: Record<string, string>;
+}
+
+/** Minimal child-process surface the supervisor depends on (injectable for tests). */
+export interface ChildHandle {
+	readonly pid?: number;
+	kill(signal?: NodeJS.Signals): boolean;
+	/** Fires once when the process exits. */
+	onExit(cb: (code: number | null, signal: NodeJS.Signals | null) => void): void;
+}
+
+export type SpawnFn = (spec: AgentSpec) => ChildHandle;
+
+/** Schedules `fn` after `ms`; returns a canceller. Injected so tests run instantly. */
+export type RestartScheduler = (fn: () => void, ms: number) => () => void;
+
+export interface SupervisorOptions {
+	spawn: SpawnFn;
+	/**
+	 * Max consecutive crash-restarts before giving up (then the agent goes STOPPED).
+	 * This counts RESTARTS, not spawn attempts: maxRestarts=N allows N restarts, i.e.
+	 * N+1 total spawns, before stopping. Default 5.
+	 */
+	maxRestarts?: number;
+	/** Base backoff (ms) for the first restart; doubles each consecutive crash. Default 1000. */
+	baseBackoffMs?: number;
+	/** Backoff ceiling (ms). Default 30000. */
+	maxBackoffMs?: number;
+	/**
+	 * How long an agent must stay RUNNING before its crash counter resets to 0
+	 * (default 10000). Without this, a fast crash-loop would reset the counter on
+	 * every optimistic RUNNING and never escalate backoff or hit maxRestarts.
+	 */
+	stabilityMs?: number;
+	/** Restart scheduler (default setTimeout/clearTimeout). */
+	schedule?: RestartScheduler;
+	/** Optional log sink (default: stderr). */
+	log?: (line: string) => void;
+}
+
+/** Per-agent state object held in the registry. */
+class AgentProcess {
+	state: AgentState = AgentState.STARTING;
+	child: ChildHandle | null = null;
+	/** Consecutive crash-restarts; reset to 0 once the agent stays up `stabilityMs`. */
+	restarts = 0;
+	cancelBackoff: (() => void) | null = null;
+	cancelStability: (() => void) | null = null;
+	/** Set when stop() was called — suppresses crash-restart. */
+	stopping = false;
+
+	constructor(readonly spec: AgentSpec) {}
+}
+
+/** Snapshot of one agent's status (for the control plane / `list()`). */
+export interface AgentStatus {
+	agentId: string;
+	tier: string;
+	state: AgentState;
+	pid?: number;
+	restarts: number;
+}
+
+const defaultSchedule: RestartScheduler = (fn, ms) => {
+	const t = setTimeout(fn, ms);
+	return () => clearTimeout(t);
+};
+
+export class Supervisor {
+	private readonly registry = new Map<string, AgentProcess>();
+	private readonly spawn: SpawnFn;
+	private readonly maxRestarts: number;
+	private readonly baseBackoffMs: number;
+	private readonly maxBackoffMs: number;
+	private readonly stabilityMs: number;
+	private readonly schedule: RestartScheduler;
+	private readonly log: (line: string) => void;
+
+	constructor(opts: SupervisorOptions) {
+		this.spawn = opts.spawn;
+		this.maxRestarts = opts.maxRestarts ?? 5;
+		this.baseBackoffMs = opts.baseBackoffMs ?? 1000;
+		this.maxBackoffMs = opts.maxBackoffMs ?? 30_000;
+		this.stabilityMs = opts.stabilityMs ?? 10_000;
+		this.schedule = opts.schedule ?? defaultSchedule;
+		this.log = opts.log ?? ((line) => process.stderr.write(`${line}\n`));
+	}
+
+	/** Start a new agent. Throws if an agent with this id already exists (not STOPPED). */
+	start(spec: AgentSpec): void {
+		const existing = this.registry.get(spec.agentId);
+		if (existing && existing.state !== AgentState.STOPPED) {
+			throw new Error(`agent ${spec.agentId} already supervised (${existing.state})`);
+		}
+		const agent = new AgentProcess(spec);
+		this.registry.set(spec.agentId, agent);
+		this.spawnAgent(agent);
+	}
+
+	/** Stop an agent: kill the child, mark STOPPED, suppress restart. No-op if unknown. */
+	stop(agentId: string): void {
+		const agent = this.registry.get(agentId);
+		if (!agent || agent.state === AgentState.STOPPED) return;
+		agent.stopping = true;
+		agent.cancelBackoff?.();
+		agent.cancelBackoff = null;
+		agent.cancelStability?.();
+		agent.cancelStability = null;
+		agent.child?.kill("SIGTERM");
+		this.transition(agent, AgentState.STOPPED);
+	}
+
+	/**
+	 * Restart an agent now (manual): stop, then start fresh with the same spec.
+	 * Resets the crash counter to 0 (a deliberate restart is a clean slate). Works
+	 * even on a STOPPED agent (relaunches it); no-op only for an unknown id.
+	 */
+	restart(agentId: string): void {
+		const agent = this.registry.get(agentId);
+		if (!agent) return;
+		const spec = agent.spec;
+		this.stop(agentId);
+		this.registry.delete(agentId);
+		this.start(spec);
+	}
+
+	/** Status snapshot of every supervised agent. */
+	list(): AgentStatus[] {
+		return [...this.registry.values()].map((a) => ({
+			agentId: a.spec.agentId,
+			tier: a.spec.tier,
+			state: a.state,
+			pid: a.child?.pid,
+			restarts: a.restarts,
+		}));
+	}
+
+	/** Stop every agent (e.g. supervisor shutdown). */
+	stopAll(): void {
+		for (const id of this.registry.keys()) this.stop(id);
+	}
+
+	// ── internals ────────────────────────────────────────────────────────────
+
+	private spawnAgent(agent: AgentProcess): void {
+		if (agent.state === AgentState.RESTARTING) {
+			this.transition(agent, AgentState.STARTING);
+		}
+		agent.stopping = false;
+		let child: ChildHandle;
+		try {
+			child = this.spawn(agent.spec);
+		} catch (err) {
+			// A synchronous launch failure is treated like an immediate crash, so the
+			// agent enters the same backoff/give-up path instead of getting stuck in
+			// STARTING with no child.
+			const msg = err instanceof Error ? err.message : String(err);
+			this.scheduleRestartOrStop(agent, `spawn failed: ${msg}`);
+			return;
+		}
+		agent.child = child;
+		this.transition(agent, AgentState.RUNNING);
+		this.log(`[supervisor] agent ${agent.spec.agentId} running (pid ${child.pid ?? "?"})`);
+		// Reset the crash counter only after the agent proves stable, so a fast
+		// crash-loop keeps escalating backoff and eventually hits maxRestarts.
+		agent.cancelStability?.();
+		agent.cancelStability = this.schedule(() => {
+			agent.cancelStability = null;
+			if (agent.state === AgentState.RUNNING) agent.restarts = 0;
+		}, this.stabilityMs);
+		// Guard the exit callback: ignore a double-delivery (one-shot) and a stale
+		// exit from a child we've already replaced (a late exit must not crash the
+		// freshly respawned agent or throw an illegal RESTARTING->CRASHED).
+		let exited = false;
+		child.onExit((code, signal) => {
+			if (exited) return;
+			exited = true;
+			if (agent.child !== child) return;
+			this.onExit(agent, code, signal);
+		});
+	}
+
+	private onExit(
+		agent: AgentProcess,
+		code: number | null,
+		signal: NodeJS.Signals | null,
+	): void {
+		agent.cancelStability?.();
+		agent.cancelStability = null;
+		if (agent.stopping || agent.state === AgentState.STOPPED) {
+			// Expected exit from stop()/restart(); nothing to do.
+			return;
+		}
+		this.scheduleRestartOrStop(agent, signal ? `signal ${signal}` : `code ${code}`);
+	}
+
+	/**
+	 * Crash recovery, shared by an unexpected child exit and a synchronous spawn
+	 * failure: mark CRASHED, then either schedule a backed-off restart or, past the
+	 * budget, give up (STOPPED).
+	 */
+	private scheduleRestartOrStop(agent: AgentProcess, reason: string): void {
+		this.transition(agent, AgentState.CRASHED);
+		this.log(`[supervisor] agent ${agent.spec.agentId} crashed (${reason})`);
+
+		if (agent.restarts >= this.maxRestarts) {
+			this.log(
+				`[supervisor] agent ${agent.spec.agentId} exceeded ${this.maxRestarts} restarts — giving up`,
+			);
+			this.transition(agent, AgentState.STOPPED);
+			return;
+		}
+
+		const delay = Math.min(
+			this.baseBackoffMs * 2 ** agent.restarts,
+			this.maxBackoffMs,
+		);
+		agent.restarts += 1;
+		this.transition(agent, AgentState.RESTARTING);
+		this.log(
+			`[supervisor] agent ${agent.spec.agentId} restart ${agent.restarts}/${this.maxRestarts} in ${delay}ms`,
+		);
+		agent.cancelBackoff = this.schedule(() => {
+			agent.cancelBackoff = null;
+			// A stop() during the backoff window wins.
+			if (agent.stopping || agent.state === AgentState.STOPPED) return;
+			this.spawnAgent(agent);
+		}, delay);
+	}
+
+	private transition(agent: AgentProcess, next: AgentState): void {
+		const allowed = TRANSITIONS[agent.state];
+		if (!allowed.includes(next)) {
+			throw new Error(
+				`illegal agent transition ${agent.state} -> ${next} (agent ${agent.spec.agentId})`,
+			);
+		}
+		agent.state = next;
+	}
+}

package/lib/supervisor_config.ts

@@ -0,0 +1,121 @@
+/**
+ * Supervisor config parsing (#280 step-12, slice 4).
+ *
+ * Turns a JSON config (or the parsed object) into validated `AgentSpec`s for the
+ * Supervisor. Kept pure + separate from the entry point so it is unit-testable.
+ *
+ * Config shape:
+ *   {
+ *     "agents": [
+ *       { "id": "reviewer", "tier": "read", "args": ["--await-invite"] },
+ *       { "tier": "chat", "count": 2 }            // count → N agents of this tier
+ *     ]
+ *   }
+ *
+ * Defaults: `args` → ["--await-invite"] (the control plane pushes the conversation,
+ * #280 step-03); a missing `id` is generated as `agent-<n>`; `count` (default 1)
+ * expands to that many specs with suffixed ids.
+ */
+
+import type { AgentSpec } from "./supervisor.ts";
+
+const VALID_TIERS = ["chat", "read", "write"] as const;
+type Tier = (typeof VALID_TIERS)[number];
+
+function isTier(v: unknown): v is Tier {
+	return typeof v === "string" && VALID_TIERS.some((t) => t === v);
+}
+
+interface RawAgent {
+	id?: unknown;
+	tier?: unknown;
+	args?: unknown;
+	count?: unknown;
+	env?: unknown;
+}
+
+function parseArgsField(raw: unknown): string[] {
+	if (raw === undefined) return ["--await-invite"];
+	if (!Array.isArray(raw) || raw.some((a) => typeof a !== "string")) {
+		throw new Error("agent.args must be an array of strings");
+	}
+	return raw as string[];
+}
+
+function parseEnvField(raw: unknown): Record<string, string> | undefined {
+	if (raw === undefined || raw === null) return undefined;
+	if (typeof raw !== "object" || Array.isArray(raw)) {
+		throw new Error("agent.env must be an object");
+	}
+	const out: Record<string, string> = {};
+	for (const [k, v] of Object.entries(raw as Record<string, unknown>)) {
+		if (typeof v !== "string") throw new Error(`agent.env.${k} must be a string`);
+		out[k] = v;
+	}
+	return out;
+}
+
+function parseCount(raw: unknown): number {
+	if (raw === undefined) return 1;
+	if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 1 || raw > 64) {
+		throw new Error("agent.count must be an integer between 1 and 64");
+	}
+	return raw;
+}
+
+/**
+ * Parse a supervisor config object into a flat list of AgentSpecs.
+ * Throws on any malformed entry (fail fast at launch). Agent ids are unique:
+ * a duplicate explicit id throws; generated ids never collide.
+ */
+export function parseSupervisorConfig(raw: unknown): AgentSpec[] {
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+		throw new Error("supervisor config must be an object");
+	}
+	const agents = (raw as { agents?: unknown }).agents;
+	if (!Array.isArray(agents) || agents.length === 0) {
+		throw new Error("supervisor config must have a non-empty `agents` array");
+	}
+
+	const specs: AgentSpec[] = [];
+	const seen = new Set<string>();
+	let generated = 0;
+
+	for (const entry of agents as RawAgent[]) {
+		if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+			throw new Error("each agent must be an object");
+		}
+		if (!isTier(entry.tier)) {
+			throw new Error(`agent.tier must be one of: ${VALID_TIERS.join(", ")}`);
+		}
+		let explicitId: string | undefined;
+		if (entry.id !== undefined) {
+			if (typeof entry.id !== "string" || entry.id.trim() === "") {
+				throw new Error("agent.id must be a non-empty string");
+			}
+			explicitId = entry.id;
+		}
+		const args = parseArgsField(entry.args);
+		const env = parseEnvField(entry.env);
+		const count = parseCount(entry.count);
+
+		for (let i = 0; i < count; i++) {
+			// count > 1 suffixes the explicit id (rev-1, rev-2…); a single agent keeps
+			// the bare id. NOTE: bumping count 1→2 thus renames `rev`→`rev-1`.
+			let id: string;
+			if (explicitId !== undefined) {
+				id = count > 1 ? `${explicitId}-${i + 1}` : explicitId;
+			} else {
+				generated += 1;
+				id = `agent-${generated}`;
+			}
+			if (seen.has(id)) throw new Error(`duplicate agent id: ${id}`);
+			seen.add(id);
+			// Independent args array per spec so a later mutation can't bleed across
+			// count-expanded siblings.
+			specs.push({ agentId: id, tier: entry.tier, args: [...args], ...(env ? { env } : {}) });
+		}
+	}
+
+	return specs;
+}