@fcon-tech/portolan 0.4.5

package/adapters/opencode/install.ts

@@ -0,0 +1,357 @@
+#!/usr/bin/env bun
+/**
+ * The opencode adapter — launch configuration only (design.md, decision 5).
+ *
+ * Registers the Portolan MCP server in an opencode config by writing the
+ * `mcp.portolan` block opencode expects:
+ *
+ *   {
+ *     "$schema": "https://opencode.ai/config.json",
+ *     "mcp": {
+ *       "portolan": {
+ *         "type": "local",
+ *         "command": ["bunx", "--package", "@fcon-tech/portolan", "portolan",
+ *                     "serve", "--target", "<province>"]
+ *       }
+ *     }
+ *   }
+ *
+ * The launch line resolves the published npm package (`bunx`), so the
+ * installer works without a clone of this repository — no repo path is
+ * written into the config.
+ *
+ * The skill ships inside the same package and is COPIED into the harness's
+ * fixed skills directory (`~/.config/opencode/skills/<frontmatter name>/`;
+ * opencode resolves skills only from fixed locations — project
+ * `.opencode/skills/` or that global dir — so a reference into the package
+ * would never load). The copy is idempotent: a re-install overwrites.
+ * (pi and omp likewise resolve only their own global dirs —
+ * `~/.pi/agent/skills/`, `~/.omp/agent/skills/`, plus `~/.agents/skills/` —
+ * their installers belong in their adapters, not here.)
+ *
+ * (Shape verified against opencode 1.18.21's own `opencode mcp add`.)
+ * opencode config files are JSONC (comments and trailing commas allowed), so
+ * the merge is text surgery through a small JSONC scanner: the user's
+ * comments, formatting, and every other key survive verbatim. Only the
+ * `mcp.portolan` block is inserted or replaced. Adapters must not import
+ * tool logic; the boundary is checked by core/src/server/adapter-boundary.ts.
+ *
+ * Usage:
+ *   bun adapters/opencode/install.ts --target /path/to/province
+ *   bun adapters/opencode/install.ts --target . --config ~/proj/opencode.jsonc
+ */
+import { cpSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+
+// The skill source is resolved relative to THIS file, so the same installer
+// works from a clone (repo skill/) and from the published package
+// (node_modules/@fcon-tech/portolan/skill/ — the files allowlist ships it).
+const SKILL_SOURCE = join(import.meta.dir, "..", "..", "skill");
+
+const { values } = parseArgs({
+  allowPositionals: false,
+  options: {
+    target: { type: "string" },
+    config: { type: "string" },
+  },
+});
+
+if (values.target === undefined) {
+  console.error("usage: bun adapters/opencode/install.ts --target <province root> [--config <opencode.jsonc>]");
+  process.exit(1);
+}
+
+const province = resolve(values.target);
+
+/**
+ * The user-level config root. Neither variable set is an environment error:
+ * silently falling back to "." would scatter configs into the cwd.
+ */
+function configHome(): string {
+  const xdg = process.env.XDG_CONFIG_HOME;
+  if (xdg !== undefined && xdg !== "") return xdg;
+  const home = process.env.HOME;
+  if (home === undefined || home === "") {
+    console.error(
+      "error: neither XDG_CONFIG_HOME nor HOME is set — cannot locate the opencode config directory. Set one and retry.",
+    );
+    process.exit(1);
+  }
+  return join(home, ".config");
+}
+
+const configPath =
+  values.config !== undefined
+    ? resolve(values.config)
+    : join(configHome(), "opencode", "opencode.jsonc");
+
+// The launch line resolves the published package via bunx: opencode spawns
+// it verbatim; the only path is the absolute province target.
+const launchCommand = [
+  "bunx",
+  "--package",
+  "@fcon-tech/portolan",
+  "portolan",
+  "serve",
+  "--target",
+  province,
+];
+const portolanBlock = `{ "type": "local", "command": ${JSON.stringify(launchCommand)}, "enabled": true }`;
+
+// ---------------------------------------------------------------------------
+// A minimal JSONC scanner. It walks the text once, tracking strings,
+// escapes, and both comment kinds, and produces two things:
+//   - a cleaned copy (comments blanked) for JSON.parse validation with
+//     trailing commas handled;
+//   - structural spans ({ ... } pairs) so the merge can do exact text
+//     surgery instead of a rewrite that would destroy user comments.
+// ---------------------------------------------------------------------------
+
+interface Span {
+  open: number; // index of '{'
+  close: number; // index of matching '}'
+}
+
+/** Blank out comments (keeping offsets stable) and return structural spans in order. */
+function scanJsonc(text: string): { cleaned: string; spans: Span[] } {
+  const chars = text.split("");
+  const spans: Span[] = [];
+  const openStack: number[] = [];
+  let i = 0;
+  let inString = false;
+  while (i < text.length) {
+    const c = text[i];
+    if (inString) {
+      if (c === "\\") {
+        i += 2;
+        continue;
+      }
+      if (c === '"') inString = false;
+      i++;
+      continue;
+    }
+    if (c === '"') {
+      inString = true;
+      i++;
+      continue;
+    }
+    if (c === "/" && text[i + 1] === "/") {
+      while (i < text.length && text[i] !== "\n") {
+        chars[i] = " ";
+        i++;
+      }
+      continue;
+    }
+    if (c === "/" && text[i + 1] === "*") {
+      while (i < text.length && !(text[i] === "*" && text[i + 1] === "/")) {
+        chars[i] = text[i] === "\n" ? "\n" : " ";
+        i++;
+      }
+      if (i < text.length) {
+        chars[i] = " ";
+        chars[i + 1] = " ";
+        i += 2;
+      }
+      continue;
+    }
+    if (c === "{") {
+      openStack.push(i);
+      i++;
+      continue;
+    }
+    if (c === "}") {
+      const open = openStack.pop();
+      if (open !== undefined) spans.push({ open, close: i });
+      i++;
+      continue;
+    }
+    i++;
+  }
+  if (openStack.length > 0) throw new Error("unbalanced braces in config");
+  if (inString) throw new Error("unterminated string in config");
+  return { cleaned: chars.join(""), spans };
+}
+
+/** Parse JSONC for validation: comments blanked, trailing commas dropped. */
+function parseJsonc(text: string): unknown {
+  const { cleaned } = scanJsonc(text);
+  const noTrailing = cleaned.replace(/,(\s*[}\]])/g, "$1");
+  return JSON.parse(noTrailing);
+}
+
+/** The innermost span whose '{' sits at cleaned[start]; expects text[start] === '{'. */
+function spanStartingAt(spans: Span[], start: number): Span {
+  const span = spans.find((s) => s.open === start);
+  if (span === undefined) throw new Error("no object found where one was expected");
+  return span;
+}
+
+/** Find a direct property key of the object `obj` whose name matches; return the index of its ':' or -1. */
+function findPropertyColon(cleaned: string, obj: Span, spans: Span[], key: string): number {
+  const search = `"${key}"`;
+  for (let i = obj.open + 1; i < obj.close; i++) {
+    if (!cleaned.startsWith(search, i)) continue;
+    // The key must sit directly inside this object: its innermost enclosing
+    // span (ignoring strings/comments via the cleaned copy) is obj itself.
+    const enclosing = spans
+      .filter((s) => s.open < i && s.close > i && s.open >= obj.open && s.close <= obj.close)
+      .sort((a, b) => b.open - a.open)[0];
+    if (enclosing === undefined || enclosing.open === obj.open) {
+      const colon = cleaned.indexOf(":", i + search.length);
+      if (colon !== -1 && colon < obj.close) return colon;
+    }
+  }
+  return -1;
+}
+
+/**
+ * Upsert `mcp.portolan` into JSONC text, preserving everything else verbatim.
+ * Returns the merged text.
+ */
+function upsertPortolan(text: string): string {
+  const { cleaned, spans } = scanJsonc(text);
+  const root = spanStartingAt(spans, cleaned.indexOf("{"));
+  const mcpColon = findPropertyColon(cleaned, root, spans, "mcp");
+  const block = `"portolan": ${portolanBlock}`;
+
+  if (mcpColon !== -1) {
+    // The mcp object starts at the first '{' after its colon.
+    const mcpOpen = cleaned.indexOf("{", mcpColon);
+    const mcpSpan = spanStartingAt(spans, mcpOpen);
+    const portolanColon = findPropertyColon(cleaned, mcpSpan, spans, "portolan");
+    if (portolanColon !== -1) {
+      // Replace the existing value: from the value start to its end (the
+      // innermost span starting after the colon, else up to ',' or '}').
+      const nextBrace = cleaned.indexOf("{", portolanColon);
+      let valueEnd: number;
+      if (nextBrace !== -1 && nextBrace < mcpSpan.close && spans.some((s) => s.open === nextBrace)) {
+        valueEnd = spanStartingAt(spans, nextBrace).close + 1;
+      } else {
+        // Non-object value: up to the next ',' or the mcp closing brace.
+        const comma = cleaned.indexOf(",", portolanColon);
+        valueEnd = comma !== -1 && comma < mcpSpan.close ? comma : mcpSpan.close;
+      }
+      return text.slice(0, portolanColon + 1) + " " + portolanBlock + text.slice(valueEnd);
+    }
+    // Insert as the first property of mcp, right after its opening brace.
+    return text.slice(0, mcpSpan.open + 1) + `\n    ${block},` + text.slice(mcpSpan.open + 1);
+  }
+
+  // No mcp key: insert one before the root's closing brace.
+  const before = text.slice(0, root.close);
+  const hasKeys = cleaned.slice(root.open + 1, root.close).trim().length > 0;
+  const insert = `${hasKeys ? "," : ""}\n  "mcp": { ${block} }`;
+  return before + insert + text.slice(root.close);
+}
+
+let finalText: string;
+if (existsSync(configPath)) {
+  const text = readFileSync(configPath, "utf8");
+  let parsed: unknown;
+  try {
+    parsed = parseJsonc(text);
+  } catch (err) {
+    console.error(
+      `cannot merge into ${configPath}: not a JSON/JSONC document (${err instanceof Error ? err.message : String(err)}).\n` +
+        `Add this block by hand under "mcp":\n\n` +
+        `  "portolan": {\n` +
+        `    "type": "local",\n` +
+        `    "command": ${JSON.stringify(launchCommand)}\n` +
+        `  }\n`,
+    );
+    process.exit(1);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    console.error(`cannot merge into ${configPath}: top level is not an object.`);
+    process.exit(1);
+  }
+  finalText = upsertPortolan(text);
+} else {
+  finalText =
+    `{\n` +
+    `  "$schema": "https://opencode.ai/config.json",\n` +
+    `  "mcp": { "portolan": ${portolanBlock} }\n` +
+    `}\n`;
+}
+
+mkdirSync(dirname(configPath), { recursive: true });
+// Stage-and-rename: the file we promised to merge into verbatim is replaced
+// atomically, so a crash mid-write truncates the temp file, never the
+// operator's config.
+const configTmp = `${configPath}.tmp-${Date.now()}`;
+writeFileSync(configTmp, finalText);
+renameSync(configTmp, configPath);
+
+// The skill's destination directory name must equal the SKILL.md frontmatter
+// name (opencode's rule), so it is read from the shipped file itself rather
+// than hardcoded.
+function skillName(): string {
+  const text = readFileSync(join(SKILL_SOURCE, "SKILL.md"), "utf8");
+  const match = /^name:\s*(\S+)\s*$/m.exec(text);
+  if (match === null) throw new Error(`no frontmatter name in ${join(SKILL_SOURCE, "SKILL.md")}`);
+  return match[1];
+}
+
+const skillDirName = skillName();
+// The name becomes a directory under the skills root and the rmSync target:
+// a hostile or malformed frontmatter must never steer the wipe outside it.
+// (A lone ".." passes the character class, so it is rejected explicitly.)
+if (!/^[A-Za-z0-9._-]+$/.test(skillDirName) || skillDirName === "..") {
+  console.error(
+    `error: skill frontmatter name ${JSON.stringify(skillDirName)} is not a safe directory name ` +
+      `(expected [A-Za-z0-9._-], not "..") — refusing to install the skill.`,
+  );
+  process.exit(1);
+}
+const skillsRoot = join(configHome(), "opencode", "skills", skillDirName);
+// Idempotent overwrite: a re-install replaces the previous copy wholesale so
+// no stale file from an older package version survives.
+rmSync(skillsRoot, { recursive: true, force: true });
+cpSync(SKILL_SOURCE, skillsRoot, { recursive: true });
+
+// The province's AGENTS.md carries the harbor protocol so every harness
+// that reads agent instructions (opencode first) knows to propose
+// expeditions at session start — no prompt injection needed. The skill is
+// named, not pathed: the harness loads it from its own skills directory, so
+// the block carries no machine path and works identically from a clone or
+// the published package.
+const agentsPath = join(province, "AGENTS.md");
+const BLOCK_BEGIN = "<!-- portolan:harbor:begin -->";
+const BLOCK_END = "<!-- portolan:harbor:end -->";
+const block =
+  `${BLOCK_BEGIN}\n` +
+  `## Portolan province\n\n` +
+  `This target is a charted Portolan province (Chart at \`.portolan/chart/\`, ship's log at \`.portolan/log.jsonl\`).\n\n` +
+  `At session start, before other work: call the \`expeditions.propose\` tool from the \`portolan\` MCP server; ` +
+  `if the queue is non-empty, present the top proposals in ONE chat message (kind, evidence summary, scope) ` +
+  `and ask for a one-phrase decision; record it with \`expeditions.decide\`. ` +
+  `Answer landscape questions from the Chart, citing anchors and trust labels. ` +
+  `The full Cartographer's method: the \`${skillDirName}\` skill (your harness loads it from its skills directory). ` +
+  `Never modify anything outside \`.portolan/\`.\n` +
+  BLOCK_END;
+let agentsText = existsSync(agentsPath) ? readFileSync(agentsPath, "utf8") : "";
+const beginIdx = agentsText.indexOf(BLOCK_BEGIN);
+const endIdx = agentsText.indexOf(BLOCK_END);
+if (beginIdx !== -1 && endIdx !== -1 && endIdx > beginIdx) {
+  agentsText = agentsText.slice(0, beginIdx) + block + agentsText.slice(endIdx + BLOCK_END.length);
+} else {
+  // No block, or orphan/misordered markers: strip any stray markers (and an
+  // orphaned body between a begin and a later-end pairing is already covered
+  // above; here only unmatched leftovers can remain) and append one fresh block.
+  const cleaned = agentsText
+    .replace(/<!-- portolan:harbor:begin -->[\s\S]*?<!-- portolan:harbor:end -->/g, "")
+    .split(BLOCK_BEGIN)
+    .join("")
+    .split(BLOCK_END)
+    .join("");
+  agentsText = cleaned.trim().length > 0 ? `${cleaned.replace(/\s*$/, "\n")}\n${block}\n` : `${block}\n`;
+}
+mkdirSync(province, { recursive: true });
+writeFileSync(agentsPath, agentsText);
+
+console.log(`portolan MCP server registered in ${configPath}`);
+console.log(`  province: ${province}`);
+console.log(`  launch:   ${launchCommand.join(" ")}`);
+console.log(`  skill copied to: ${skillsRoot}`);
+console.log(`  harbor protocol: ${agentsPath}`);

