@fcon-tech/portolan 0.4.5

package/core/src/harbor/settings.ts

@@ -0,0 +1,108 @@
+/**
+ * The settings file: `<target>/.portolan/settings.json`, one recognized
+ * namespace (`harbor`) with two recognized keys — `harbor.schedule` and
+ * `harbor.auto_repair_max_vessels` — unset by default (design.md, decision
+ * 5). The schedule is documentation for external wiring — Portolan
+ * interprets nothing from it and runs nothing on its own; the headless
+ * propose CLI is the scheduler's entry. The auto-repair bound is the night
+ * watch's whole policy (night-watch design.md, decision 1): absent or zero
+ * means report-only, and a malformed value fails LOUDLY — a typo'd bound
+ * must never degrade silently into "launch everything" or "launch nothing".
+ * Unknown keys are tolerated with a warning so a newer or hand-edited
+ * settings file never breaks an older Portolan; a file that is not a JSON
+ * object fails loudly.
+ * openspec/changes/harbor-master + openspec/changes/night-watch (harbor
+ * capability: scheduling is an explicit setting, off by default / night
+ * policy bound)
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { SettingsError } from "./errors";
+
+export const SETTINGS_FILE = "settings.json";
+
+/** The recognized `harbor` namespace. */
+export interface HarborSettings {
+  /** A cron-ish descriptor, documentation for external scheduling; absent by default. */
+  schedule?: string;
+  /**
+   * The night watch's auto-repair bound: the largest number of affected
+   * vessels a repair proposal may carry and still be auto-executed.
+   * Absent (and zero) means report-only; a non-negative integer or the
+   * settings file fails loudly.
+   */
+  autoRepairMaxVessels?: number;
+}
+
+/** What reading the settings file produced, plus its warnings. */
+export interface SettingsResult {
+  harbor: HarborSettings;
+  warnings: string[];
+}
+
+/** Where the settings file lives. */
+export function settingsFile(targetRoot: string): string {
+  return join(targetRoot, ".portolan", SETTINGS_FILE);
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Read the settings file. Absent file: `{ harbor: {}, warnings: [] }` — no
+ * schedule, nothing configured, nothing runs on its own. Unknown keys (at
+ * either level) and ill-typed known keys are tolerated with a warning and
+ * ignored — except `harbor.auto_repair_max_vessels`, which must be a
+ * non-negative integer when present and fails loudly otherwise (the bound is
+ * the night watch's safety story; ambiguity about it is never tolerable).
+ * Malformed JSON or a non-object root is a loud error.
+ */
+export function readSettings(targetRoot: string): SettingsResult {
+  const file = settingsFile(targetRoot);
+  if (!existsSync(file)) return { harbor: {}, warnings: [] };
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(file, "utf8"));
+  } catch (err) {
+    throw new SettingsError(`cannot parse ${file}: ${(err as Error).message}`);
+  }
+  if (!isPlainObject(parsed)) {
+    throw new SettingsError(`${file} is not a JSON object`);
+  }
+
+  const warnings: string[] = [];
+  const harbor: HarborSettings = {};
+  for (const [key, value] of Object.entries(parsed)) {
+    if (key !== "harbor") {
+      warnings.push(`settings: unknown key "${key}" ignored (known: harbor)`);
+      continue;
+    }
+    if (!isPlainObject(value)) {
+      warnings.push(`settings: "harbor" must be an object; ignored`);
+      continue;
+    }
+    for (const [innerKey, innerValue] of Object.entries(value)) {
+      if (innerKey === "schedule") {
+        if (typeof innerValue !== "string" || innerValue.length === 0) {
+          warnings.push(`settings: harbor.schedule must be a non-empty string; ignored`);
+        } else {
+          harbor.schedule = innerValue;
+        }
+      } else if (innerKey === "auto_repair_max_vessels") {
+        if (typeof innerValue !== "number" || !Number.isInteger(innerValue) || innerValue < 0) {
+          throw new SettingsError(
+            `harbor.auto_repair_max_vessels must be a non-negative integer, got ${JSON.stringify(innerValue)}`,
+          );
+        }
+        harbor.autoRepairMaxVessels = innerValue;
+      } else {
+        warnings.push(
+          `settings: unknown key "harbor.${innerKey}" ignored (known: harbor.schedule, harbor.auto_repair_max_vessels)`,
+        );
+      }
+    }
+  }
+  return { harbor, warnings };
+}

