petbox-wire 0.1.0-ci.1206

package/src/doctor-definition.test.ts

@@ -0,0 +1,128 @@
+// Integration test for doctor gating the SAME definition apply would compile
+// (bug: doctor-gates-wrong-definition).
+//
+// wire.ts runs main() at import time (see its own comment on why testable logic lives in side
+// modules), so the only way to exercise `doctor`'s actual argv/behavior end-to-end is to spawn
+// it as a real subprocess — same technique CI itself uses (`node src/wire.ts <args>`). This test
+// seeds a fake ~/.petbox (via USERPROFILE/HOME redirection) with:
+//   - a registry entry for a throwaway project directory (identity)
+//   - an API key in the key store for that project's env var (resolveProject requires one)
+//   - an LKG agent-definition cache carrying a definition whose name is NOT "default" (the
+//     built-in DEFAULT_AGENT_DEFINITION.name), so the two are trivially distinguishable
+//
+// Before the fix, `doctor` ignored all of this and always gated the hard-coded
+// DEFAULT_AGENT_DEFINITION (name "default") — so its output would show `definition="default"`
+// even with a differently-named LKG cache sitting right there, identical to what `apply
+// --offline` would use. After the fix, `doctor --offline` must report the LKG-cached name.
+//
+// Run: node --test src/doctor-definition.test.ts
+
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+
+const WIRE_TS = join(import.meta.dirname, "wire.ts");
+
+function freshDir(prefix: string): string {
+  return realpathSync(mkdtempSync(join(tmpdir(), prefix)));
+}
+
+// A minimal but shape-valid AgentDefinition + cache envelope (agent-def-fetch.ts's
+// AgentDefCacheRecord / parseAgentDefinitionResponse contract).
+function makeCustomDefRecord(name: string) {
+  return {
+    key: "default",
+    version: 7,
+    fetchedAt: new Date().toISOString(),
+    definition: {
+      name,
+      roles: [
+        {
+          slug: "worker",
+          tier: "worker",
+          requiredCapabilities: [],
+        },
+      ],
+    },
+  };
+}
+
+function runDoctor(cwd: string, homeDir: string, extraArgs: string[] = []): { stdout: string; stderr: string; status: number | null } {
+  const res = spawnSync(process.execPath, [WIRE_TS, "doctor", ...extraArgs], {
+    cwd,
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      // Windows resolves homedir() from USERPROFILE; POSIX from HOME. Set both so the test is
+      // portable across the dev machine (win32) and any Linux CI runner.
+      USERPROFILE: homeDir,
+      HOME: homeDir,
+      HOMEDRIVE: undefined,
+      HOMEPATH: undefined,
+    },
+  });
+  return { stdout: res.stdout ?? "", stderr: res.stderr ?? "", status: res.status };
+}
+
+test("doctor --offline gates the LKG-cached definition, not the hard-coded built-in default", () => {
+  const homeDir = freshDir("petbox-doctor-home-");
+  const projectDir = freshDir("petbox-doctor-proj-");
+  try {
+    const petboxDir = join(homeDir, ".petbox");
+    mkdirSync(petboxDir, { recursive: true });
+    mkdirSync(join(petboxDir, "cache"), { recursive: true });
+
+    const envVar = "PETBOX_DOCTOR_TEST_API_KEY";
+    writeFileSync(
+      join(petboxDir, "projects.json"),
+      JSON.stringify({ entries: [{ prefix: projectDir, project: "doctor-test-proj", envVar }] }, null, 2),
+      "utf8",
+    );
+    writeFileSync(join(petboxDir, "keys.json"), JSON.stringify({ [envVar]: "fake-key-value" }, null, 2), "utf8");
+    writeFileSync(
+      join(petboxDir, "cache", "doctor-test-proj.agent-def.json"),
+      JSON.stringify(makeCustomDefRecord("custom-lkg-def"), null, 2),
+      "utf8",
+    );
+
+    const { stdout, stderr, status } = runDoctor(projectDir, homeDir, ["--offline"]);
+    const out = stdout + stderr;
+
+    assert.match(
+      out,
+      /definition="custom-lkg-def"/,
+      `doctor must gate the LKG-cached definition (custom-lkg-def), not the built-in default. Full output:\n${out}`,
+    );
+    assert.doesNotMatch(
+      out,
+      /definition="default"/,
+      `doctor must NOT fall back to the built-in DEFAULT_AGENT_DEFINITION when an LKG cache exists. Full output:\n${out}`,
+    );
+    assert.match(out, /using LKG definition/, "doctor must name which link it resolved (LKG here)");
+    // The custom def's single worker role has no requiredCapabilities, so every known harness
+    // passes trivially — doctor should exit clean.
+    assert.equal(status, 0);
+  } finally {
+    rmSync(homeDir, { recursive: true, force: true });
+    rmSync(projectDir, { recursive: true, force: true });
+  }
+});
+
+test("doctor --offline with NO registry entry / NO LKG cache falls back to the built-in default (unchanged behavior)", () => {
+  const homeDir = freshDir("petbox-doctor-home-");
+  const projectDir = freshDir("petbox-doctor-proj-");
+  try {
+    // No ~/.petbox at all — doctor must still work offline against the built-in default.
+    const { stdout, stderr, status } = runDoctor(projectDir, homeDir, ["--offline"]);
+    const out = stdout + stderr;
+    assert.match(out, /definition="default"/, `expected the built-in default when nothing is registered. Full output:\n${out}`);
+    assert.match(out, /offline default definition/);
+    assert.equal(status, 0);
+  } finally {
+    rmSync(homeDir, { recursive: true, force: true });
+    rmSync(projectDir, { recursive: true, force: true });
+  }
+});