package/adapters/pi/portolan-mcp

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+#
+# pi launch shim for the Portolan MCP server (design.md, decision 6).
+#
+# A shim adds no behavior: it execs the same server a direct launch gives
+# you, with the arguments you pass through. Point any MCP client extension
+# (pi/omp MCP tooling) at this script:
+#
+#   adapters/pi/portolan-mcp --target /path/to/province
+#
+# Adapters must not import tool logic (checked by
+# core/src/server/adapter-boundary.ts) and must not parse tool traffic.
+set -euo pipefail
+
+# Bun lives at ~/.bun/bin by default; find it without copying commands.
+command -v bun >/dev/null 2>&1 || export PATH="$HOME/.bun/bin:$PATH"
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+exec bun "$ROOT/core/src/server/main.ts" "$@"

package/adapters/scheduling/night-watch.cron

@@ -0,0 +1,23 @@
+# Portolan night watch — drop-in crontab lines.
+#
+# Portolan ships no daemon: these lines are the external scheduler. Adjust
+# PROVINCE and PORTOLAN to this machine, then install with:
+#
+#   crontab -e   # paste the lines below
+#
+# Both runs are deterministic over an unchanged province — a quiet run
+# prints nothing extra to post. See adapters/README.md ("The night watch")
+# for the policy bound (harbor.auto_repair_max_vessels) and launcher
+# contract.
+
+PROVINCE=/path/to/province
+PORTOLAN=/path/to/portolan-checkout
+
+# Report-only nightly watch: the morning list, nothing auto-launched.
+15 2 * * *  cd $PORTOLAN && bun core/src/harbor/cli.ts watch --target $PROVINCE --format chat
+
+# Acting variant (auto-repair within the configured bound through the
+# opencode launcher) — replace the line above with:
+#15 2 * * *  cd $PORTOLAN && bun core/src/harbor/cli.ts watch --target $PROVINCE \
+#            --launcher adapters/opencode/expedition-launcher \
+#            --launcher-timeout 45m --format chat