package/core/src/harbor/snapshot.ts

@@ -0,0 +1,187 @@
+/**
+ * The landscape snapshot: what the province looked like at the last survey,
+ * stored under `<target>/.portolan/harbor/snapshot.json` as
+ * `{ indexHash, landscape[] }` (design.md, decision 2).
+ *
+ * Refresh rule — the chart index hash. When the current index hash differs
+ * from the stored one, a survey stood against the current landscape and the
+ * snapshot refreshes; when it matches, the landscape is compared against the
+ * snapshot and entries absent from it yield new-land proposals. This needs
+ * no hooks into the chart store. A first propose over a chart with no
+ * snapshot establishes the baseline (and proposes no new-land): there is no
+ * earlier survey to differ from.
+ *
+ * The landscape is a bounded walk collecting two entry kinds: repository
+ * directories (a child `.git`, file or directory — worktrees and submodules
+ * included) and manifest files (the five kinds the manifests tool parses).
+ * The walk skips `node_modules`, `.git`, and `.portolan` exactly like the
+ * probe tools' walks, and never records the province root itself.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { MANIFEST_KINDS } from "../tools/manifests";
+import { readChart, sortEntries, writeFilesAtomically } from "../chart-io";
+import { HarborError } from "./errors";
+
+export const HARBOR_DIRNAME = "harbor";
+export const SNAPSHOT_FILE = "snapshot.json";
+
+/** Directories the landscape walk never descends into (probe-tool convention). */
+const SKIPPED_DIRS = new Set(["node_modules", ".git", ".portolan"]);
+
+/** Bound on walk depth: deep trees terminate; six levels cover monorepo layouts. */
+const MAX_DEPTH = 6;
+
+/** One landscape fact: a repository directory or a manifest file, by relative path. */
+export interface LandscapeEntry {
+  kind: "repo" | "manifest";
+  /** Relative to the province root; `apps/api`, `vendor/lib/go.mod`, ... */
+  path: string;
+}
+
+/** The stored snapshot: the landscape together with the chart index hash it was taken against. */
+export interface LandscapeSnapshot {
+  indexHash: string;
+  landscape: LandscapeEntry[];
+}
+
+/** Where the Harbor Master's files live for a given target root. */
+export function harborDir(targetRoot: string): string {
+  return join(targetRoot, ".portolan", HARBOR_DIRNAME);
+}
+
+/** Where the landscape snapshot lives. */
+export function snapshotFile(targetRoot: string): string {
+  return join(harborDir(targetRoot), SNAPSHOT_FILE);
+}
+
+/**
+ * sha256 over the chart's canonical entry content — the snapshot's refresh
+ * key. Store-owned `stale` flags are stripped before hashing: a staleness
+ * refresh marks pending correction but is not "a survey stood", so it must
+ * not refresh the snapshot (design.md, decision 2's parenthetical). A real
+ * survey write always changes content — vessel signatures are re-stamped
+ * against the repaired sources — and a write that changes nothing is, by
+ * the design's accepted-risk note, not a new survey.
+ */
+export function chartIndexHash(targetRoot: string): string {
+  const content = readChart(targetRoot).map(({ stale: _stale, ...entry }) => entry);
+  const canonical = sortEntries(content)
+    .map((entry) => JSON.stringify(entry))
+    .join("\n");
+  return createHash("sha256").update(canonical).digest("hex");
+}
+
+function entryKey(entry: LandscapeEntry): string {
+  return `${entry.kind}:${entry.path}`;
+}
+
+/** Stable landscape order: kind, then path. */
+export function sortLandscape(landscape: LandscapeEntry[]): LandscapeEntry[] {
+  return [...landscape].sort((a, b) =>
+    a.kind === b.kind ? (a.path < b.path ? -1 : a.path > b.path ? 1 : 0) : a.kind < b.kind ? -1 : 1,
+  );
+}
+
+/**
+ * Walk the province and list the landscape: repository directories (a
+ * `.git` child) and manifest files, skipping `node_modules`/`.git`/
+ * `.portolan`, bounded by depth. Read-only toward everything it walks.
+ */
+export function scanLandscape(targetRoot: string): LandscapeEntry[] {
+  const found: LandscapeEntry[] = [];
+  const seen = new Set<string>();
+  const push = (entry: LandscapeEntry): void => {
+    const key = entryKey(entry);
+    if (!seen.has(key)) {
+      seen.add(key);
+      found.push(entry);
+    }
+  };
+
+  const visit = (rel: string, depth: number): void => {
+    if (depth > MAX_DEPTH) return;
+    let children;
+    try {
+      children = readdirSync(join(targetRoot, rel), { withFileTypes: true });
+    } catch {
+      return; // an unreadable directory contributes nothing
+    }
+    const sorted = [...children].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    // A `.git` child marks a repository — noticed, never descended into.
+    if (rel !== "" && sorted.some((de) => de.name === ".git")) {
+      push({ kind: "repo", path: rel });
+    }
+    for (const de of sorted) {
+      if (de.isDirectory()) {
+        if (SKIPPED_DIRS.has(de.name)) continue;
+        visit(rel === "" ? de.name : `${rel}/${de.name}`, depth + 1);
+      } else if (de.isFile() && (MANIFEST_KINDS as readonly string[]).includes(de.name)) {
+        push({ kind: "manifest", path: rel === "" ? de.name : `${rel}/${de.name}` });
+      }
+    }
+  };
+  visit("", 0);
+  return sortLandscape(found);
+}
+
+/**
+ * The anchor a new-land proposal cites for a landscape entry: the manifest
+ * file itself, or the repository's `.git` marker (a regular file in both
+ * cases, so `sound.anchor` can confirm it: `.git/HEAD` for a plain
+ * repository, the gitdir pointer file for a worktree/submodule).
+ */
+export function landscapeAnchor(targetRoot: string, entry: LandscapeEntry): { type: "file"; path: string } {
+  if (entry.kind === "manifest") return { type: "file", path: entry.path };
+  const git = join(targetRoot, entry.path, ".git");
+  try {
+    if (statSync(git).isFile()) return { type: "file", path: `${entry.path}/.git` };
+  } catch {
+    // fall through to the plain-repository form
+  }
+  return { type: "file", path: `${entry.path}/.git/HEAD` };
+}
+
+/** Read the stored snapshot; null when none exists yet. */
+export function readSnapshot(targetRoot: string): LandscapeSnapshot | null {
+  const file = snapshotFile(targetRoot);
+  if (!existsSync(file)) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(file, "utf8"));
+  } catch (err) {
+    throw new HarborError(`snapshot: corrupt landscape snapshot ${file}: ${(err as Error).message}`);
+  }
+  const snap = parsed as LandscapeSnapshot;
+  if (
+    typeof snap?.indexHash !== "string" ||
+    !Array.isArray(snap.landscape) ||
+    snap.landscape.some(
+      (e) =>
+        (e?.kind !== "repo" && e?.kind !== "manifest") || typeof e?.path !== "string" || e.path.length === 0,
+    )
+  ) {
+    throw new HarborError(
+      `snapshot: corrupt landscape snapshot ${file}: expected { indexHash, landscape[] } with repo/manifest entries`,
+    );
+  }
+  return snap;
+}
+
+/** Persist the snapshot (plain pretty JSON, diff-friendly). */
+export function writeSnapshot(targetRoot: string, snapshot: LandscapeSnapshot): void {
+  // Same stage-temp-then-rename discipline as the chart itself: a torn
+  // write on the unattended cron path would brick every later propose and
+  // watch with a "corrupt landscape snapshot" until a human deletes the file.
+  mkdirSync(harborDir(targetRoot), { recursive: true });
+  writeFilesAtomically(
+    harborDir(targetRoot),
+    new Map([
+      [
+        SNAPSHOT_FILE,
+        `${JSON.stringify({ indexHash: snapshot.indexHash, landscape: sortLandscape(snapshot.landscape) }, null, 2)}\n`,
+      ],
+    ]),
+  );
+}

