@repo-os/repoos 0.5.49 → 0.5.51

package/README.md

@@ -296,6 +296,23 @@ roles alongside the engineer agent. Freeform task creation sends a description
 through the PM agent for structured drafting. All agent capability is local —
 no API tokens leave your machine unless you configure them.
 
+## RepoOS Hub for macOS
+
+A native Mac app (macOS 13+; sessions persist across relaunches on macOS 14+)
+that keeps tabs on all your RepoOS servers from
+one window: pin tasks across servers, see live attention counts in the sidebar
+and Dock badge, and jump between servers and tasks with Cmd-K. Each server
+loads in its own isolated WebKit session — sessions are never shared between
+servers, and server pages get no bridge into your files or Keychain. Local
+loopback servers need zero setup; remote servers use short-lived, revocable
+capability tokens (created over HTTPS on the server, stored in the Keychain)
+for their attention and search endpoints.
+
+The Hub's DMG is published on
+[GitHub Releases](https://github.com/repo-os/repoos/releases) with each tag
+release (the first Hub DMG is pending). Setup, pairing, and limitation details
+are in the [Hub guide](https://github.com/repo-os/repoos/blob/main/user-docs/macos-hub.md).
+
 ## Roadmap
 
 - **Stage 1 — parser + index + CLI** ✅

package/dist/.build-info.json

@@ -1,4 +1,4 @@
 {
-  "hash": "f5bc7080896e6462e45fb88aeecb10c9c2f675395207b58c11bc29b2b5524aa7",
-  "version": "0.5.49"
+  "hash": "9978dc66ddd3de60d301a374cf6cf80f0e7f6fa67545d1dcab764e930f29b35a",
+  "version": "0.5.51"
 }

package/dist/.build-stamp.json

@@ -1,3 +1,3 @@
 {
-  "generatedAt": "2026-09-20T04:12:23.987Z"
+  "generatedAt": "2026-09-23T02:28:26.540Z"
 }

package/dist/cli/index.js

@@ -15,6 +15,7 @@ import { cmdUpgrade } from "../commands/upgrade.js";
 import { cmdUninstall } from "../commands/uninstall.js";
 import { cmdStatus } from "../commands/status.js";
 import { cmdDoctor } from "../commands/doctor.js";
+import { cmdCertify } from "../commands/certify.js";
 import { cmdSupport } from "../commands/support.js";
 import { cmdService } from "../commands/service.js";
 import { checkBuild } from "../core/build.js";
@@ -91,7 +92,8 @@ function help() {
         cmdRow("init [name]", "Scaffold work/, repoos.toml, AGENTS.md; outside a git repo runs a guided flow that can launch the web console"),
         cmdRow("list [status]", `Show the board (or one column: ${c.dim("inbox|ready|active|review|done")})`),
         cmdRow("status [--json]", "One-screen health snapshot: server, build freshness, board, worktrees, tunnel, git"),
-        cmdRow("doctor [--json]", "Read-only readiness preflight: identity, config, layout, tools, check plan, server, secrets"),
+        cmdRow("doctor [--json] [--probe <cli>] [--binary <path>]", "Readiness preflight: identity, config, layout, tools, check plan, server, secrets (--probe runs a live contract check; --binary overrides PATH resolution)"),
+        cmdRow("certify <cli> [--yes] [--binary <path>]", "Run the adapter contract suite and write certification evidence into agent-compatibility.json (--binary probes a specific binary)"),
         cmdRow("support bundle", "Write a redacted, inspectable diagnostic bundle for failed setups"),
         cmdRow("show <id>", "Show a task's full spec"),
         cmdRow("mv <id> <status>", `Move a task to a new status — never merges code   ${c.dim('flags: --note "...", --force-not-merged')}`),
@@ -101,7 +103,7 @@ function help() {
         cmdRow('new-doc "<desc>"', "Create a document from a description via PM agent"),
         cmdRow("index [--json]", "Rebuild the derived index cache"),
         cmdRow("gc [--yes|--dry-run]", "Collect leaked task worktrees/branches (done/absent tasks, integrate candidates)"),
-        cmdRow("serve [--port N]", "Start the local server (live API + SSE stream)"),
+        cmdRow("serve [--port N]", `Start the local server (live API + SSE stream)   ${c.dim("flags: --host, --preview-overrides, --no-preview-overrides")}`),
         cmdRow("stop [--port N]", "Stop this repo's serve process (by its own lockfile)"),
         cmdRow("service [sub]", `Manage background services ${c.dim("list|status|install|start|stop|restart|enable|disable|remove")}`),
         cmdRow("tunnel <sub>", `Publish local apps via Cloudflare Tunnel + Zero Trust ${c.dim("(setup|create|allow|deny|rename|destroy|start|install|stop|list|status)")}`),
@@ -163,6 +165,7 @@ function main() {
         "check",
         "status",
         "doctor",
+        "certify",
         "support",
         "help",
         "--help",
@@ -201,6 +204,9 @@ function main() {
         case "doctor":
             void cmdDoctor(rest);
             break;
+        case "certify":
+            void cmdCertify(rest);
+            break;
         case "support":
             void cmdSupport(rest);
             break;

package/dist/commands/certify.d.ts

@@ -0,0 +1,10 @@
+export interface CertifyCliArgs {
+    cli: string | null;
+    yes: boolean;
+    json: boolean;
+    missingCli: boolean;
+    /** Explicit binary path — skips PATH resolution and probes this binary directly. */
+    binary: string | null;
+}
+export declare function parseCertifyArgs(argv: string[]): CertifyCliArgs;
+export declare function cmdCertify(argv: string[]): Promise<void>;

package/dist/commands/certify.js

@@ -0,0 +1,198 @@
+/**
+ * `repoos certify <cli> [--yes] [--json]` — run the adapter contract suite and,
+ * when every seam passes, write the certification evidence back into
+ * `src/core/agent-compatibility.json` automatically.
+ *
+ * This is the maintainer-facing counterpart to `repoos doctor --probe`: doctor
+ * shows you the result; certify also commits it to the manifest so the next
+ * RepoOS release ships the updated compatibility status to all users.
+ *
+ * The command resolves the manifest path the same way `agent-compatibility.ts`
+ * does — src/core/ in a dev checkout, dist/core/ in a built install — and
+ * writes back to whichever file it loaded from.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { join } from "node:path";
+import { runAdapterContract } from "../core/agent-contract.js";
+import { parseAgentVersion } from "../core/agent-compatibility.js";
+import { c } from "../cli/colors.js";
+export function parseCertifyArgs(argv) {
+    const yes = argv.includes("--yes");
+    const json = argv.includes("--json");
+    const binaryIdx = argv.indexOf("--binary");
+    const binary = binaryIdx !== -1 ? (argv[binaryIdx + 1] ?? null) : null;
+    const positional = argv.filter((a, i) => !a.startsWith("--") && argv[i - 1] !== "--binary");
+    const cli = positional[0] ?? null;
+    return { cli, yes, json, missingCli: !cli, binary };
+}
+/** Locate the live manifest file on disk (src or dist). */
+function findManifestPath() {
+    const manifestUrl = new URL("../core/agent-compatibility.json", import.meta.url);
+    const candidates = [];
+    if (manifestUrl.protocol === "file:") {
+        candidates.push(fileURLToPath(manifestUrl));
+    }
+    candidates.push(join(process.cwd(), "src/core/agent-compatibility.json"), join(process.cwd(), "dist/core/agent-compatibility.json"));
+    const root = process.env.REPOOS_ROOT;
+    if (root) {
+        candidates.push(join(root, "src/core/agent-compatibility.json"), join(root, "dist/core/agent-compatibility.json"));
+    }
+    for (const p of candidates) {
+        try {
+            if (existsSync(p))
+                return p;
+        }
+        catch {
+            /* skip */
+        }
+    }
+    return null;
+}
+function loadManifest(path) {
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+function saveManifest(path, manifest) {
+    writeFileSync(path, JSON.stringify(manifest, null, 2) + "\n", "utf8");
+}
+export async function cmdCertify(argv) {
+    const { cli, yes, json: asJson, missingCli, binary } = parseCertifyArgs(argv);
+    if (missingCli || !cli) {
+        console.error(c.red("  repoos certify needs a harness id, e.g. `repoos certify opencode`."));
+        console.error(c.dim("    Use --binary <path> to probe a specific binary instead of PATH resolution."));
+        process.exitCode = 1;
+        return;
+    }
+    const WARNING = [
+        "",
+        c.yellow(c.bold("⚠ Live compatibility probe + manifest write")),
+        "    This runs the adapter contract suite against the installed harness and,",
+        "    if every seam passes, writes the certification evidence into",
+        "    src/core/agent-compatibility.json. It may use your provider credentials",
+        "    and spend tokens. It never reads task files or project content.",
+        "",
+    ].join("\n");
+    if (!yes) {
+        if (!process.stdin.isTTY) {
+            console.error(c.red("  repoos certify requires --yes when stdin is not a terminal."));
+            console.error(c.dim("    repoos certify " + cli + " --yes"));
+            process.exitCode = 1;
+            return;
+        }
+        const { createInterface } = await import("node:readline");
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        console.log(WARNING);
+        const answer = await new Promise((resolve) => {
+            rl.question(c.bold(`  Run the ${cli} probe and write results to the manifest? [y/N] `), resolve);
+        });
+        rl.close();
+        if (!/^y(es)?$/i.test(answer.trim())) {
+            console.log(c.dim("  Cancelled."));
+            return;
+        }
+    }
+    else if (!asJson) {
+        console.log(WARNING);
+    }
+    // Run the probe.
+    const result = await runAdapterContract({
+        cli,
+        mode: "live",
+        ...(binary ? { bin: binary } : {}),
+    });
+    if (asJson) {
+        console.log(JSON.stringify(result, null, 2));
+        if (!result.passed)
+            process.exitCode = 1;
+        return;
+    }
+    // Print probe output (same as doctor --probe).
+    console.log("");
+    console.log("  " +
+        c.bold(c.cyan("Adapter contract probe")) +
+        c.dim(" — " + result.cli) +
+        c.dim(" (" + result.binary + ")"));
+    for (const cap of result.capabilities) {
+        const icon = cap.ok ? c.green("✔") : c.red("✗");
+        console.log("    " + icon + " " + cap.label + c.dim("  (" + cap.id + ")"));
+        console.log("      " + c.dim(cap.detail));
+    }
+    const passCount = result.capabilities.filter((cap) => cap.ok).length;
+    const verdict = result.passed
+        ? c.green(`PASSED — ${result.capabilities.length}/${result.capabilities.length} seams`)
+        : c.red(`FAILED — ${passCount}/${result.capabilities.length} seams`);
+    console.log("");
+    console.log("  " + verdict + c.dim(`  (${Math.round(result.durationMs / 1000)}s)`));
+    if (!result.passed) {
+        console.log("");
+        console.log(c.dim("  Manifest not updated — probe must pass all seams to certify."));
+        console.log("");
+        process.exitCode = 1;
+        return;
+    }
+    // Locate the manifest and update it.
+    const manifestPath = findManifestPath();
+    if (!manifestPath) {
+        console.error(c.red("  Cannot find agent-compatibility.json to write certification."));
+        console.error(c.dim("  Run from the repoos source checkout, or set REPOOS_ROOT."));
+        process.exitCode = 1;
+        return;
+    }
+    const manifest = loadManifest(manifestPath);
+    const versionStr = result.detectedVersion ? result.detectedVersion.join(".") : null;
+    const now = new Date().toISOString().slice(0, 10); // YYYY-MM-DD
+    const source = `repoos certify ${cli} live probe — ${result.capabilities.length}/${result.capabilities.length} seams passed on ${result.startedAt} against binary ${result.binary}`;
+    let contract = manifest.contracts.find((c) => c.cli === cli);
+    if (!contract) {
+        // Bootstrap a minimal contract for a harness that has no entry yet.
+        const major = result.detectedVersion?.[0] ?? 0;
+        contract = {
+            cli,
+            name: cli,
+            supportedMajor: major,
+            supportedRange: `>=${major}.0.0 <${major + 1}.0.0`,
+            newestCertifiedVersion: versionStr,
+            knownIncompatibleRanges: [],
+            requiredCapabilities: result.capabilities.filter((c) => c.ok).map((c) => c.id),
+            verifiedAt: now,
+            verificationSource: source,
+            upgradeGuidance: `Install the current ${cli} release and re-run \`repoos certify ${cli}\`.`,
+            officialUrl: "",
+        };
+        manifest.contracts.push(contract);
+        console.log("");
+        console.log("  " + c.yellow("⚠ No existing contract — bootstrapped a new entry."));
+        console.log(c.dim("    Review src/core/agent-compatibility.json before committing:"));
+        console.log(c.dim(`    officialUrl, upgradeGuidance, and supportedRange may need editing.`));
+    }
+    else {
+        // Update the three certification fields.
+        const prev = contract.newestCertifiedVersion;
+        const prevParsed = prev ? parseAgentVersion(prev) : null;
+        const thisParsed = result.detectedVersion;
+        // Only advance newestCertifiedVersion — never roll it back.
+        if (!prevParsed ||
+            !thisParsed ||
+            thisParsed[0] > prevParsed[0] ||
+            (thisParsed[0] === prevParsed[0] && thisParsed[1] > prevParsed[1]) ||
+            (thisParsed[0] === prevParsed[0] &&
+                thisParsed[1] === prevParsed[1] &&
+                thisParsed[2] >= prevParsed[2])) {
+            contract.newestCertifiedVersion = versionStr;
+        }
+        contract.verifiedAt = now;
+        contract.verificationSource = source;
+    }
+    saveManifest(manifestPath, manifest);
+    console.log("");
+    console.log("  " + c.green("✔ Manifest updated") + c.dim(" — " + manifestPath));
+    if (versionStr) {
+        console.log(c.dim(`    newestCertifiedVersion: ${versionStr}`));
+    }
+    console.log(c.dim(`    verifiedAt: ${now}`));
+    console.log("");
+    console.log(c.dim("  Next: review the diff, then commit:"));
+    console.log(c.dim(`    git diff src/core/agent-compatibility.json`));
+    console.log(c.dim(`    git add src/core/agent-compatibility.json && git commit -m "cert(${cli}): certify ${versionStr ?? "unknown"}"`));
+    console.log("");
+}

package/dist/commands/doctor.d.ts

@@ -1,4 +1,20 @@
 import { type DoctorReport } from "../core/doctor.js";
+export interface DoctorCliArgs {
+    json: boolean;
+    yes: boolean;
+    /** Value passed to `--probe`, or null when the flag is absent. */
+    probe: string | null;
+    /** True when `--probe` was given without a value (or before another flag). */
+    probeMissingValue: boolean;
+    /** Explicit binary path for the probe — bypasses PATH resolution. */
+    binary: string | null;
+}
+/**
+ * Parse `repoos doctor`'s argument list. Kept pure and exported so the probe
+ * arming rules (`--probe` needs a value; `--probe --yes` is a usage error) are
+ * unit-tested rather than only exercised through a live run.
+ */
+export declare function parseDoctorArgs(argv: string[]): DoctorCliArgs;
 export declare function renderDoctor(report: DoctorReport): void;
-/** `repoos doctor [--json]` */
+/** `repoos doctor [--json] [--probe <cli>] [--yes]` */
 export declare function cmdDoctor(argv: string[]): Promise<void>;

package/dist/commands/doctor.js

@@ -1,16 +1,42 @@
 /**
- * `repoos doctor [--json]` — human and machine rendering of the readiness
- * preflight built in `src/core/doctor.ts`.
+ * `repoos doctor [--json] [--probe <cli>] [--yes]` — human and machine
+ * rendering of the readiness preflight built in `src/core/doctor.ts`.
  *
  * The command adds no diagnostic logic of its own: it runs the engine, prints
  * it, and sets the exit code (non-zero when any finding is a `fail`, so it is
  * usable in scripts). `--json` emits the same `DoctorReport` the UI and the
  * support bundle (#0453) consume.
+ *
+ * `--probe <cli>` runs the live adapter contract suite for that harness
+ * (`src/core/agent-contract.ts`) instead of the static report. It is opt-in
+ * and may use provider credentials/tokens, so it warns, asks for confirmation
+ * on a TTY (or requires `--yes` headless), runs in an isolated temp fixture,
+ * and cleans up.
  */
 import { readBuildMeta } from "../core/build.js";
+import { runAdapterContract } from "../core/agent-contract.js";
 import { doctorRemediations, DOCTOR_CATEGORIES, runDoctor, } from "../core/doctor.js";
 import { c } from "../cli/colors.js";
 const ICON = { pass: "✔", warn: "⚠", fail: "✗" };
+/**
+ * Parse `repoos doctor`'s argument list. Kept pure and exported so the probe
+ * arming rules (`--probe` needs a value; `--probe --yes` is a usage error) are
+ * unit-tested rather than only exercised through a live run.
+ */
+export function parseDoctorArgs(argv) {
+    const json = argv.includes("--json");
+    const yes = argv.includes("--yes");
+    const binaryIdx = argv.indexOf("--binary");
+    const binary = binaryIdx !== -1 ? (argv[binaryIdx + 1] ?? null) : null;
+    const probeArg = argv.indexOf("--probe");
+    if (probeArg === -1)
+        return { json, yes, probe: null, probeMissingValue: false, binary };
+    const value = argv[probeArg + 1];
+    if (!value || value.startsWith("--")) {
+        return { json, yes, probe: null, probeMissingValue: true, binary };
+    }
+    return { json, yes, probe: value, probeMissingValue: false, binary };
+}
 function severityColor(severity, text) {
     if (severity === "pass")
         return c.green(text);
@@ -57,9 +83,18 @@ export function renderDoctor(report) {
     }
     console.log("");
 }
-/** `repoos doctor [--json]` */
+/** `repoos doctor [--json] [--probe <cli>] [--yes]` */
 export async function cmdDoctor(argv) {
-    const asJson = argv.includes("--json");
+    const { json: asJson, yes, probe: probeCli, probeMissingValue, binary } = parseDoctorArgs(argv);
+    if (probeMissingValue) {
+        console.error(c.red("  repoos doctor --probe needs a harness id, e.g. `--probe opencode`."));
+        process.exitCode = 1;
+        return;
+    }
+    if (probeCli) {
+        await cmdProbe(probeCli, { asJson, yes, binary });
+        return;
+    }
     try {
         const report = await runDoctor({ version: readBuildMeta().version });
         if (asJson) {
@@ -76,3 +111,85 @@ export async function cmdDoctor(argv) {
         process.exitCode = 1;
     }
 }
+/**
+ * Live adapter-contract probe (`repoos doctor --probe <cli>`). Opt-in: warns
+ * that provider credentials/tokens may be spent, confirms on a TTY (or demands
+ * `--yes` headless), runs every seam in an isolated temp fixture, and reports
+ * the honest result. A passed probe is the evidence a maintainer records in
+ * `src/core/agent-compatibility.json` (verifiedAt + verificationSource).
+ */
+async function cmdProbe(cli, opts) {
+    const WARNING = [
+        "",
+        c.yellow(c.bold("⚠ Live compatibility probe")),
+        "    This runs the installed harness in an isolated temporary directory,",
+        "    exercising version, help, model listing, a headless one-shot, event",
+        "    parsing, permission/auto mode, session continuation, and cancellation.",
+        "    It may use your provider credentials and spend tokens: the one-shot,",
+        "    resume, and cancellation seams each start a real harness run. It never",
+        "    reads task files, prompts, or project content, and the temporary fixture",
+        "    is removed when done.",
+        "",
+    ].join("\n");
+    if (!opts.yes) {
+        if (!process.stdin.isTTY) {
+            console.error(c.red("  repoos doctor --probe requires --yes when stdin is not a terminal."));
+            console.error(c.dim("    repoos doctor --probe " + cli + " --yes"));
+            process.exitCode = 1;
+            return;
+        }
+        const { createInterface } = await import("node:readline");
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        console.log(WARNING);
+        const answer = await new Promise((resolve) => {
+            rl.question(c.bold(`  Run the live ${cli} compatibility probe? [y/N] `), resolve);
+        });
+        rl.close();
+        if (!/^y(es)?$/i.test(answer.trim())) {
+            console.log(c.dim("  Probe cancelled."));
+            return;
+        }
+    }
+    else if (!opts.asJson) {
+        console.log(WARNING);
+    }
+    try {
+        const result = await runAdapterContract({
+            cli,
+            mode: "live",
+            ...(opts.binary ? { bin: opts.binary } : {}),
+        });
+        if (opts.asJson) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            console.log("");
+            console.log("  " +
+                c.bold(c.cyan("Adapter contract probe")) +
+                c.dim(" — " + result.cli) +
+                c.dim(" (" + result.binary + ")"));
+            for (const cap of result.capabilities) {
+                const icon = cap.ok ? c.green("✔") : c.red("✗");
+                console.log("    " + icon + " " + cap.label + c.dim("  (" + cap.id + ")"));
+                console.log("      " + c.dim(cap.detail));
+            }
+            const verdict = result.passed
+                ? c.green(`PASSED — ${result.capabilities.length}/${result.capabilities.length} seams`)
+                : c.red(`FAILED — ${result.capabilities.filter((cap) => cap.ok).length}/${result.capabilities.length} seams`);
+            console.log("");
+            console.log("  " + verdict + c.dim(`  (${Math.round(result.durationMs / 1000)}s)`));
+            if (result.passed && result.evidence) {
+                console.log("");
+                console.log("  " + c.bold("Record evidence in the manifest"));
+                console.log("    " + c.dim(result.evidence));
+            }
+            console.log("");
+        }
+        if (!result.passed)
+            process.exitCode = 1;
+    }
+    catch (e) {
+        console.error(c.red("  repoos doctor --probe failed: ") + e.message);
+        process.exitCode = 1;
+    }
+}

package/dist/commands/serve.d.ts

@@ -40,6 +40,17 @@ export declare function resolveServeHost(explicitHost?: string): {
     tailscaleDetected: boolean;
     tailscaleIP?: string;
 };
+/**
+ * Whether this `repoos serve` should apply the repo's preview-only
+ * `[preview.*]` config overlay (#0464).
+ *
+ * Precedence, lowest to highest: the REPOOS_PREVIEW_CHILD=1 marker (set by
+ * PreviewManager on every managed preview child) turns it on; an explicit
+ * `--no-preview-overrides`/`--preview-overrides` flag always wins. An ordinary
+ * `repoos serve` has neither, so it resolves the base configuration unchanged.
+ * Exported for tests.
+ */
+export declare function resolvePreviewOverrides(args: readonly string[], env?: NodeJS.ProcessEnv): boolean;
 /**
  * True when this process is a managed agent (REPOOS_AGENT=1) attempting to
  * launch `repoos serve` directly, as opposed to a preview child or a reload

package/dist/commands/serve.js

@@ -79,6 +79,26 @@ export function resolveServeHost(explicitHost) {
         return { host: "0.0.0.0", tailscaleDetected: true, tailscaleIP };
     return { host: "127.0.0.1", tailscaleDetected: false };
 }
+/**
+ * Whether this `repoos serve` should apply the repo's preview-only
+ * `[preview.*]` config overlay (#0464).
+ *
+ * Precedence, lowest to highest: the REPOOS_PREVIEW_CHILD=1 marker (set by
+ * PreviewManager on every managed preview child) turns it on; an explicit
+ * `--no-preview-overrides`/`--preview-overrides` flag always wins. An ordinary
+ * `repoos serve` has neither, so it resolves the base configuration unchanged.
+ * Exported for tests.
+ */
+export function resolvePreviewOverrides(args, env = process.env) {
+    let explicit;
+    for (const arg of args) {
+        if (arg === "--preview-overrides")
+            explicit = true;
+        else if (arg === "--no-preview-overrides")
+            explicit = false;
+    }
+    return explicit ?? env.REPOOS_PREVIEW_CHILD === "1";
+}
 /**
  * True when this process is a managed agent (REPOOS_AGENT=1) attempting to
  * launch `repoos serve` directly, as opposed to a preview child or a reload
@@ -116,6 +136,12 @@ export async function cmdServe(args, opts = {}) {
         else if (args[i] === "--quiet" || args[i] === "-q")
             quiet = true;
     }
+    // Preview-only config overlay (#0464). A managed preview child
+    // (REPOOS_PREVIEW_CHILD=1, set by PreviewManager) applies the repo's
+    // `[preview.*]` overlay by default; every ordinary `repoos serve` resolves
+    // the base configuration. `--preview-overrides` forces it on (UI-test
+    // previews); `--no-preview-overrides` is the escape hatch back to base.
+    const applyPreviewOverrides = resolvePreviewOverrides(args);
     const { host, tailscaleDetected, tailscaleIP } = resolveServeHost(explicitHost);
     let handle;
     try {
@@ -124,6 +150,8 @@ export async function cmdServe(args, opts = {}) {
         handle = await startServer({
             port,
             host,
+            hostExplicit: explicitHost !== undefined,
+            previewOverrides: applyPreviewOverrides,
             reloadReplacement: process.env.REPOOS_RELOAD === "1",
         });
     }
@@ -149,6 +177,11 @@ export async function cmdServe(args, opts = {}) {
         snap.taskCount +
         c.dim(" tasks  ·  SSE stream at ") +
         c.cyan(handle.url + "/api/events"));
+    // Report an active preview-only overlay and its effective keys (#0464), so a
+    // preview that deliberately differs from the base config is never silent.
+    if (handle.previewOverrides?.length) {
+        console.log(c.yellow("  preview overrides active: ") + c.dim(handle.previewOverrides.join(", ")));
+    }
     const rt = isBun()
         ? `Bun ${process.versions.bun ?? ""}`.trim()
         : `Node ${process.versions.node}`;

package/dist/commands/service.js

@@ -15,7 +15,7 @@
  * Commands operate on the current repo by default.
  */
 import { listServices, getServiceStatus, installService, removeService, startService, stopService, restartService, enableAutoStart, disableAutoStart, checkHealth, } from "../core/service-manager.js";
-import { boardRoot, deriveServePort, loadConfig } from "../core/config.js";
+import { boardRoot, loadConfig, resolveServePort } from "../core/config.js";
 import { c } from "../cli/colors.js";
 function statusLabel(s) {
     if (s === "running")
@@ -78,7 +78,7 @@ export async function cmdService(argv) {
         case "install": {
             const { root } = boardRoot();
             const config = loadConfig(root);
-            const port = deriveServePort(root);
+            const port = resolveServePort(root, config);
             const result = await installService(root, port, { autoStart: false });
             if (!result.ok) {
                 console.error(c.red("  ✗ " + result.error));

package/dist/commands/tasks.d.ts

@@ -50,8 +50,8 @@ export declare function cmdMv(id?: string, status?: string, note?: string, opts?
  */
 export declare function cmdNote(args: string[]): void;
 /**
- * `repoos update <id> [--title ...] [--area ...] [--priority ...] [--type ...]
- *   [--body ... | --body -] [--branch ...] [--assigned-to ai|human]
+ * `repoos update <id> [--title ...] [--area ...] [--story ...] [--priority ...]
+ *   [--type ...] [--body ... | --body -] [--branch ...] [--assigned-to ai|human]
  *   [--needs-input true|false] [--questions "Question one\nQuestion two"]`
  *
  * Writes directly via patchTaskFile (same path the server's PATCH route uses),

package/dist/commands/tasks.js

@@ -248,6 +248,7 @@ export function cmdNote(args) {
 const UPDATE_FLAGS = {
     title: "title",
     area: "area",
+    story: "story",
     priority: "priority",
     type: "type",
     body: "body",
@@ -257,8 +258,8 @@ const UPDATE_FLAGS = {
     questions: "questions",
 };
 /**
- * `repoos update <id> [--title ...] [--area ...] [--priority ...] [--type ...]
- *   [--body ... | --body -] [--branch ...] [--assigned-to ai|human]
+ * `repoos update <id> [--title ...] [--area ...] [--story ...] [--priority ...]
+ *   [--type ...] [--body ... | --body -] [--branch ...] [--assigned-to ai|human]
  *   [--needs-input true|false] [--questions "Question one\nQuestion two"]`
  *
  * Writes directly via patchTaskFile (same path the server's PATCH route uses),
@@ -268,7 +269,7 @@ const UPDATE_FLAGS = {
  */
 export function cmdUpdate(args) {
     const [id, ...rest] = args;
-    const usage = '  Usage: repoos update <id> [--title "..."] [--area a] [--priority p] [--type t] [--body "..."|-] [--branch b] [--assigned-to ai|human] [--needs-input true|false] [--questions "Question one\\nQuestion two"] [--clear-questions]';
+    const usage = '  Usage: repoos update <id> [--title "..."] [--area a] [--story "Delivery slice"] [--priority p] [--type t] [--body "..."|-] [--branch b] [--assigned-to ai|human] [--needs-input true|false] [--questions "Question one\\nQuestion two"] [--clear-questions]';
     if (!id) {
         console.error(c.red(usage));
         process.exitCode = 1;
@@ -337,7 +338,16 @@ export function cmdUpdate(args) {
         process.exitCode = 1;
     }
 }
-const NEW_FLAGS = new Set(["ai", "type", "area", "priority", "body", "needs-input", "questions"]);
+const NEW_FLAGS = new Set([
+    "ai",
+    "type",
+    "area",
+    "story",
+    "priority",
+    "body",
+    "needs-input",
+    "questions",
+]);
 function parseQuestions(raw) {
     try {
         const parsed = JSON.parse(raw);
@@ -355,7 +365,7 @@ function parseQuestions(raw) {
 }
 /** `repoos new <title> [--ai] [--needs-input true] [--questions "..."]` */
 export function cmdNew(args) {
-    const usage = '  Usage: repoos new "Task title" [--ai] [--type bug] [--area web] [--priority p1] [--body "..."|-] [--needs-input true|false] [--questions "Question one\\nQuestion two"]';
+    const usage = '  Usage: repoos new "Task title" [--ai] [--type bug] [--area web] [--story "Delivery slice"] [--priority p1] [--body "..."|-] [--needs-input true|false] [--questions "Question one\\nQuestion two"]';
     const flags = {};
     const positional = [];
     for (let i = 0; i < args.length; i++) {
@@ -396,6 +406,7 @@ export function cmdNew(args) {
         title,
         type: flags.type || undefined,
         area: flags.area || undefined,
+        story: flags.story || undefined,
         priority: flags.priority || undefined,
         assignedTo: flags.ai ? "ai" : undefined,
         body: flags.body || undefined,

package/dist/commands/ui-harness.js

@@ -18,7 +18,17 @@ export async function startPreviewServer(root) {
     // disableAuth: the smoke gate tests generic rendering (title, board,
     // buttons), not auth flows — a project with [auth] enabled must not make
     // `repoos check` itself unable to reach the dashboard.
-    const opts = { host: "127.0.0.1", port: 0, disableAuth: true };
+    //
+    // previewOverrides: this is the UI-test preview path, so it resolves the same
+    // preview-only `[preview.*]` overlay a managed preview applies (#0464). The
+    // smoke test's throwaway fixture declares no overlay, so this is normally a
+    // no-op; it matters when the harness serves a real root.
+    const opts = {
+        host: "127.0.0.1",
+        port: 0,
+        disableAuth: true,
+        previewOverrides: true,
+    };
     if (root !== undefined)
         opts.root = root;
     return startServer(opts);