@repo-os/repoos 0.5.57 → 0.5.59

package/README.md

@@ -96,7 +96,7 @@ install, `repoos upgrade` prints the matching package-manager command instead.
 Then in any repo:
 
 ```bash
-repoos init        # scaffold work/, docs/, repoos.toml, AGENTS.md (idempotent)
+repoos init        # scaffold repoos/work/, repoos/docs/, repoos.toml, AGENTS.md (idempotent)
 ```
 
 Zero config required. `repoos init` walks up to find your repo root, creates the
@@ -219,6 +219,14 @@ your other Tailscale devices and from localhost-only tools on the same machine
 (e.g. a Cloudflare Tunnel's local origin). Pass `--host 127.0.0.1` explicitly
 to restrict it to localhost only.
 
+In that mode `repoos serve` also runs `tailscale serve` for you and prints an
+`https://<machine>.<tailnet>.ts.net` URL. Use it: a plain-`http://` Tailscale IP
+isn't a browser secure context, so some UI features can't work there. It is
+tailnet-only (not Funnel), never overwrites another `tailscale serve` mapping
+(it falls back to port 8443, then 10000), and needs MagicDNS + HTTPS
+Certificates enabled in the Tailscale admin console (`serve` prints a hint if
+not). Pass `--no-tailscale-https` to skip it.
+
 ### Endpoints
 
 ```

package/dist/.build-info.json

@@ -1,5 +1,5 @@
 {
-  "hash": "69cefc15aead79d33e1a4fcf9b4d8d1358152d8f214530f3af45226fbe121036",
-  "version": "0.5.57",
+  "hash": "54bb7cbb6f6758af0e4594f62905c10fa0aa98c53e313ec47f2d21da7c028692",
+  "version": "0.5.59",
   "devUi": false
 }

package/dist/.build-stamp.json

@@ -1,3 +1,3 @@
 {
-  "generatedAt": "2026-09-29T11:51:40.533Z"
+  "generatedAt": "2026-09-29T23:17:06.252Z"
 }

package/dist/cli/index.js

@@ -8,6 +8,7 @@ import { cmdList, cmdShow, cmdMv, cmdUpdate, cmdNew, cmdIndex, cmdNote, } from "
 import { cmdNewDoc } from "../commands/docs.js";
 import { cmdGc } from "../commands/gc.js";
 import { cmdCheck } from "../commands/check.js";
+import { cmdShot } from "../commands/shot.js";
 import { cmdServe, serveProcessTitle, setServeProcessTitle } from "../commands/serve.js";
 import { cmdStop } from "../commands/stop.js";
 import { cmdTunnel } from "../commands/tunnel.js";
@@ -22,9 +23,7 @@ import { checkBuild } from "../core/build.js";
 import { loadConfig } from "../core/config.js";
 import { reexecAfterStaleBuild, reexecUnderBunIfRequested } from "../core/runtime.js";
 import { c } from "./colors.js";
-import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { readVersion } from "../core/version.js";
 // node:sqlite (used by db.ts/auth-store.ts) is still marked experimental on
 // supported Node versions and prints a warning the first time it's loaded.
 // That's expected/stable usage here, not something a user needs to see —
@@ -39,19 +38,6 @@ process.on("warning", (warning) => {
         return;
     console.warn(warning);
 });
-/** Reads the version stamped into .build-info.json at build time; falls back for dev/source runs. */
-function readVersion() {
-    try {
-        const root = dirname(dirname(fileURLToPath(import.meta.url)));
-        const info = JSON.parse(readFileSync(join(root, ".build-info.json"), "utf8"));
-        if (info.version)
-            return info.version;
-    }
-    catch {
-        /* fall through */
-    }
-    return "0.0.0-dev";
-}
 const VERSION = readVersion();
 // Column where COMMANDS descriptions start, measured from the start of the
 // command text (not counting the leading 4-space indent). Wide enough for
@@ -89,6 +75,7 @@ function help() {
         cmdRow("check --profile full", "Run every declared step, including ones held back from a routine run"),
         cmdRow("check --changed main", "Fast pre-review pass over steps affected by changed paths"),
         cmdRow("check --print-plan", "Print the resolved plan as [[check.steps]] TOML to commit"),
+        cmdRow("shot [<route|url>]", `Capture preview screenshots into the task's shots folder   ${c.dim("flags: --target --selector --task --base --wait --full-page")}`),
         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"),
@@ -103,7 +90,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)   ${c.dim("flags: --host, --preview-overrides, --no-preview-overrides")}`),
+        cmdRow("serve [--port N]", `Start the local server (live API + SSE stream)   ${c.dim("flags: --host, --no-tailscale-https, --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)")}`),
@@ -113,13 +100,16 @@ function help() {
     const exampleLines = [
         exRow("repoos init"),
         exRow("repoos init myproject", "guided new-project flow outside a git repo"),
-        exRow('repoos new "Add company dashboard" --ai --type feature --area web --priority p1'),
+        exRow('repoos new "Add company dashboard" --ai --type feature --area web,server --priority p1'),
         exRow('repoos new-doc "API design doc for the payment system"'),
         exRow("repoos mv 0012 active"),
         exRow('repoos mv 0012 active --note "Fix the regression in checkout; see review"'),
         exRow('repoos note 0012 "Handle the reviewer\'s suggestions before the next review"'),
-        exRow('repoos update 0012 --title "New title" --area web'),
+        exRow('repoos update 0012 --title "New title" --area web,core'),
         exRow("repoos list ready"),
+        exRow("repoos shot", "screenshot the task preview for the current worktree"),
+        exRow("repoos shot /repo/commits/abc123", "capture one route"),
+        exRow("repoos shot --target 'Docs site' --selector '.sidebar'"),
         exRow("repoos status", "one-screen health snapshot"),
         exRow("repoos status --json", "machine-readable, for agents/tools"),
         exRow("repoos index --json", "machine-readable, for agents/tools"),
@@ -264,6 +254,17 @@ function main() {
         case "check":
             void cmdCheck(rest);
             break;
+        case "shot":
+            void cmdShot(rest)
+                .then((code) => {
+                if (code !== 0)
+                    process.exitCode = code;
+            })
+                .catch((err) => {
+                console.error(c.red(`  ✗ shot failed: ${err.message}`));
+                process.exitCode = 1;
+            });
+            break;
         case "tunnel":
             void cmdTunnel(rest);
             break;

package/dist/commands/check.js

@@ -31,6 +31,7 @@ import { preferBunForDevTasks } from "../core/runtime.js";
 import { blockingFailures, DEFAULT_PROFILE, describeStep, formatPlanToml, resolveCheckPlan, selectSteps, } from "../core/check-plan.js";
 import { detectRepoMarkers, missingBinaries, prereqDetail, runCommand, stepCwd, } from "../core/check-runner.js";
 import { writeCheckRun } from "../core/check-results-store.js";
+import { extractFailedTests } from "../core/check-failure-summary.js";
 import { envToRunContext, getCheckStore, localMachineName } from "../core/check-store.js";
 import { mainCheckoutRoot } from "../core/git.js";
 import { Logger } from "../core/logger.js";
@@ -1640,6 +1641,9 @@ export async function cmdCheck(argv = []) {
         failedStep: gatingFailures[0]?.name ?? null,
         skippedSteps: results.filter((r) => r.status === "skipped").map((r) => r.name),
         detail: gatingFailures[0]?.detail ?? null,
+        // The stored detail is a short log tail that routinely loses the failing
+        // test's name; keep the names themselves so "which test?" is a query.
+        failedTests: gatingFailures.flatMap((r) => extractFailedTests(r.output ?? "")),
     });
     process.exit(gatingFailures.length > 0 ? 1 : 0);
 }
@@ -1672,6 +1676,7 @@ function recordRunHistoryRow(row) {
             failedStep: row.failedStep,
             skippedSteps: row.skippedSteps,
             detail: row.detail,
+            failedTests: row.failedTests,
         });
     }
     catch {

package/dist/commands/init.d.ts

@@ -1,3 +1,5 @@
+/** Blockquote every line, so a multi-line (pasted markdown) description stays one quote. */
+export declare function quoteBlock(text: string): string;
 /** Marker makes the optional existing-repo addition safe to offer repeatedly. */
 export declare const REPOOS_AGENTS_SECTION_MARKER = "<!-- repoos:managed-instructions -->";
 /**
@@ -19,7 +21,11 @@ export declare function repoOSAgentsSectionAddition(existing: string, workDir?:
 type ScaffoldLayout = string;
 /** Which starter task to seed beyond 0001 — a blank project or an existing repo. */
 type ScaffoldKind = "new" | "existing";
-export declare function scaffoldInto(root: string, description: string, layout?: ScaffoldLayout, kind?: ScaffoldKind): {
+export declare function scaffoldInto(root: string, description: string, layout?: ScaffoldLayout, kind?: ScaffoldKind, 
+/** Areas collected at init time (#0583) — real `[[areas]]` rows when given. */
+areas?: string[], 
+/** When true, scaffold commented `[[preview.targets]]` stubs for those areas. */
+previewStub?: boolean): {
     created: string[];
     skipped: string[];
 };

package/dist/commands/init.js

@@ -6,7 +6,7 @@
  * guided, interactive flow that creates a brand-new RepoOS project from
  * scratch: optionally in a subdirectory, with a choice of layout (repo root
  * vs. a `repoos/` subfolder, config file at root either way), an optional
- * one-line project description (seeded into the sample task) and an optional
+ * project description, one or many lines (seeded into the sample task) and an optional
  * initial commit.
  */
 import { spawn } from "node:child_process";
@@ -15,6 +15,8 @@ import { createServer } from "node:net";
 import { join, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
+import { canaryGitignoreIgnore, canaryGitignoreNegation, canaryRelPath } from "../core/canary.js";
+import { scaffoldCanaryFile } from "../core/canary-repo.js";
 import { deriveServePort, findRepoRoot, loadConfig } from "../core/config.js";
 import { CHECK_PLAN_PROPOSAL_FILE, proposeCheckPlan } from "../core/check-plan-proposal.js";
 import { formatPlanToml } from "../core/check-plan.js";
@@ -58,12 +60,19 @@ running \`repoos init\` already satisfies everything above. There's nothing to
 Status is a frontmatter field — never move files between folders. Keep diffs
 small. Read AGENTS.md before starting any task.
 `;