package/core/schema/chart.schema.json

@@ -0,0 +1,154 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://portolan.dev/core/chart.schema.json",
+  "title": "Portolan Chart entry",
+  "description": "One entry of the Chart (the Padrón): vessel, fairway, port of entry, beacon, light, or danger. Every entry carries at least one anchor and exactly one trust label from the closed vocabulary. This schema is the published contract for Cartographer agents; core/src/types.ts mirrors it.",
+  "$ref": "#/$defs/chartEntry",
+  "$defs": {
+    "trustLabel": {
+      "description": "Closed trust vocabulary (chart notation): measured, charted, reported, doubtful, unsurveyed.",
+      "enum": ["measured", "charted", "reported", "doubtful", "unsurveyed"]
+    },
+    "fairwayRelation": {
+      "description": "Optional closed relation vocabulary on a fairway: build, runtime, config. A fairway without a relation stays valid and reads as untyped.",
+      "enum": ["build", "runtime", "config"]
+    },
+    "entryId": { "type": "string", "minLength": 1 },
+    "anchor": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "path"],
+          "properties": {
+            "type": { "const": "file" },
+            "path": { "type": "string", "minLength": 1 },
+            "line": { "type": "integer", "minimum": 1 }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "path", "key"],
+          "properties": {
+            "type": { "const": "manifest" },
+            "path": { "type": "string", "minLength": 1 },
+            "key": { "type": "string", "minLength": 1 }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "id"],
+          "properties": {
+            "type": { "const": "receipt" },
+            "id": { "type": "string", "minLength": 1 }
+          }
+        }
+      ]
+    },
+    "anchors": {
+      "description": "An entry without at least one anchor does not ship.",
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/anchor" }
+    },
+    "vessel": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "id", "name", "paths", "anchors", "trust"],
+      "properties": {
+        "kind": { "const": "vessel" },
+        "id": { "$ref": "#/$defs/entryId" },
+        "name": { "type": "string", "minLength": 1 },
+        "behavior": { "type": "string" },
+        "paths": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "note": { "type": "string" },
+        "anchors": { "$ref": "#/$defs/anchors" },
+        "trust": { "$ref": "#/$defs/trustLabel" }
+      }
+    },
+    "fairway": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "id", "from", "to", "anchors", "trust"],
+      "properties": {
+        "kind": { "const": "fairway" },
+        "id": { "$ref": "#/$defs/entryId" },
+        "from": { "$ref": "#/$defs/entryId" },
+        "to": { "$ref": "#/$defs/entryId" },
+        "relation": { "$ref": "#/$defs/fairwayRelation" },
+        "note": { "type": "string" },
+        "anchors": { "$ref": "#/$defs/anchors" },
+        "trust": { "$ref": "#/$defs/trustLabel" }
+      }
+    },
+    "portOfEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "id", "vessel", "protocol", "anchors", "trust"],
+      "properties": {
+        "kind": { "const": "portOfEntry" },
+        "id": { "$ref": "#/$defs/entryId" },
+        "vessel": { "$ref": "#/$defs/entryId" },
+        "protocol": { "type": "string", "minLength": 1 },
+        "note": { "type": "string" },
+        "anchors": { "$ref": "#/$defs/anchors" },
+        "trust": { "$ref": "#/$defs/trustLabel" }
+      }
+    },
+    "beacon": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "id", "vessel", "surface", "key", "anchors", "trust"],
+      "properties": {
+        "kind": { "const": "beacon" },
+        "id": { "$ref": "#/$defs/entryId" },
+        "vessel": { "$ref": "#/$defs/entryId" },
+        "surface": { "enum": ["env", "flag", "port"] },
+        "key": { "type": "string", "minLength": 1 },
+        "note": { "type": "string" },
+        "anchors": { "$ref": "#/$defs/anchors" },
+        "trust": { "$ref": "#/$defs/trustLabel" }
+      }
+    },
+    "light": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "id", "vessel", "name", "anchors", "trust"],
+      "properties": {
+        "kind": { "const": "light" },
+        "id": { "$ref": "#/$defs/entryId" },
+        "vessel": { "$ref": "#/$defs/entryId" },
+        "name": { "type": "string", "minLength": 1 },
+        "note": { "type": "string" },
+        "anchors": { "$ref": "#/$defs/anchors" },
+        "trust": { "$ref": "#/$defs/trustLabel" }
+      }
+    },
+    "danger": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "id", "vessel", "category", "note", "anchors", "trust"],
+      "properties": {
+        "kind": { "const": "danger" },
+        "id": { "$ref": "#/$defs/entryId" },
+        "vessel": { "$ref": "#/$defs/entryId" },
+        "category": { "enum": ["rock", "shallow", "wreck"] },
+        "note": { "type": "string", "minLength": 1 },
+        "anchors": { "$ref": "#/$defs/anchors" },
+        "trust": { "$ref": "#/$defs/trustLabel" }
+      }
+    },
+    "chartEntry": {
+      "oneOf": [
+        { "$ref": "#/$defs/vessel" },
+        { "$ref": "#/$defs/fairway" },
+        { "$ref": "#/$defs/portOfEntry" },
+        { "$ref": "#/$defs/beacon" },
+        { "$ref": "#/$defs/light" },
+        { "$ref": "#/$defs/danger" }
+      ]
+    }
+  }
+}