package/core/src/harbor/watch.ts

@@ -0,0 +1,103 @@
+/**
+ * The night watch (openspec/changes/night-watch): queue → night policy →
+ * external launcher → harbor history → chat report. Designed for external
+ * schedulers (cron/CI); Portolan still ships no daemon — nothing here runs
+ * on a timer, only when invoked.
+ *
+ * Semantics pinned by design.md:
+ * - decision 1: the whole policy is `harbor.auto_repair_max_vessels`
+ *   (absent/0 = report-only); repairs within the bound launch, new-land and
+ *   gap never do.
+ * - decision 2: the launcher is external and swappable (argv from
+ *   `--launcher`, the `{ target, proposal }` brief as JSON on stdin, capped
+ *   by a timeout); with no launcher configured the watch is report-only
+ *   even with a bound set — the core names no harness.
+ * - decision 3: accept-then-append-failure. The auto-accept (`by:
+ *   night-watch`) is written before launch; a failed launch appends a
+ *   `launch-failed` outcome, which is the latest word on the fingerprint,
+ *   so a failed proposal is effectively not-accepted and stays queued (the
+ *   queue filters on `declined` only).
+ *
+ * Determinism: the report carries no timestamps — two watch runs over an
+ * unchanged province (same launcher behavior) emit byte-identical reports.
+ */
+import { computeProposals, type Proposal } from "./proposals";
+import { readSettings } from "./settings";
+import { nightPolicy } from "./night-policy";
+import { briefFor, launchExpedition, DEFAULT_LAUNCHER_TIMEOUT_MS } from "./launcher";
+import { appendDecision, appendLaunchFailure, NIGHT_WATCH } from "./history";
+
+/** What the watch was told at invocation. */
+export interface WatchOptions {
+  /** The external launcher command (argv template); absent = report-only. */
+  launcher?: string;
+  /** Per-launch timeout in milliseconds; default 30m (DEFAULT_LAUNCHER_TIMEOUT_MS). */
+  launcherTimeoutMs?: number;
+}
+
+/** One launch the watch attempted, with its outcome. */
+export interface WatchAction {
+  proposal: Proposal;
+  outcome: "completed" | "launch-failed";
+  /** Deterministic failure reason; present iff the outcome is launch-failed. */
+  reason?: string;
+}
+
+/** The watch report's data: what ran, what stayed pending, and the policy that decided. */
+export interface WatchReport {
+  /** The effective `harbor.auto_repair_max_vessels` (absent = 0). */
+  bound: number;
+  /** True when nothing could launch at all (no launcher configured, or bound 0). */
+  reportOnly: boolean;
+  /** The launcher command the run used, when one was configured. */
+  launcherCommand?: string;
+  /** Every launch attempted this run, in queue order, with outcomes. */
+  ran: WatchAction[];
+  /** Proposals left for the Governor, in queue order, with their evidence. */
+  pending: Proposal[];
+}
+
+/**
+ * Run the night watch against a province: compute the queue, apply the
+ * night policy, launch what qualifies through the external launcher
+ * (recording each auto-accept `by night-watch` first, appending
+ * `launch-failed` on failure), and return the report data. Never launches
+ * anything and writes no history when report-only.
+ */
+export async function runWatch(targetRoot: string, options: WatchOptions = {}): Promise<WatchReport> {
+  const { harbor } = readSettings(targetRoot);
+  const bound = harbor.autoRepairMaxVessels ?? 0;
+
+  const { proposals } = computeProposals(targetRoot);
+  const { launch, pending } = nightPolicy(proposals, bound);
+
+  // Report-only (no launcher, or bound 0): nothing can launch, so what the
+  // policy would have launched folds back into pending — the report always
+  // shows the Governor every outstanding proposal.
+  const reportOnly = options.launcher === undefined || bound <= 0;
+  const ran: WatchAction[] = [];
+  if (!reportOnly) {
+    for (const proposal of launch) {
+      appendDecision(targetRoot, proposal.fingerprint, "accepted", { by: NIGHT_WATCH });
+      const result = await launchExpedition({
+        launcher: options.launcher as string,
+        brief: briefFor(targetRoot, proposal),
+        timeoutMs: options.launcherTimeoutMs ?? DEFAULT_LAUNCHER_TIMEOUT_MS,
+      });
+      if (result.ok) {
+        ran.push({ proposal, outcome: "completed" });
+      } else {
+        appendLaunchFailure(targetRoot, proposal.fingerprint, result.reason as string);
+        ran.push({ proposal, outcome: "launch-failed", reason: result.reason });
+      }
+    }
+  }
+
+  return {
+    bound,
+    reportOnly,
+    ...(options.launcher !== undefined ? { launcherCommand: options.launcher } : {}),
+    ran,
+    pending: reportOnly ? proposals : pending,
+  };
+}