package/src/droid-pull-memory.ts

@@ -0,0 +1,126 @@
+// Factory Droid SessionStart hook (global) — the droid port of pull-memory.ts.
+//
+// Injects the PetBox memory protocol + curated canon so the agent recalls relevant memory at
+// session start and captures learnings as it works, via the already-connected petbox MCP.
+//
+// Droid names MCP tools `<server>___<tool>` (triple underscore) at runtime — observed live
+// in exec mode; the docs' `mcp__<server>__<tool>` form did not match. The protocol renders
+// with droidPetboxTool (`petbox___*`); the canon block stays byte-identical across agents. Droid's SessionStart stdin
+// is snake_case (`session_id`, `transcript_path`, `cwd`, `source`), the same shape Claude Code
+// uses, so we resolve the project from `cwd` and pass `source` through for the resume nudge.
+//
+// Output contract (docs): a SessionStart hook returns context to the model via the structured
+// JSON `{ hookSpecificOutput: { hookEventName: "SessionStart", additionalContext } }` on stdout
+// (stdout-as-context is also accepted, but the structured form is the documented preference).
+//
+// Best-effort, always exit 0, no output for an unregistered cwd.
+//
+// The banner's orchestrator notes resolve server → LKG cache → built-in default, same as
+// `apply` (resolveAgentDefinitionForSession, wrapping agent-def-fetch.ts's
+// resolveAgentDefinitionWithLkg). That fetch and the canon fetch run SEQUENTIALLY under one
+// shared SESSION_FETCH_BUDGET_MS wall-clock budget (not Promise.all'd) — verbatim the same
+// reasoning as pull-memory.ts (this file's Claude Code counterpart): the happy path for both
+// requests together is ~100-200ms, so concurrency bought nothing there, and it made the two
+// independent 8s timeouts stack in the worst case if reasoned about naively. Giving the whole
+// hook one budget means whatever the agent-def fetch doesn't spend, the canon fetch inherits
+// as its own timeout, so the combined worst case stays ~SESSION_FETCH_BUDGET_MS, not 2x it. A
+// fetch that starts with little/no budget left degrades to its own fallback (LKG cache /
+// built-in default / no canon) rather than blocking — see canon.ts's fetchCanon.
+
+import { resolveAgentDefinitionForSession } from "./agent-def-fetch.ts";
+import { fetchCanonBlock } from "./canon.ts";
+import { unrefLingeringHandles } from "./hook-drain.ts";
+import { buildProtocol, droidPetboxTool } from "./protocol.ts";
+import { resolveProject } from "./registry.ts";
+
+// Shared wall-clock budget for BOTH fetches combined (agent-def, then canon) — see the
+// module comment above. Kept in step with pull-memory.ts: short on purpose, because the LKG
+// cache holds the same documents and a redeploy restarting the server must not tax every
+// session start with an 8s stall. Stale-but-instant beats fresh-but-late here.
+const SESSION_FETCH_BUDGET_MS = 2000;
+
+type HookInput = { cwd?: string; source?: string };
+
+function readStdin(): Promise<string> {
+  return new Promise((resolve) => {
+    let buf = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (c) => (buf += c));
+    process.stdin.on("end", () => resolve(buf));
+    process.stdin.on("error", () => resolve(buf));
+  });
+}
+
+// process.stdout.write() on a Windows pipe is asynchronous — the call can return before the
+// OS-level write completes. Awaiting the write callback guarantees the context JSON is fully
+// flushed before main() resolves, so the process never ends mid-write and truncates it (see
+// pull-memory.ts's identical helper for the full rationale).
+function writeStdout(text: string): Promise<void> {
+  return new Promise((resolve) => {
+    if (text.length === 0) {
+      resolve();
+      return;
+    }
+    process.stdout.write(text, () => resolve());
+  });
+}
+
+async function main(): Promise<void> {
+  let source = "startup";
+  let cwd = "";
+  try {
+    const raw = await readStdin();
+    const j: HookInput = JSON.parse(raw);
+    if (typeof j.source === "string" && j.source.trim()) source = j.source.trim();
+    if (typeof j.cwd === "string") cwd = j.cwd;
+  } catch {
+    // fall through with defaults; cwd stays empty → resolves to null below
+  }
+
+  try {
+    const resolved = resolveProject(cwd);
+    if (!resolved) return; // not a registered project → no output
+
+    // Sequential under one shared budget (not Promise.all): whatever the first fetch doesn't
+    // spend is what the second gets, so the combined worst case is bounded by
+    // SESSION_FETCH_BUDGET_MS instead of stacking two independent timeouts.
+    const budgetStart = Date.now();
+    const defResult = await resolveAgentDefinitionForSession(resolved, {
+      timeoutMs: SESSION_FETCH_BUDGET_MS,
+    });
+    const remainingMs = SESSION_FETCH_BUDGET_MS - (Date.now() - budgetStart);
+    const canon = await fetchCanonBlock(resolved, { timeoutMs: remainingMs });
+
+    let context = buildProtocol(resolved.project, droidPetboxTool, {
+      source,
+      harness: "droid",
+      definition: defResult.definition,
+    });
+    // Append the curated memory canon when available (best-effort; degrades to nothing).
+    if (canon) context += `\n\n${canon}`;
+    const out = {
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext: context,
+      },
+    };
+    await writeStdout(JSON.stringify(out));
+  } catch {
+    // best-effort
+  }
+}
+
+// Exit cleanly instead of tearing the process down mid-close: a hard process.exit() while
+// libuv handles from the concurrent HTTP fetches are still closing raced Windows' async
+// handle teardown (`Assertion failed: !(handle->flags & UV_HANDLE_CLOSING), src\win\async.c`)
+// and could truncate the stdout write above (fire-and-forget on a Windows pipe) — the same
+// crash observed in pull-memory.ts (see its exit comment). Setting exitCode and returning lets
+// Node drain the event loop naturally instead — `Connection: close` (canon.ts /
+// agent-def-fetch.ts) covers a completed fetch, and unrefLingeringHandles covers a fetch
+// aborted mid-flight against a stalled server (measured to leave its TLSSocket alive for
+// several more seconds otherwise; see hook-drain.ts) so a slow session start can't turn into
+// a multi-second stall on a handle nothing is still using.
+main().finally(() => {
+  process.exitCode = 0;
+  unrefLingeringHandles();
+});