+/** Blockquote every line, so a multi-line (pasted markdown) description stays one quote. */
+export function quoteBlock(text) {
+    return text
+        .split("\n")
+        .map((line) => (line.trim() === "" ? ">" : `> ${line}`))
+        .join("\n");
+}
 /**
  * The first *workable* task a guided new-project init leaves on the board.
  * 0001 is deliberately `done` (scaffolding is the whole of it), so this is what
  * a new user — or their first agent — actually picks up. `repoos init` runs
  * before any server or agent exists, so the body itself is the prompt: it
- * embeds the one-line description collected at init and carries the questions
+ * embeds the description collected at init and carries the questions
  * that turn that description into docs and real tasks later.
  */
 const NEW_PROJECT_STARTER_TASK = (id, description, workDir = "work", docsDir = "docs") => `---
@@ -79,15 +88,15 @@ branch: ""
 ---
 ## Overview
 
-This project started from a one-line description. This task turns it into
+This project started from a short description. This task turns it into
 something a team can actually build from — a shared vision, an initial
 architecture, and a first batch of concrete work.
 
 ## Project description
 
 ${description
-    ? `> ${description}`
-    : "_No description was given at init time. Start by writing one line that says what this project is and who it's for._"}
+    ? quoteBlock(description)
+    : "_No description was given at init time. Start by writing a short description that says what this project is and who it's for._"}
 
 ## What to do
 
@@ -202,6 +211,15 @@ a candidate merge. Do not erase a task's branch metadata to force this path.
 
 ## Rules
 
+- **\`repoos.toml\` owns the layout.** \`workDir\` (\`${workDir}\`) and \`docsDir\`
+  (\`${docsDir}\`) are authoritative: tasks live under \`${workDir}/\` and project
+  docs under \`${docsDir}/\` because the config says so. Never move, rename or
+  relocate those directories, and never "fix" a layout you think is wrong by
+  moving files. If project docs or a person's own notes disagree with the
+  config, report the mismatch — the fix is to update \`repoos.toml\` with human
+  approval (or correct the docs), never to move directories on your own. Do not
+  invent ownership rules for RepoOS directories; the config is the only source
+  of truth for layout.
 - **Never** move task files between folders. Status lives in frontmatter.
 - **Never write directly to \`${workDir}/*.md\` files.** All task creation and
   manipulation goes through \`repoos\` commands or HTTP API endpoints
@@ -249,7 +267,10 @@ export const REPOOS_AGENTS_SECTION = (workDir) => `${REPOOS_AGENTS_SECTION_MARKE
 ## RepoOS
 
 RepoOS keeps tasks as Markdown under \`${workDir}/\` and runs task work in dedicated
-Git worktrees. Use the RepoOS UI or \`repoos\` commands to create and update
+Git worktrees. The layout is set by \`repoos.toml\` (\`workDir\`/\`docsDir\`/\`cacheDir\`):
+those paths are authoritative, so never move or rename them — if project docs
+disagree with the config, ask the human instead of relocating directories.
+Use the RepoOS UI or \`repoos\` commands to create and update
 tasks; do not hand-edit task files. Read the relevant project docs before
 starting work, run \`repoos check\` before handoff, and await human approval
 through RepoOS's **Move to done**. The reviewer is advisory. A Git remote does
@@ -267,7 +288,7 @@ export function repoOSAgentsSectionAddition(existing, workDir = "work") {
     }
     return (existing.endsWith("\n") ? "\n" : "\n\n") + REPOOS_AGENTS_SECTION(workDir);
 }
-function repoosToml(namespace) {
+function repoosToml(namespace, areas = [], previewStub = false) {
     const ns = namespace
         ? `workDir = "${namespace}/work"\ndocsDir = "${namespace}/docs"\ncacheDir = "${namespace}/.repoos"\n`
         : "";
@@ -305,8 +326,45 @@ defaultAssignee = "unassigned"
 # active = "In progress"
 # review = "Code review"
 # done   = "Shipped"
+${areaRows(areas)}
+${previewStub ? previewTargetRows(areas) : ""}
 `;
 }