package/core/src/index.ts

@@ -0,0 +1,28 @@
+/**
+ * @portolan/core — public surface: the chart ontology, validation, the
+ * chart store, staleness, Notices to Mariners, and the Harbor Master's
+ * expedition-proposal engine (including the night watch and its external
+ * launcher contract). Everything a Cartographer harness needs; nothing
+ * else.
+ */
+export * from "./types";
+export * from "./validate";
+export * from "./chart-store";
+export * from "./staleness";
+export * from "./notices";
+export * from "./tools/sweep";
+export * from "./tools/symbols";
+export * from "./tools/manifests";
+export * from "./tools/log";
+export * from "./tools/sound";
+export * from "./tools/neighborhood";
+export * from "./harbor/errors";
+export * from "./harbor/fingerprint";
+export * from "./harbor/snapshot";
+export * from "./harbor/history";
+export * from "./harbor/settings";
+export * from "./harbor/proposals";
+export * from "./harbor/chat-format";
+export * from "./harbor/night-policy";
+export * from "./harbor/launcher";
+export * from "./harbor/watch";

package/core/src/notices.ts

@@ -0,0 +1,117 @@
+/**
+ * Notices to Mariners: the plain-text change report an expedition leaves
+ * behind. Derived by diffing the previous index against the new one —
+ * added / corrected / marked stale / retired — each notice carrying the
+ * entry's anchors. Deterministic output, suitable for git diff review.
+ */
+import { formatAnchor, type IndexedEntry, type Notice, type NoticeAction } from "./types";
+
+/** Fields that carry chart state, not surveyed content. */
+const META_FIELDS = new Set(["stale", "signature"]);
+
+function contentChangedFields(before: IndexedEntry, after: IndexedEntry): string[] {
+  const keys = new Set([...Object.keys(before), ...Object.keys(after)]);
+  const changed: string[] = [];
+  for (const key of keys) {
+    if (META_FIELDS.has(key)) continue;
+    if (JSON.stringify(before[key as keyof IndexedEntry]) !== JSON.stringify(after[key as keyof IndexedEntry])) {
+      changed.push(key);
+    }
+  }
+  return changed.sort();
+}
+
+/**
+ * Diff two chart states into notices.
+ *
+ * - present after only → added
+ * - present before only → retired
+ * - fresh → stale → marked stale (pending correction)
+ * - content changed, or stale → fresh (a repair) → corrected
+ */
+export function diffNotices(before: IndexedEntry[], after: IndexedEntry[]): Notice[] {
+  const beforeByKey = new Map(before.map((e) => [`${e.kind}/${e.id}`, e]));
+  const afterByKey = new Map(after.map((e) => [`${e.kind}/${e.id}`, e]));
+  const notices: Notice[] = [];
+
+  for (const [key, entry] of afterByKey) {
+    const prior = beforeByKey.get(key);
+    if (!prior) {
+      notices.push({ action: "added", kind: entry.kind, id: entry.id, anchors: entry.anchors });
+      continue;
+    }
+    const changedFields = contentChangedFields(prior, entry);
+    const staleCleared = prior.stale && !entry.stale;
+    const staleSet = !prior.stale && entry.stale;
+    if (staleSet) {
+      notices.push({
+        action: "markedStale",
+        kind: entry.kind,
+        id: entry.id,
+        note: "sources changed since the last survey",
+        anchors: entry.anchors,
+      });
+    } else if (changedFields.length > 0 || staleCleared) {
+      const parts: string[] = [];
+      if (changedFields.length > 0) parts.push(`changed: ${changedFields.join(", ")}`);
+      if (staleCleared) parts.push("repaired (was pending correction)");
+      notices.push({
+        action: "corrected",
+        kind: entry.kind,
+        id: entry.id,
+        note: parts.join("; "),
+        anchors: entry.anchors,
+      });
+    }
+  }
+
+  for (const [key, entry] of beforeByKey) {
+    if (!afterByKey.has(key)) {
+      notices.push({ action: "retired", kind: entry.kind, id: entry.id, anchors: entry.anchors });
+    }
+  }
+
+  return sortNotices(notices);
+}
+
+const ACTION_ORDER: NoticeAction[] = ["added", "corrected", "markedStale", "retired"];
+
+function sortNotices(notices: Notice[]): Notice[] {
+  return [...notices].sort((a, b) => {
+    const rank = ACTION_ORDER.indexOf(a.action) - ACTION_ORDER.indexOf(b.action);
+    if (rank !== 0) return rank;
+    const ka = `${a.kind}/${a.id}`;
+    const kb = `${b.kind}/${b.id}`;
+    return ka < kb ? -1 : ka > kb ? 1 : 0;
+  });
+}
+
+const LABELS: Record<NoticeAction, string> = {
+  added: "ADDED",
+  corrected: "CORRECTED",
+  markedStale: "MARKED STALE",
+  retired: "RETIRED",
+};
+
+/**
+ * Render notices as plain text:
+ *
+ *   NOTICES TO MARINERS
+ *
+ *   MARKED STALE  vessel/web — sources changed since the last survey
+ *                 anchor: services/web/main.ts:1
+ */
+export function renderNotices(notices: Notice[]): string {
+  if (notices.length === 0) return "";
+  const pad = " ".repeat(14);
+  const lines: string[] = ["NOTICES TO MARINERS", ""];
+  for (const notice of notices) {
+    const label = LABELS[notice.action].padEnd(14);
+    const head = `${notice.kind}/${notice.id}${notice.note ? ` — ${notice.note}` : ""}`;
+    lines.push(`${label}${head}`);
+    for (const anchor of notice.anchors) {
+      lines.push(`${pad}anchor: ${formatAnchor(anchor)}`);
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}

package/core/src/perimeter.ts

@@ -0,0 +1,44 @@
+/**
+ * The target perimeter: the one containment rule every province read obeys.
+ * A cited path counts as inside only when it resolves both lexically and
+ * through symlinks inside the target root — no reader crosses the perimeter
+ * whatever the citation claims. A wholly fabricated path has no existing
+ * parent, so containment is checked against the nearest existing ancestor:
+ * nothing on such a path can be read, and the honest outcome is "escapes",
+ * not a crash.
+ * specs/permissions/spec.md; security hardening cfa1869, 23d012b.
+ */
+import { realpathSync } from "node:fs";
+import { dirname, resolve, sep } from "node:path";
+
+/**
+ * Resolve a cited path inside the target root; undefined when it escapes
+ * (a `..` segment, an in-target symlink pointing outside, or an absolute
+ * path elsewhere on the machine).
+ */
+export function resolveInsideTarget(targetRoot: string, rel: string): string | undefined {
+  const root = resolve(targetRoot);
+  const abs = resolve(root, rel);
+  if (abs !== root && !abs.startsWith(root + sep)) return undefined;
+  // A symlink inside the target may point outside it — including the cited
+  // file itself: compare real paths, so an anchor can never read through an
+  // in-target link past the perimeter.
+  const realRoot = realpathSync(root);
+  let probe = abs;
+  let realPath: string;
+  for (;;) {
+    try {
+      realPath = realpathSync(probe);
+      break;
+    } catch {
+      const parent = dirname(probe);
+      if (parent === probe) {
+        realPath = probe; // walked to the filesystem root unrealized: escape
+        break;
+      }
+      probe = parent;
+    }
+  }
+  if (realPath !== realRoot && !realPath.startsWith(realRoot + sep)) return undefined;
+  return abs;
+}

package/core/src/server/adapter-boundary.ts

@@ -0,0 +1,66 @@
+/**
+ * The adapter-boundary check (tasks.md 4.3): a static scan proving
+ * `adapters/` imports no tool logic. Adapters are launch configuration
+ * (design.md, decision 5) — an adapter that imports a tool module would be
+ * a code path the harness-parity scenario cannot test by construction.
+ *
+ * The scan is deliberately blunt: it flags any module import (static,
+ * dynamic, or require) of the core package or of anything under core/src.
+ * Launching the server (exec lines in shims, the command array in the
+ * opencode config) is exactly what adapters are FOR and is never flagged.
+ * Markdown is skipped — prose shows examples, code does not import.
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+
+/** One boundary violation: where it is, and the offending line. */
+export interface BoundaryViolation {
+  file: string;
+  line: number;
+  text: string;
+}
+
+/** Import/requires that reach tool or core logic from adapter code. */
+const TOOL_IMPORT_PATTERNS: RegExp[] = [
+  /from\s+["']@portolan\/core[^"']*["']/, // static import of the package
+  /import\s*\(\s*["']@portolan\/core[^"']*["']\s*\)/, // dynamic import
+  /require\s*\(\s*["']@portolan\/core[^"']*["']\s*\)/, // CJS require
+  /from\s+["'][^"']*core\/src\//, // relative path into the core tree
+  /import\s*\(\s*["'][^"']*core\/src\//,
+  /require\s*\(\s*["'][^"']*core\/src\//,
+];
+
+const SCANNED_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".mjs", ".cjs", ".sh", ""]);
+
+/**
+ * Scan an adapter tree for tool-logic imports. Returns every violation;
+ * an empty list means the boundary holds.
+ */
+export function scanAdapterTree(root: string): BoundaryViolation[] {
+  const violations: BoundaryViolation[] = [];
+  const visit = (dir: string): void => {
+    for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) =>
+      a.name < b.name ? -1 : a.name > b.name ? 1 : 0,
+    )) {
+      const abs = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        visit(abs);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (entry.name.endsWith(".md") || entry.name.endsWith(".json") || entry.name.endsWith(".jsonc")) {
+        continue; // prose and config; launch lines live here on purpose
+      }
+      const ext = entry.name.includes(".") ? entry.name.slice(entry.name.lastIndexOf(".")) : "";
+      if (!SCANNED_EXTENSIONS.has(ext)) continue;
+      const lines = readFileSync(abs, "utf8").split("\n");
+      lines.forEach((text, index) => {
+        if (TOOL_IMPORT_PATTERNS.some((pattern) => pattern.test(text))) {
+          violations.push({ file: relative(root, abs), line: index + 1, text: text.trim() });
+        }
+      });
+    }
+  };
+  visit(root);
+  return violations;
+}

package/core/src/server/main.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env bun
+/**
+ * The Portolan MCP server entry point. Launch with:
+ *
+ *   bun core/src/server/main.ts --target <province root>
+ *
+ * `--target` defaults to the working directory and is resolved once here;
+ * every tool call is scoped to that root, and no call can redirect it —
+ * changing provinces means launching a new server (design.md, decision 2).
+ * The server speaks MCP over stdio and nothing else: no network, no daemon.
+ * specs/harness/spec.md
+ */
+import { parseArgs } from "node:util";
+import { resolve } from "node:path";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createPortolanServer } from "./server";
+
+const { values } = parseArgs({
+  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());