package/src/droid-push-session.ts

@@ -0,0 +1,100 @@
+// Factory Droid Stop hook (global) — the droid port of push-session.ts.
+//
+// Mirrors the session conversation into PetBox's Session module so the board auto-populates.
+// The project + API key are resolved from cwd via the shared registry; if the cwd is not a
+// registered project this exits immediately (first guard, before any work).
+//
+// Droid's Stop stdin is snake_case (`session_id`, `transcript_path`, `cwd`, `stop_hook_active`)
+// — the same shape Claude Code uses. We parse the droid JSONL (buildDroidMessages: user/
+// assistant TEXT turns only, tool dumps + `<system-reminder>` injections excluded) and push
+// only the INCREMENT via the server-authoritative append cursor (see append.ts): this process
+// is fresh each turn, so it passes null and pushTranscript optimistically resends a small
+// idempotent overlap window; a contiguity gap comes back as a structured 409 with the server's
+// lastOrdinal and the tail is resent from there. Old servers without the append route fall back
+// to the legacy full-snapshot push. Best-effort: every failure is swallowed and we ALWAYS
+// exit 0 — never break the user's session.
+
+import { pushTranscript } from "./append.ts";
+import { buildDroidMessages } from "./droid-transcript.ts";
+import { unrefLingeringHandles } from "./hook-drain.ts";
+import { resolveProject } from "./registry.ts";
+import type { Msg } from "./transcript.ts";
+
+const FETCH_TIMEOUT_MS = 12000;
+
+type HookInput = {
+  session_id?: string;
+  transcript_path?: string;
+  cwd?: string;
+  stop_hook_active?: boolean;
+};
+
+function readStdin(): Promise<string> {
+  return new Promise((resolve) => {
+    let buf = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (c) => (buf += c));
+    process.stdin.on("end", () => resolve(buf));
+    process.stdin.on("error", () => resolve(buf));
+  });
+}
+
+async function main(): Promise<void> {
+  try {
+    const raw = await readStdin();
+    let j: HookInput;
+    try {
+      j = JSON.parse(raw);
+    } catch {
+      return;
+    }
+    if (j.stop_hook_active) return;
+
+    // FIRST guard: not a registered project → silent no-op (before any file/network work).
+    const resolved = resolveProject(j.cwd ?? "");
+    if (!resolved) return;
+
+    const sid = (j.session_id ?? "").trim();
+    const tp = (j.transcript_path ?? "").trim();
+    if (!sid || !tp) return;
+
+    let msgs: Msg[];
+    try {
+      msgs = await buildDroidMessages(tp);
+    } catch {
+      return; // transcript missing/unreadable
+    }
+    if (msgs.length === 0) return; // empty body → server returns 400, don't push
+
+    // Fresh process each turn → no remembered cursor (null): pushTranscript guesses an
+    // idempotent overlap window and self-heals off the server's structured gap reject.
+    await pushTranscript(
+      {
+        baseUrl: resolved.baseUrl,
+        project: resolved.project,
+        sessionId: sid,
+        apiKey: resolved.apiKey,
+        agent: "droid",
+        timeoutMs: FETCH_TIMEOUT_MS,
+      },
+      msgs,
+      null,
+    );
+  } catch {
+    // best-effort: never break the user's session
+  }
+}
+
+// Exit cleanly instead of tearing the process down mid-close: a hard process.exit() while
+// libuv handles from the HTTP push above are still closing can race Windows' async handle
+// teardown (`Assertion failed: !(handle->flags & UV_HANDLE_CLOSING), src\win\async.c`) — the
+// same crash observed in pull-memory.ts (see its exit comment). Setting exitCode and returning
+// lets Node drain the event loop naturally instead — `Connection: close` (append.ts) covers a
+// completed push, and unrefLingeringHandles covers a push aborted mid-flight against a stalled
+// server (measured to leave its TLSSocket alive for several more seconds otherwise; see
+// hook-drain.ts) so a slow Stop hook can't turn into a multi-second stall on a handle nothing
+// is still using.
+main().finally(() => {
+  process.exitCode = 0;
+  unrefLingeringHandles();
+});