package/core/src/bin/portolan.ts

@@ -0,0 +1,84 @@
+#!/usr/bin/env bun
+/**
+ * The `portolan` dispatcher — the single bin the published package exposes.
+ * It routes to the existing entry points; it implements nothing itself:
+ *
+ *   portolan serve --target <province root>      → server/main.ts (MCP over stdio)
+ *   portolan chartroom <render|review> …        → chartroom/cli.ts
+ *   portolan harbor <propose|watch|run> …       → harbor/cli.ts
+ *
+ * `serve` runs in-process (same parse, same server wiring as main.ts);
+ * the CLIs are spawned with inherited stdio so their behavior — output,
+ * exit codes — is indistinguishable from running them directly.
+ */
+import { resolve } from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const SUBCOMMANDS = ["serve", "chartroom", "harbor"] as const;
+
+const usage = `usage: portolan <command> [args]
+
+commands:
+  serve      run the Portolan MCP server (stdio)
+  chartroom  Chart Room CLI (render | review)
+  harbor     harbor CLI (propose | watch | run)`;
+
+function failUsage(): never {
+  console.error(`${usage}\n\nvalid commands: ${SUBCOMMANDS.join(", ")}`);
+  process.exit(1);
+}
+
+/** Path to a sibling source file of this dispatcher. */
+function srcPath(relative: string): string {
+  return fileURLToPath(new URL(relative, import.meta.url));
+}
+
+async function serve(rest: readonly string[]): Promise<void> {
+  // Same parse and wiring as core/src/server/main.ts — behavior
+  // indistinguishable from launching that file directly.
+  const { parseArgs } = await import("node:util");
+  const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
+  const { createPortolanServer } = await import("../server/server");
+
+  const { values } = parseArgs({
+    // Same parse as main.ts, over the args after the `serve` subcommand.
+    args: rest,
+    allowPositionals: false,
+    options: {
+      target: { type: "string", default: process.cwd() },
+    },
+  });
+  const targetRoot = resolve(values.target as string);
+  const server = createPortolanServer({ targetRoot });
+  await server.connect(new StdioServerTransport());
+}
+
+/** Run one of the existing CLI scripts with the remaining args, verbatim. */
+function runCli(script: string, args: string[]): never {
+  const child = spawn(process.execPath, [script, ...args], { stdio: "inherit" });
+  child.on("exit", (code, signal) => {
+    if (signal !== null) process.kill(process.pid, signal);
+    else process.exit(code ?? 1);
+  });
+  // Never resolves in practice; keeps the dispatcher alive for the child.
+  return new Promise<never>(() => {}) as never;
+}
+
+async function dispatch(argv: readonly string[]): Promise<void> {
+  const [command, ...rest] = argv;
+  switch (command) {
+    case "serve":
+      return serve(rest);
+    case "chartroom":
+      return runCli(srcPath("../chartroom/cli.ts"), rest);
+    case "harbor":
+      return runCli(srcPath("../harbor/cli.ts"), rest);
+    default:
+      failUsage();
+  }
+}
+
+if (import.meta.main) {
+  await dispatch(Bun.argv.slice(2));
+}