+/**
+ * The `[areas]` block: the vocabulary collected at init time as real
+ * `[[areas]]` rows, or the commented-out stub when skipped (#0583).
+ */
+function areaRows(areas) {
+    if (!areas.length) {
+        return [
+            "# [[areas]]                             # the task-area vocabulary (#0583)",
+            '# name = "web"                           # offered in the area picker + the PM prompt',
+            '# description = "The main web app"',
+            "# Every [[preview.targets]] area is offered automatically, even when not",
+            "# declared here. With none declared the area field is free text only.",
+        ].join("\n");
+    }
+    return areas.map((a) => `[[areas]]\nname = "${a}"`).join("\n\n");
+}
+/**
+ * The commented `[[preview.targets]]` skeleton offered when an area vocabulary
+ * was seeded at init (#0583) — the wiring for when the project has something
+ * previewable, referencing the areas the picker now offers.
+ */
+function previewTargetRows(areas) {
+    const areaList = areas.length ? JSON.stringify(areas) : '["web"]';
+    return [
+        "# [preview]                               # read-only task previews",
+        `# command = "bun run dev --port {port} --host {host}"`,
+        `#                                         # default when no target matches`,
+        "",
+        `# [[preview.targets]]`,
+        `# name = "Main app"`,
+        `# areas = ${areaList}`,
+        `# command = "bun run dev --port {port} --host {host}"`,
+        `# readyTimeoutMs = 240000                 # raise for a command that also builds`,
+    ].join("\n");
+}
 const ENV_EXAMPLE = `# Copy to .env and fill in what you need — .env is gitignored, this file is
 # tracked so the repo documents which secrets a full setup expects.
 # repoos serve auto-loads .env at startup; real shell/process-supervisor env
@@ -380,7 +438,11 @@ function findStarter(root, workDir, slug) {
         return null;
     }
 }
-export function scaffoldInto(root, description, layout = "", kind = "new") {
+export function scaffoldInto(root, description, layout = "", kind = "new", 
+/** Areas collected at init time (#0583) — real `[[areas]]` rows when given. */
+areas = [], 
+/** When true, scaffold commented `[[preview.targets]]` stubs for those areas. */
+previewStub = false) {
     const created = [];
     const skipped = [];
     let aborted = false;
@@ -425,7 +487,7 @@ export function scaffoldInto(root, description, layout = "", kind = "new") {
     // Write config first so workDir/docsDir/cacheDir overrides are in effect
     // before the dirs are created (namespace layout) — or so an existing
     // config is respected untouched (existing-repo path).
-    ensureFile("repoos.toml", repoosToml(layout));
+    ensureFile("repoos.toml", repoosToml(layout, areas, previewStub));
     const config = loadConfig(root);
     ensureDir(config.workDir);
     ensureDir(config.docsDir);
@@ -449,10 +511,17 @@ export function scaffoldInto(root, description, layout = "", kind = "new") {
         ensureFile(join(config.workDir, `${starterId}-${starter.slug}.md`), starter.build(starterId, description, config.workDir, config.docsDir));
     }
     ensureFile(".env.example", ENV_EXAMPLE);
+    if (scaffoldCanaryFile(root, config.cacheDir)) {
+        created.push(canaryRelPath(config.cacheDir));
+    }
     // gitignore the derived cache and local secrets
     const giPath = join(root, ".gitignore");
     const ignoreLines = [
-        { comment: "# RepoOS derived index cache", line: `${config.cacheDir}/` },
+        { comment: "# RepoOS derived index cache", line: canaryGitignoreIgnore(config.cacheDir) },
+        {
+            comment: "# RepoOS canary flow-test counter (tracked)",
+            line: canaryGitignoreNegation(config.cacheDir),
+        },
         { comment: "# Local secrets — see .env.example", line: ".env" },
     ];
     const existingLines = existsSync(giPath) ? readFileSync(giPath, "utf8").split(/\r?\n/) : [];
@@ -521,6 +590,46 @@ async function ask(question) {
         rl.close();
     }
 }
+/**
+ * Like `ask`, but accepts multi-line input. On a TTY, a pasted block arrives as
+ * a burst of lines, so after each line we wait briefly for more; a typed line
+ * ending in `\\` also continues onto the next line. Non-TTY input (pipes, CI)
+ * stays strictly one line so later prompts' answers aren't swallowed.
+ */
+async function askMultiline(question) {
+    if (!input.isTTY)
+        return ask(question);
+    const rl = createInterface({ input, output });
+    return new Promise((resolvePromise) => {
+        const lines = [];
+        let timer;
+        let done = false;
+        const finish = () => {
+            if (done)
+                return;
+            done = true;
+            if (timer)
+                clearTimeout(timer);
+            rl.close();
+            resolvePromise(lines.join("\n").trim());
+        };
+        rl.on("close", finish);
+        rl.on("line", (line) => {
+            if (timer)
+                clearTimeout(timer);
+            if (line.endsWith("\\")) {
+                lines.push(line.slice(0, -1));
+                rl.setPrompt("  … ");
+                rl.prompt();
+                return;
+            }
+            lines.push(line);
+            timer = setTimeout(finish, 75);
+        });
+        rl.setPrompt(question);
+        rl.prompt();
+    });
+}
 async function confirm(question, dflt) {
     const hint = dflt ? " [Y/n]" : " [y/N]";
     const answer = (await ask(question + c.dim(hint) + " ")).toLowerCase();
@@ -854,9 +963,34 @@ async function guidedNewRepo(args) {
         console.log(c.yellow("\n  Cancelled — nothing was created."));
         return;
     }
-    const description = await ask("  Project description" +
-        c.dim(" — one line, gives the AI context to suggest next steps (optional, Enter to skip)") +
+    const description = await askMultiline("  Project description" +
+        c.dim(" — gives the AI context to suggest next steps; paste multi-line markdown or end a line with \\ to continue (optional, Enter to skip)") +
+        ": ");
+    // The task-area vocabulary (#0583) — reinforced with preview targets, since
+    // a `[[preview.targets]]` area is offered in the picker automatically even
+    // when not declared here. Skipped means free text only; never blocking.
+    const areasInput = await ask("  Task areas to seed the area picker" +
+        c.dim(" — comma-separated (e.g. web, cli, api; Enter to skip)") +
         ": ");
+    const areas = areasInput
+        ? areasInput
+            .split(",")
+            .map((a) => a.trim())
+            .filter(Boolean)
+        : [];
+    if (areas.length) {
+        console.log(c.dim("  Preview targets route a task preview by its area — the picker and"));
+        console.log(c.dim("  the PM prompt offer target areas automatically; see user-docs/configuration.md's Previews section."));
+    }
+    // Preview targets reinforce areas ("define them together"): when an area
+    // vocabulary was given, offer to scaffold the commented `[[preview.targets]]`
+    // skeleton those areas feed, so the wiring sits where preview setup happens
+    // later. A brand-new project has nothing runnable yet — never a live
+    // preview command, just the commented shape to fill in.
+    let previewStub = false;
+    if (areas.length) {
+        previewStub = await confirm("  Scaffold commented preview-target stubs for these areas?", false);
+    }
     if (!existsSync(target))
         mkdirSync(target, { recursive: true });
     // git health warnings — fail-soft, scaffold regardless
@@ -869,7 +1003,7 @@ async function guidedNewRepo(args) {
         console.log(c.dim("    git may auto-detect it, or the initial commit may fail. Set it with:"));
         console.log(c.dim('    git config --global user.name "You" && git config --global user.email you@example.com'));
     }
-    const { created, skipped } = scaffoldInto(target, description, layout);
+    const { created, skipped } = scaffoldInto(target, description, layout, "new", areas, previewStub);
     reportInit(target, created, skipped);
     await offerCheckPlanProposal(target);
     if (!gitOk) {

package/dist/commands/serve-banner.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/serve-banner.test.js

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import { renderServeBanner } from "./serve.js";
+describe("renderServeBanner", () => {
+    const rows = [
+        { label: "Local", value: "http://127.0.0.1:7515" },
+        { label: "Tailnet HTTPS", value: "x" },
+    ];
+    it("shows the version and aligns labels", () => {
+        const out = renderServeBanner("1.2.3", rows);
+        expect(out).toContain("RepoOS v1.2.3");
+        expect(out).toContain("Local          http://127.0.0.1:7515");
+    });
+    it("splits an HTTPS warning into problem, fix and link", () => {
+        const out = renderServeBanner("1.2.3", rows, "HTTPS certificates aren't enabled for your tailnet — turn on MagicDNS and HTTPS Certificates at https://login.tailscale.com/admin/dns");
+        expect(out).toContain("Tailscale HTTPS unavailable");
+        expect(out).toContain("HTTPS certificates aren't enabled for your tailnet");
+        expect(out).toContain("Fix: turn on MagicDNS and HTTPS Certificates at");
+        expect(out).toContain("https://login.tailscale.com/admin/dns");
+        expect(out).toContain("--no-tailscale-https");
+    });
+    it("handles a reason without a fix link", () => {
+        const out = renderServeBanner("1", rows, "all ports in use");
+        expect(out).toContain("all ports in use");
+        expect(out).not.toContain("Fix:");
+    });
+});

package/dist/commands/serve.d.ts

@@ -59,6 +59,18 @@ export declare function resolvePreviewOverrides(args: readonly string[], env?: N
  * processes keep working. Exported for the defense-in-depth tests (#0096).
  */
 export declare function directServeBlockedByAgent(env?: NodeJS.ProcessEnv): boolean;
+export interface BannerRow {
+    label: string;
+    /** May contain ANSI codes. */
+    value: string;
+}
+/**
+ * The startup banner: a title line with the running version, an aligned
+ * label/value table, and — when Tailscale HTTPS could not be set up — a
+ * highlighted warning block that separates the problem from its fix. Pure
+ * (returns a string) so tests can assert on it with colors off.
+ */
+export declare function renderServeBanner(version: string, rows: readonly BannerRow[], httpsWarning?: string): string;
 export declare function cmdServe(args: string[], opts?: {
     onShutdown?: () => void;
     onReady?: (url: string) => void;

package/dist/commands/serve.js

@@ -8,7 +8,8 @@ import { PREVIEW_REQUEST_SIGNAL } from "../server/agents.js";
 import { isBun } from "../core/runtime.js";
 import { findRepoRoot } from "../core/config.js";
 import { c, statusColor } from "../cli/colors.js";
-import { detectTailscaleIPv4 } from "../core/tailscale.js";
+import { readVersion } from "../core/version.js";
+import { detectTailscaleIPv4, ensureTailscaleHttps } from "../core/tailscale.js";
 /**
  * The OS-visible process title for a `repoos serve` instance:
  * `repoos-<project>`, where `<project>` is the managed root's directory name.
@@ -109,6 +110,39 @@ export function resolvePreviewOverrides(args, env = process.env) {
 export function directServeBlockedByAgent(env = process.env) {
     return env.REPOOS_AGENT === "1" && env.REPOOS_PREVIEW_CHILD !== "1" && env.REPOOS_RELOAD !== "1";
 }
+/**
+ * The startup banner: a title line with the running version, an aligned
+ * label/value table, and — when Tailscale HTTPS could not be set up — a
+ * highlighted warning block that separates the problem from its fix. Pure
+ * (returns a string) so tests can assert on it with colors off.
+ */
+export function renderServeBanner(version, rows, httpsWarning) {
+    const width = Math.max(...rows.map((r) => r.label.length));
+    const out = [
+        "",
+        `  ${c.bold(c.cyan("◆ RepoOS"))} ${c.dim("v" + version)}  ${c.green("● running")}`,
+        "",
+    ];
+    for (const r of rows)
+        out.push(`  ${c.dim(r.label.padEnd(width))}  ${r.value}`);
+    if (httpsWarning) {
+        // Reasons read "<problem> — <fix> <url>": put the problem, the fix and the
+        // link on their own lines so the actionable part isn't buried.
+        const [problem, ...rest] = httpsWarning.split(" — ");
+        const fixText = rest.join(" — ");
+        const url = /https?:\/\/\S+/.exec(fixText)?.[0];
+        const fix = (url ? fixText.replace(url, "") : fixText).replace(/\s*\bat\s*$/, "").trim();
+        out.push("", `  ${c.yellow("▲")} ${c.bold(c.yellow("Tailscale HTTPS unavailable"))}`);
+        out.push(`    ${c.dim(problem ?? "")}`);
+        if (fix)
+            out.push(`    ${c.bold("Fix:")} ${fix}${url ? c.dim(" at") : ""}`);
+        if (url)
+            out.push(`         ${c.cyan(url)}`);
+        out.push(`    ${c.dim("or pass")} ${c.cyan("--no-tailscale-https")} ${c.dim("to silence this")}`);
+    }
+    out.push("", c.dim("  press ^C to stop"), "");
+    return out.join("\n");
+}
 export async function cmdServe(args, opts = {}) {
     // Defense in depth (#0096): a managed agent process must never start its own
     // `repoos serve`. An agent that ignores the mission and runs `repoos serve`
@@ -128,6 +162,7 @@ export async function cmdServe(args, opts = {}) {
     let port;
     let explicitHost;
     let quiet = false;
+    let tailscaleHttps = true;
     for (let i = 0; i < args.length; i++) {
         if (args[i] === "--port" || args[i] === "-p")
             port = Number(args[++i]);
@@ -135,6 +170,8 @@ export async function cmdServe(args, opts = {}) {
             explicitHost = args[++i];
         else if (args[i] === "--quiet" || args[i] === "-q")
             quiet = true;
+        else if (args[i] === "--no-tailscale-https")
+            tailscaleHttps = false;
     }
     // Preview-only config overlay (#0464). A managed preview child
     // (REPOOS_PREVIEW_CHILD=1, set by PreviewManager) applies the repo's
@@ -171,32 +208,46 @@ export async function cmdServe(args, opts = {}) {
         return;
     }
     const snap = handle.index.snapshot();
-    console.log(c.bold(c.cyan("\n  RepoOS server")) + c.dim("  ·  ") + c.bold(handle.url));
-    console.log(c.dim("  open ") + c.cyan(handle.url) + c.dim(" in your browser for the UI"));
-    console.log(c.dim("  watching ") +
-        snap.taskCount +
-        c.dim(" tasks  ·  SSE stream at ") +
-        c.cyan(handle.url + "/api/events"));
+    const rt = isBun()
+        ? `Bun ${process.versions.bun ?? ""}`.trim()
+        : `Node ${process.versions.node}`;
+    const rows = [
+        { label: "Local", value: c.cyan(c.bold(handle.url)) },
+        { label: "Events", value: c.cyan(handle.url + "/api/events") + c.dim("  (SSE)") },
+        { label: "Watching", value: `${snap.taskCount} tasks` },
+        { label: "Runtime", value: rt },
+    ];
     // 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(", ")));
+        rows.push({ label: "Preview", value: c.yellow(handle.previewOverrides.join(", ")) });
     }
-    const rt = isBun()
-        ? `Bun ${process.versions.bun ?? ""}`.trim()
-        : `Node ${process.versions.node}`;
-    console.log(c.dim("  runtime ") + rt);
-    console.log(c.dim("  api: ") + c.dim("/api/tasks  /api/tasks/:id  /api/counts  /api/index  /api/docs"));
     if (tailscaleDetected) {
-        console.log(c.dim("  Tailscale detected — listening on all interfaces (") +
-            c.cyan("0.0.0.0") +
-            c.dim("), reachable from other Tailscale devices at ") +
-            c.cyan(`http://${tailscaleIP}:${handle.port}`) +
-            c.dim(". Use ") +
-            c.cyan("--host 127.0.0.1") +
-            c.dim(" to restrict to localhost only."));
+        rows.push({
+            label: "Tailnet",
+            value: c.cyan(`http://${tailscaleIP}:${handle.port}`) +
+                c.dim("  (all interfaces; ") +
+                c.cyan("--host 127.0.0.1") +
+                c.dim(" to restrict)"),
+        });
+    }
+    // HTTPS for tailnet devices (a plain-http IP isn't a secure context, so
+    // crypto.randomUUID etc. are missing). Skipped for managed previews, which
+    // must not touch the machine's `tailscale serve` config.
+    let httpsWarning;
+    if (tailscaleDetected && tailscaleHttps && process.env.REPOOS_PREVIEW_CHILD !== "1") {
+        const https = await ensureTailscaleHttps(handle.port);
+        if (https.url) {
+            rows.push({
+                label: "Tailnet HTTPS",
+                value: c.green(c.bold(https.url)) + c.dim("  (secure context)"),
+            });
+        }
+        else if (https.reason) {
+            httpsWarning = https.reason;
+        }
     }
-    console.log(c.dim("  press ^C to stop\n"));
+    console.log(renderServeBanner(readVersion(), rows, httpsWarning));
     // Fires only now that the server is actually listening (handle.url is a
     // live, bound address) — a caller opening a browser tab any earlier races
     // the server's own startup and shows connection errors until a manual