package/src/droid-transcript.ts

@@ -0,0 +1,47 @@
+// Factory Droid transcript parsing — the droid analogue of transcript.ts, kept as a thin
+// adapter over the SHARED text-extraction/exclusion rules so what a "session turn" is cannot
+// drift between agents (spec: agent-wiring, wiring-single-source).
+//
+// A droid transcript is JSONL, but its record shape differs from Claude Code's:
+//   - line 1 is `{type:"session_start", id, title, cwd, ...}` (skipped);
+//   - each turn is `{type:"message", message:{role, content}}` where content is either a
+//     string or an array of parts `{type:"text"|"thinking"|"tool_use"|"tool_result", ...}`.
+// We keep the user/assistant TEXT turns in order and drop tool_use/tool_result/thinking dumps
+// and harness chrome — reusing extractText (text-parts only) + isExcluded (`<system-reminder>`
+// and friends) from transcript.ts so both agents share one definition. Droid also flags
+// injected context with `visibility:"llm_only"`; we skip those too as a belt-and-suspenders
+// guard alongside the system-reminder prefix check.
+//
+// Plain TS for native node type-stripping: zero deps.
+
+import { createReadStream } from "node:fs";
+import { createInterface } from "node:readline";
+import { extractText, isExcluded, type Msg } from "./transcript.ts";
+
+// Collect the user/assistant text messages in droid transcript order. No rendering and no
+// cap: the server needs the full, ordered transcript to assign stable per-message ordinals.
+export async function buildDroidMessages(transcriptPath: string): Promise<Msg[]> {
+  const rl = createInterface({
+    input: createReadStream(transcriptPath, { encoding: "utf8" }),
+    crlfDelay: Infinity,
+  });
+  const msgs: Msg[] = [];
+  for await (const line of rl) {
+    if (!line || line.trim().length === 0) continue;
+    let e: any;
+    try {
+      e = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (e.type !== "message" || !e.message) continue;
+    const role = e.message.role;
+    if (role !== "user" && role !== "assistant") continue;
+    if (e.message.visibility === "llm_only") continue; // injected context, not a real turn
+    const text = extractText(e.message);
+    if (text.length === 0) continue; // thinking/tool_use/tool_result-only turn → no text
+    if (isExcluded(text)) continue; // <system-reminder> / harness chrome
+    msgs.push({ role, content: text });
+  }
+  return msgs;
+}

package/src/harness-capabilities.ts

@@ -0,0 +1,126 @@
+// Per-harness capability matrix for the agent-artifact compiler.
+//
+// Spec (definition-truthfulness, per-harness-artifact): a role may only require
+// capabilities the target harness declares. This matrix is kit data (versioned with
+// the npm package) — capabilities change with harness versions, not with the
+// portable agent definition.
+//
+// EVERY cell is a factual claim about a harness, taken from that harness's docs
+// (or a verified live observation). Do not invent; do not copy another harness's row.
+//
+// Plain TS for native node type-stripping: zero deps.
+
+export type HarnessId = "claude-code" | "opencode" | "droid";
+
+/** Capability ids a role may list in requiredCapabilities. */
+export type Capability =
+  | "mcp_main_session"
+  | "mcp_subagent"
+  | "dynamic_model_at_spawn"
+  | "role_files"
+  | "builtin_explore_inherits_model"
+  | "hooks"
+  | "spawn_subagents";
+
+export const HARNESS_IDS: readonly HarnessId[] = ["claude-code", "opencode", "droid"] as const;
+
+export const CAPABILITIES: readonly Capability[] = [
+  "mcp_main_session",
+  "mcp_subagent",
+  "dynamic_model_at_spawn",
+  "role_files",
+  "builtin_explore_inherits_model",
+  "hooks",
+  "spawn_subagents",
+] as const;
+
+/**
+ * Capability matrix — sources cited per cell.
+ *
+ * claude-code (verified live 2026-07-10 + 2026-07-12 + Anthropic Claude Code agent docs):
+ *   mcp_main_session — main session has MCP.
+ *   mcp_subagent — declared (verified live 2026-07-12: a subagent with an unrestricted
+ *     tool set called an MCP tool, mcp__petbox__whoami, successfully). The earlier
+ *     "subagents lack MCP" note (2026-07-10) was an artifact of a hand-written
+ *     ~/.claude/agents/worker.md `tools:` whitelist that hid MCP — not a harness limit.
+ *   dynamic_model_at_spawn — model passed dynamically at Agent/Task spawn.
+ *   role_files — project/user agents under .claude/agents/*.md.
+ *   builtin_explore_inherits_model — built-in Explore inherits parent model by default.
+ *   hooks — SessionStart/Stop/UserPromptSubmit hook surface.
+ *   spawn_subagents — main session spawns via Agent/Task tool; subagents do not re-spawn.
+ *
+ * opencode:
+ *   mcp_main_session / mcp_subagent — plugin injects system text with no main/subagent
+ *     branching; MCP tools available the same way in both (kit observation).
+ *   dynamic_model_at_spawn — NOT declared (opencode PR #18588: model not dynamic at spawn;
+ *     roles are files only).
+ *   role_files — .opencode/agent/*.md.
+ *   builtin_explore_inherits_model — built-in explore inherits parent model.
+ *   hooks — not a first-class CC-hook surface; leave undeclared.
+ *   spawn_subagents — can spawn subagents (agent types / Task-equivalent).
+ *
+ * droid (Factory official docs — do not reintroduce enableHooks-MCP assumptions):
+ *   role_files — custom droids in .factory/droids/*.md (project) and ~/.factory/droids/
+ *     (user); project overrides user on name clash.
+ *     https://docs.factory.ai/cli/configuration/custom-droids
+ *   spawn_subagents — main session spawns via Task tool (subagent_type = built-in or
+ *     custom droid name); subagents cannot spawn further (Task unavailable to them).
+ *     https://docs.factory.ai/cli/configuration/custom-droids
+ *   dynamic_model_at_spawn — droid frontmatter model: inherit | explicit id; inherit
+ *     follows parent / complexity routing.
+ *     https://docs.factory.ai/cli/configuration/custom-droids § Controlling the model
+ *   mcp_main_session — MCP via .factory/mcp.json (user/folder/project).
+ *     https://docs.factory.ai/cli/configuration/mcp
+ *   mcp_subagent — custom droid mcpServers frontmatter scopes which configured MCP
+ *     servers the subagent receives.
+ *     https://docs.factory.ai/cli/configuration/custom-droids § Selecting MCP servers
+ *   hooks — Factory settings hooks (Stop/SessionStart/UserPromptSubmit) used by the kit.
+ *   builtin_explore_inherits_model — NOT declared: Factory ships built-in `explorer` with
+ *     model inherit, but we do not equate it to CC/opencode "Explore" without a separate
+ *     verification pass (leave honestly unspecified).
+ *   Hierarchy note: org/project/folder/user settings; write project-level .factory/droids/
+ *     only (additive). https://docs.factory.ai/enterprise/hierarchical-settings-and-org-control
+ */
+const MATRIX: Readonly<Record<HarnessId, readonly Capability[]>> = {
+  "claude-code": [
+    "mcp_main_session", // live: main has MCP
+    "mcp_subagent", // live 2026-07-12: unrestricted subagent called mcp__petbox__whoami
+    "dynamic_model_at_spawn", // model at Agent/Task spawn
+    "role_files", // .claude/agents/*.md
+    "builtin_explore_inherits_model", // built-in Explore inherits parent
+    "hooks", // SessionStart/Stop/UserPromptSubmit
+    "spawn_subagents", // main spawns; subagents do not re-spawn
+  ],
+  opencode: [
+    "mcp_main_session", // same MCP surface main/sub (no branching inject)
+    "mcp_subagent", // subagents see MCP like main
+    "role_files", // .opencode/agent/*.md
+    "builtin_explore_inherits_model", // built-in explore inherits
+    "spawn_subagents", // can spawn agent types
+    // no dynamic_model_at_spawn — PR #18588
+    // no hooks — not CC-hook surface
+  ],
+  droid: [
+    "mcp_main_session", // docs: .factory/mcp.json — https://docs.factory.ai/cli/configuration/mcp
+    "mcp_subagent", // docs: mcpServers on custom droid — custom-droids § Selecting MCP servers
+    "spawn_subagents", // docs: Task tool from main — custom-droids
+    "role_files", // docs: .factory/droids/*.md — custom-droids
+    "dynamic_model_at_spawn", // docs: model inherit | explicit — custom-droids § model
+    "hooks", // kit uses Factory settings hooks
+    // no builtin_explore_inherits_model — explorer exists but not equated to CC Explore here
+  ],
+};
+
+/** Known capability set for a harness id. Unknown id → empty set (never invent). */
+export function harnessCapabilities(harness: string): ReadonlySet<string> {
+  const list = (MATRIX as Record<string, readonly Capability[] | undefined>)[harness];
+  return new Set(list ?? []);
+}
+
+export function isKnownHarness(id: string): id is HarnessId {
+  return (HARNESS_IDS as readonly string[]).includes(id);
+}
+
+export function hasCapability(harness: string, capability: string): boolean {
+  return harnessCapabilities(harness).has(capability);
+}