@pome-sh/cli 0.5.0 → 0.7.0

package/dist/src/cli/main.js

@@ -7,8 +7,8 @@ import { basename, dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { readLatestRun, readMetaSummary, } from "../recorder/artifacts.js";
 import { LEGACY_EVENTS_MESSAGE, computeTraceHealth, readEventsJsonl, renderEvents, renderTraceHealth, } from "../recorder/inspect.js";
-import { runScenario } from "../runner/runScenario.js";
-import { runScenarioHosted } from "../runner/runScenarioHosted.js";
+import { runTask } from "../runner/runTask.js";
+import { runTaskHosted } from "../runner/runTaskHosted.js";
 import { effectiveTrialCount, parseTrialsFlag } from "../runner/trialCount.js";
 import { runScoreLine, scoreStatus } from "../hosted/evalResultView.js";
 import { HostedUsageError, exitCodeFor } from "../hosted/errors.js";
@@ -16,10 +16,10 @@ import { resolveCredentials, clearLocalCredentials } from "./credentials.js";
 import { loginWithClerk } from "./login.js";
 import { runDocsCommand } from "./docs.js";
 import { runCompileSeeds } from "./compile-seeds.js";
-import { runScenariosCommand } from "./scenarios.js";
+import { runTasksCommand } from "./tasks.js";
 import { runEvalCommand } from "./eval.js";
 import { copyAnnounceLine, ensureDefaultTask, runYoursFrameLines, trialsPinFallbackLine, } from "./default-task.js";
-import { findTwin, runnableScenarios, } from "./scenarios-catalog.js";
+import { findTwin, runnableTasks, } from "./tasks-catalog.js";
 import { friendlyHostedError, runSessionCreate, runSessionList, runSessionStop, } from "./session.js";
 import { normalizeRegisterTwins, runRegisterAgent } from "./register.js";
 import { resolvePackageRoot } from "./resolve-package-root.js";
@@ -30,10 +30,11 @@ import { MANIFEST_JSON, readManifest, writeManifest, } from "./project-config.js
 import { createGitHubCloneApp } from "../twin/githubCloneAdapter.js";
 import { buildFixPrompt, buildGroupFixPrompt, } from "../fix-prompt/index.js";
 import { discoverRunSet, loadTrialEvents, } from "../hosted/evalResultCache.js";
-import { parseScenarioFile } from "../scenario/parseScenario.js";
+import { parseTaskFile } from "../task/parseTask.js";
 const PACKAGE_VERSION = readPackageVersion();
 const SESSION_CREATE_FORMATS = new Set(["text", "json", "env"]);
-const DEFAULT_AGENT_COMMAND = "npx tsx examples/agents/scripted-triage-agent.ts";
+const DEFAULT_AGENT_FILE = "examples/agents/scripted-triage-agent.ts";
+const DEFAULT_AGENT_COMMAND = `npx tsx ${DEFAULT_AGENT_FILE}`;
 const MANIFEST_SCHEMA_URL = "https://pome.sh/schemas/v1/pome.json";
 function readPackageVersion() {
     try {
@@ -67,6 +68,8 @@ export function createProgram() {
         .command("init")
         .description("Create starter Pome config and folders")
         .option("--sdk <name>", "Scaffold for a specific agent SDK (claude | claude-managed). Adds the SDK-specific example file and pre-fills agent.framework so the dashboard badges runs correctly.")
+        .option("--bare", "Write only the manifest — skip the starter task library and sample agents. Auto-selected when the current directory already has a package.json (the bring-your-own-agent case).")
+        .option("--starter", "Force the full starter library even in an existing project.")
         .action(async (opts) => {
         const sdk = opts.sdk?.trim();
         if (sdk !== undefined &&
@@ -81,23 +84,54 @@ export function createProgram() {
             process.exitCode = 2;
             return;
         }
-        await mkdir("scenarios", { recursive: true });
-        await mkdir("examples/agents", { recursive: true });
-        await mkdir("runs", { recursive: true });
-        await copyStarterFiles();
-        let command = DEFAULT_AGENT_COMMAND;
+        if (opts.bare && opts.starter) {
+            console.error("Pass at most one of --bare / --starter.");
+            process.exitCode = 2;
+            return;
+        }
+        // F-904 — a directory that already has a package.json is the "bring your
+        // own agent" case: scaffold only the manifest, never the starter library
+        // (a 2026-07-24 cold walk dumped 28 untracked files into a real project).
+        // --starter / --bare override the auto-decision in either direction.
+        const looksLikeExistingProject = existsSync(join(process.cwd(), "package.json"));
+        const bare = opts.starter
+            ? false
+            : Boolean(opts.bare) || looksLikeExistingProject;
+        if (!bare) {
+            await mkdir("tasks", { recursive: true });
+            await mkdir("examples/agents", { recursive: true });
+            await mkdir("runs", { recursive: true });
+            await copyStarterFiles();
+        }
+        // Bare mode omits `command`: the BYO user launches their own agent, so a
+        // default pointer at an unscaffolded examples/agents/... file would be a
+        // broken instruction. --sdk still writes a real file and sets command.
+        let command = bare ? undefined : DEFAULT_AGENT_COMMAND;
         let framework;
-        let postInitMessage = "Pome initialized.\n" +
-            "Next steps:\n" +
-            "  1. pome login                    # one-time, opens the dashboard to sign in\n" +
-            "  2. pome register agent <name>    # scopes runs to this project (writes agent.slug to pome.json)\n" +
-            "  3. pome run scenarios/01-bug-happy-path.md\n" +
-            "\n" +
-            "Optional follow-ups:\n" +
-            "  - pome init --sdk claude         # scaffold a Claude Agent SDK starter\n" +
-            "  - pome scenarios stripe --copy   # add Stripe payment tasks when needed\n" +
-            "\n" +
-            "See `pome docs getting-started` for a narrative walkthrough.";
+        let postInitMessage = bare
+            ? "Pome initialized (existing project — starter library skipped).\n" +
+                "Next steps:\n" +
+                '  1. Set "command" in pome.json to your agent\'s launch command\n' +
+                "  2. pome login                    # one-time, opens the dashboard to sign in\n" +
+                "  3. pome register agent <name>    # scopes runs to this project (writes agent.slug to pome.json)\n" +
+                "  4. pome run <your-task>.md\n" +
+                "\n" +
+                "Optional follow-ups:\n" +
+                "  - pome tasks github --copy       # drop the starter task library into tasks/\n" +
+                "  - pome init --sdk claude         # scaffold a Claude Agent SDK starter\n" +
+                "\n" +
+                "See `pome docs getting-started` for a narrative walkthrough."
+            : "Pome initialized.\n" +
+                "Next steps:\n" +
+                "  1. pome login                    # one-time, opens the dashboard to sign in\n" +
+                "  2. pome register agent <name>    # scopes runs to this project (writes agent.slug to pome.json)\n" +
+                "  3. pome run tasks/01-bug-happy-path.md\n" +
+                "\n" +
+                "Optional follow-ups:\n" +
+                "  - pome init --sdk claude         # scaffold a Claude Agent SDK starter\n" +
+                "  - pome tasks stripe --copy       # add Stripe payment tasks when needed\n" +
+                "\n" +
+                "See `pome docs getting-started` for a narrative walkthrough.";
         if (sdk) {
             const scaffold = await writeSdkScaffold(sdk);
             command = scaffold.agentCommand;
@@ -106,6 +140,10 @@ export function createProgram() {
                 `Pome initialized with --sdk ${sdk}. Scaffolded ${scaffold.exampleAgentRelativePath}.\n` +
                     scaffold.postInstallHint;
         }
+        // Point the manifest at an existing task directory so bare `pome run`
+        // (F-865) resolves it. The starter path always creates tasks/; bare mode
+        // only claims it when the user already keeps their tasks there.
+        const tasksDir = !bare || (await hasMarkdownTasks("tasks")) ? "tasks" : undefined;
         // The manifest requires `agent.slug` (F-804). `pome init` runs before
         // `pome register`, so seed a portable slug derived from the directory
         // name; register later overwrites it with the server-canonical slug.
@@ -115,13 +153,17 @@ export function createProgram() {
             const agent = { slug };
             if (framework)
                 agent.framework = framework;
-            await writeManifest(join(process.cwd(), MANIFEST_JSON), "json", {
+            const manifest = {
                 $schema: MANIFEST_SCHEMA_URL,
                 agent,
-                command,
-                artifacts_dir: "runs",
-                pass_threshold: 100,
-            });
+            };
+            if (command)
+                manifest.command = command;
+            if (tasksDir)
+                manifest.tasks = tasksDir;
+            manifest.artifacts_dir = "runs";
+            manifest.pass_threshold = 100;
+            await writeManifest(join(process.cwd(), MANIFEST_JSON), "json", manifest);
         }
         else if (sdk) {
             const priorAgent = typeof existing.raw.agent === "object" && existing.raw.agent !== null
@@ -177,23 +219,35 @@ export function createProgram() {
         .action(async (topic, opts) => {
         await runDocsCommand(topic, { site: opts.site, urlOnly: Boolean(opts.url) });
     });
-    program
-        .command("scenarios")
-        .argument("[twin]", "Twin id (e.g. github). Omit to list available twins.")
-        .option("--copy", "Copy the twin's runnable tasks into the local project.", false)
-        .option("--force", "With --copy, overwrite existing files in the destination.", false)
-        .option("--dest <dir>", "With --copy, write into this directory instead of ./scenarios/.")
-        .description("Browse the bundled task library (or copy a twin's tasks into the local project)")
-        .action(async (twin, opts) => {
-        await runScenariosCommand(twin, {
-            copy: opts.copy,
-            force: opts.force,
-            dest: opts.dest,
+    const registerTasksCommand = (name, hidden) => {
+        const cmd = program
+            .command(name, { hidden })
+            .argument("[twin]", "Twin id (e.g. github). Omit to list available twins.")
+            .option("--copy", "Copy the twin's runnable tasks into the local project.", false)
+            .option("--force", "With --copy, overwrite existing files in the destination.", false)
+            .option("--dest <dir>", "With --copy, write into this directory instead of ./tasks/.")
+            .description("Browse the bundled task library (or copy a twin's tasks into the local project)")
+            .action(async (twin, opts) => {
+            // F-892 — `pome scenarios` was renamed to `pome tasks`. The old name
+            // stays as a hidden, still-working alias with a one-line pointer so
+            // existing muscle memory / scripts don't break; help only shows
+            // `pome tasks`.
+            if (hidden) {
+                console.error("`pome scenarios` was renamed to `pome tasks` — running it for you. Update your scripts; the old name will be removed in a future release.");
+            }
+            await runTasksCommand(twin, {
+                copy: opts.copy,
+                force: opts.force,
+                dest: opts.dest,
+            });
         });
-    });
+        return cmd;
+    };
+    registerTasksCommand("tasks", false);
+    registerTasksCommand("scenarios", true);
     program
         .command("compile-seeds")
-        .argument("[target]", "Task .md file or directory (defaults to ./scenarios)")
+        .argument("[target]", "Task .md file or directory (defaults to ./tasks)")
         .option("--force", "Recompile even if the sidecar's source hash matches", false)
         .option("--hosted", "Compile via the Pome control plane instead of calling Anthropic directly (uses your Pome API key; no ANTHROPIC_API_KEY needed)", false)
         .option("--api-url <url>", "Control-plane base URL (only relevant with --hosted).", process.env.POME_API_URL ?? DEFAULT_CONTROL_PLANE_URL)
@@ -224,6 +278,7 @@ export function createProgram() {
         try {
             await runRegisterAgent({
                 apiBaseUrl: opts.apiUrl,
+                dashboardBaseUrl: process.env.POME_DASHBOARD_URL ?? DEFAULT_DASHBOARD_URL,
                 name,
                 force: opts.force,
                 twins: normalizeRegisterTwins(opts.twins),
@@ -316,7 +371,7 @@ export function createProgram() {
     });
     program
         .command("run")
-        .argument("[path]", 'Task markdown file or directory. Omit to run the demo task ("that was ours, run yours"): scenarios/first-run-demo.md is dropped into your project on first use with runs: 5 pinned.')
+        .argument("[path]", 'Task markdown file or directory. Omit to run the demo task ("that was ours, run yours"): tasks/first-run-demo.md is dropped into your project on first use with runs: 5 pinned.')
         .option("--agent <command>", "Agent command to run")
         .option("-n, --trials <count>", "FDRS-636: run <count> isolated trials of the task as ONE trial group (integer 1-20; hosted only). " +
         "Default is the task config's `runs` field (capped at 20). k>1 mints sessions with a shared group id up to your " +
@@ -334,7 +389,7 @@ export function createProgram() {
         .option("--agent-version <version>", "Override the manifest's agent.version for this run (stamped on the session/run).")
         .option("--no-capture", "Self-host only: skip spawning the capture-server child and don't inject HTTP_PROXY/HTTPS_PROXY into the agent. Used by the CI overhead gate (FDRS-405) to baseline proxy-on-vs-off latency. No-op on hosted runs.")
         .option("--local", "Self-host: run against an in-process twin and CAPTURE a raw trace only (an audit log — no score, no verdict, no judge). A verdict comes from the cloud: run `pome eval <run-dir>` on the captured trace, or `pome login` and run against Pome cloud.")
-        .description('Run one or more Pome tasks. With no path, runs the demo task (scenarios/first-run-demo.md, copied into your project on first use — "that was ours, run yours"). Refuses to start if the doctor wiring checks fail (see `pome doctor`); there is no --force.')
+        .description('Run one or more Pome tasks. With no path, runs the demo task (tasks/first-run-demo.md, copied into your project on first use — "that was ours, run yours"). Refuses to start if the doctor wiring checks fail (see `pome doctor`); there is no --force.')
         .action(async (target, options) => {
         // F0-5 — `pome run`'s pre-flight (resolving files, reading config,
         // resolving credentials) used to propagate plain `Error`s to
@@ -357,31 +412,50 @@ export function createProgram() {
                 return;
             }
         }
-        // FDRS-645 — "run yours": bare `pome run` defaults to the demo task
-        // via a user-visible copy (scenarios/first-run-demo.md, dropped on
-        // first use; its Config pins runs: 5 so an explicit -n still wins).
-        // The moment-05 frame prints later, once the doctor + credential
-        // gates have passed.
+        // Read the manifest once — both bare-run task resolution (F-865) and
+        // the agent command below consume it.
+        const manifestRead = await readManifest(process.cwd()).catch(() => null);
+        // FDRS-645 / F-865 — bare `pome run` (no path) resolves its default:
+        //   - a MIGRATED project (manifest with a `tasks` key) runs that whole
+        //     declared directory, exactly like `pome run <that-dir>`: no demo
+        //     drop, no "run yours" frame, each file at its own `runs`/-n;
+        //   - an UN-MIGRATED project (no manifest / no `tasks` key) keeps the
+        //     "run yours" demo default — a user-visible copy at
+        //     tasks/first-run-demo.md (dropped on first use; its Config pins
+        //     runs: 5 so an explicit -n still wins). The moment-05 frame prints
+        //     later, once the doctor + credential gates have passed.
         let defaultTask = null;
+        let bareViaManifestTasks = false;
         if (target === undefined) {
-            try {
-                defaultTask = await ensureDefaultTask();
+            const declaredTasks = manifestRead?.manifest.tasks;
+            if (manifestRead && declaredTasks) {
+                // Resolve the declared dir relative to the manifest, not cwd — the
+                // manifest can be discovered up-tree. A declared-but-missing dir
+                // surfaces as taskFiles' usage error below (exit 5); we never
+                // silently fall back to the demo drop once intent is declared.
+                target = resolve(dirname(manifestRead.path), declaredTasks);
+                bareViaManifestTasks = true;
             }
-            catch (err) {
-                console.error(err instanceof Error ? err.message : String(err));
-                process.exitCode = exitCodeFor(err);
-                return;
+            else {
+                try {
+                    defaultTask = await ensureDefaultTask();
+                }
+                catch (err) {
+                    console.error(err instanceof Error ? err.message : String(err));
+                    process.exitCode = exitCodeFor(err);
+                    return;
+                }
+                if (defaultTask.copied)
+                    console.error(copyAnnounceLine(defaultTask));
+                if (!defaultTask.trialsApplied)
+                    console.error(trialsPinFallbackLine());
+                target = defaultTask.path;
             }
-            if (defaultTask.copied)
-                console.error(copyAnnounceLine(defaultTask));
-            if (!defaultTask.trialsApplied)
-                console.error(trialsPinFallbackLine());
-            target = defaultTask.path;
         }
         let files;
         let hostedCreds;
         try {
-            files = await scenarioFiles(target);
+            files = await taskFiles(target);
         }
         catch (err) {
             const code = exitCodeFor(err);
@@ -389,9 +463,31 @@ export function createProgram() {
             process.exitCode = code;
             return;
         }
-        const manifestRead = await readManifest(process.cwd()).catch(() => null);
+        // F-865 — make a manifest-driven bare run legible: name where the set
+        // came from, and never let an empty declared dir no-op silently.
+        if (bareViaManifestTasks) {
+            const manifestFile = basename(manifestRead.path);
+            const declared = manifestRead.manifest.tasks;
+            if (files.length === 0) {
+                console.error(`no task .md files found in ${declared}/ (declared in ${manifestFile}) — add tasks or copy some with \`pome tasks <twin> --copy\`.`);
+            }
+            else {
+                console.error(`resolved ${files.length} task(s) from ${manifestFile} (tasks: "${declared}")`);
+            }
+        }
         const configCommand = manifestRead?.manifest.command;
-        const agentCommand = options.agent ?? configCommand ?? DEFAULT_AGENT_COMMAND;
+        const resolvedCommand = options.agent ?? configCommand;
+        // Bare `pome init` (existing project) writes no `command`. Don't
+        // silently fall back to the starter scaffold it never created — a
+        // spawn of a missing file gives a cryptic error. Use the default only
+        // when that file actually exists; otherwise fail with guidance.
+        if (resolvedCommand === undefined && !existsSync(DEFAULT_AGENT_FILE)) {
+            console.error('No agent command configured. Set "command" in pome.json to your ' +
+                'agent\'s launch command, or pass --agent "<command>".');
+            process.exitCode = 2;
+            return;
+        }
+        const agentCommand = resolvedCommand ?? DEFAULT_AGENT_COMMAND;
         let worstExit = 0;
         // Hosted is the default. Self-host runs against an in-process twin via
         // `--local` (documented) or POME_LOCAL=1 (an internal escape hatch).
@@ -466,8 +562,8 @@ export function createProgram() {
                     // config's `runs` field (both capped at 20). k>1 takes the
                     // trial-group path; k=1 stays EXACTLY the single-run path
                     // below (no group is ever stamped for it).
-                    const scenarioForRuns = await parseScenarioFile(file);
-                    const k = effectiveTrialCount(trialsFlag, scenarioForRuns.config.runs);
+                    const taskForRuns = await parseTaskFile(file);
+                    const k = effectiveTrialCount(trialsFlag, taskForRuns.config.runs);
                     if (k > 1) {
                         const { runTrialGroup } = await import("../runner/runTrialGroup.js");
                         // FDRS-644 — the literal re-run command the fix handoff
@@ -482,7 +578,7 @@ export function createProgram() {
                                 ? fileForRerun
                                 : file} -n ${k}`;
                         const groupResult = await runTrialGroup({
-                            scenarioPath: file,
+                            taskPath: file,
                             agentCommand,
                             agentCommandSource: options.agent
                                 ? "--agent"
@@ -505,8 +601,8 @@ export function createProgram() {
                         }
                         continue;
                     }
-                    const result = await runScenarioHosted({
-                        scenarioPath: file,
+                    const result = await runTaskHosted({
+                        taskPath: file,
                         agentCommand,
                         artifactsDir: options.artifactsDir,
                         hosted: { baseUrl: hostedCreds.apiBaseUrl, apiKey: hostedCreds.apiKey },
@@ -535,8 +631,8 @@ export function createProgram() {
                 // no score, no verdict, no judge. Let exceptions (file-not-found,
                 // parse errors, agent failures) propagate to Commander's top-level
                 // handler.
-                const result = await runScenario({
-                    scenarioPath: file,
+                const result = await runTask({
+                    taskPath: file,
                     agentCommand,
                     artifactsDir: options.artifactsDir,
                     // Commander negates --no-* flags: `--no-capture` → `capture: false`.
@@ -589,7 +685,7 @@ export function createProgram() {
     });
     // Hidden: the bundled demo agent `pome demo` spawns as its trial child
     // through the real capture path (FDRS-643). Reads the POME_* env contract
-    // injected by runScenario plus POME_DEMO_* gateway coordinates.
+    // injected by runTask plus POME_DEMO_* gateway coordinates.
     program
         .command("demo-agent", { hidden: true })
         .description("Internal: the bundled demo agent process (spawned by `pome demo`).")
@@ -601,12 +697,12 @@ export function createProgram() {
     });
     program
         .command("doctor")
-        .description("Check the agent↔twin wiring: pome.json (or pome.yaml) present + valid, twin reachable, requests routed to the twin (not a hardcoded production host), egress floor active. On failure prints one named cause (file:line where knowable) + one concrete fix and exits non-zero.")
+        .description("Check the agent↔twin wiring: pome.json (or pome.yaml) present + valid, the local twin boots + serves, requests routed to the twin (not a hardcoded production host), egress floor active. On failure prints one named cause (file:line where knowable) + one concrete fix and exits non-zero.")
         .action(async () => {
         const { runDoctorChecks } = await import("../doctor/checks.js");
         const { renderDoctorReport } = await import("../doctor/render.js");
         const report = await runDoctorChecks();
-        for (const line of renderDoctorReport(report))
+        for (const line of renderDoctorReport(report, { passNote: true }))
             console.error(line);
         if (!report.ok)
             process.exitCode = 1;
@@ -655,7 +751,7 @@ export function createProgram() {
         else {
             const health = computeTraceHealth({
                 events: eventsResult.events,
-                scenarioUsesTwin: meta.twins.length > 0,
+                taskUsesTwin: meta.twins.length > 0,
             });
             for (const line of renderTraceHealth(health))
                 console.log(line);
@@ -672,18 +768,18 @@ export function createProgram() {
         .argument("[target]", "Artifacts root or a trial run dir (default: runs). Legacy form: a path to events.jsonl — then <task> is required.")
         .argument("[task]", "Path to the task .md file (only with an events.jsonl target)")
         .description("Assemble a paste-into-IDE fix prompt (no LLM call, no network). With no args, reads the latest FAILED run set under ./runs: the persisted cloud verdicts (verdict.json) become grouped failure signatures over the raw traces, in one prompt. Point it at a trial run dir to target that set, or use the legacy `<events.jsonl> <task.md>` form for a single trace.")
-        .action(async (target, scenarioArg) => {
+        .action(async (target, taskArg) => {
         // Legacy 2-arg form: <events.jsonl> <scenario.md> — unchanged
         // (CAPTURE-ONLY, FDRS-657: raw trace + declared criteria, no verdict).
         if (target !== undefined && target.endsWith(".jsonl")) {
-            if (!scenarioArg) {
+            if (!taskArg) {
                 console.error("The events.jsonl form needs the task file: pome fix-prompt <events.jsonl> <task.md>");
                 process.exitCode = 5;
                 return;
             }
             const [eventsRaw, scenario] = await Promise.all([
                 readFile(resolve(target), "utf8"),
-                parseScenarioFile(resolve(scenarioArg)),
+                parseTaskFile(resolve(taskArg)),
             ]);
             const events = eventsRaw
                 .split("\n")
@@ -693,7 +789,7 @@ export function createProgram() {
             console.log(buildFixPrompt({ events, scenario }));
             return;
         }
-        if (scenarioArg !== undefined) {
+        if (taskArg !== undefined) {
             console.error("The second argument only applies to the events.jsonl form: pome fix-prompt <events.jsonl> <task.md>");
             process.exitCode = 5;
             return;
@@ -716,7 +812,7 @@ export function createProgram() {
         const set = discovery.set;
         let scenario = null;
         try {
-            scenario = await parseScenarioFile(resolve(set.scenarioPath));
+            scenario = await parseTaskFile(resolve(set.taskPath));
         }
         catch {
             // Task file moved/edited since the run — the prompt degrades to the
@@ -877,7 +973,7 @@ const SUPPORTED_GMAIL_ENDPOINTS = [
     "GET /gmail/v1/users/:userId/settings/sendAs/:email",
     "POST /upload/gmail/v1/users/:userId/{messages,drafts} (media|multipart)",
 ];
-async function scenarioFiles(target) {
+async function taskFiles(target) {
     const resolved = resolve(target);
     // F0-5a — surface bad-input paths as `HostedUsageError` so the top-level
     // exit-code mapper returns the documented exit 5 ("usage error") instead
@@ -895,12 +991,27 @@ async function scenarioFiles(target) {
         .sort()
         .map((entry) => join(resolved, entry));
 }
+// F-904 — does the cwd already carry a task directory worth recording in the
+// manifest? A directory named `dir` counts only when it holds at least one
+// `.md` (an empty scaffold dir is not a task set).
+async function hasMarkdownTasks(dir) {
+    const abs = join(process.cwd(), dir);
+    if (!existsSync(abs))
+        return false;
+    try {
+        const entries = await readdir(abs);
+        return entries.some((f) => f.toLowerCase().endsWith(".md"));
+    }
+    catch {
+        return false;
+    }
+}
 async function copyStarterFiles() {
     const packageRoot = resolvePackageRoot(import.meta.url);
     if (!packageRoot)
         return;
     await Promise.all([
-        copyStarterScenarios(packageRoot),
+        copyStarterTasks(packageRoot),
         copyIfPresent(join(packageRoot, "examples", "agents"), join("examples", "agents")),
     ]);
 }
@@ -913,20 +1024,20 @@ async function copyIfPresent(source, target) {
         errorOnExist: false,
     });
 }
-async function copyStarterScenarios(packageRoot) {
-    const scenarioDir = join(packageRoot, "scenarios");
-    if (!existsSync(scenarioDir))
+async function copyStarterTasks(packageRoot) {
+    const taskDir = join(packageRoot, "tasks");
+    if (!existsSync(taskDir))
         return;
     const starterTwin = findTwin("github");
-    const starterScenarios = starterTwin
-        ? runnableScenarios(starterTwin).map((s) => s.filename)
+    const starterTasks = starterTwin
+        ? runnableTasks(starterTwin).map((t) => t.filename)
         : [];
-    await mkdir("scenarios", { recursive: true });
-    await Promise.all(starterScenarios.flatMap((file) => {
+    await mkdir("tasks", { recursive: true });
+    await Promise.all(starterTasks.flatMap((file) => {
         const sidecar = file.replace(/\.md$/i, ".seed.json");
         return [
-            copyIfPresent(join(scenarioDir, file), join("scenarios", file)),
-            copyIfPresent(join(scenarioDir, sidecar), join("scenarios", sidecar)),
+            copyIfPresent(join(taskDir, file), join("tasks", file)),
+            copyIfPresent(join(taskDir, sidecar), join("tasks", sidecar)),
         ];
     }));
 }

package/dist/src/cli/register.d.ts

@@ -2,6 +2,10 @@ import { type InteractiveSeams } from "./agent-resolver.js";
 import { friendlyHostedError } from "./session.js";
 interface RegisterAgentOptions extends InteractiveSeams {
     apiBaseUrl: string;
+    /** Dashboard base for the post-register deep link (POME_DASHBOARD_URL /
+     *  DEFAULT_DASHBOARD_URL — resolved at the main.ts boundary, like the runner's
+     *  reliability-page handoff). */
+    dashboardBaseUrl: string;
     name: string;
     force: boolean;
     twins?: string[];

package/dist/src/cli/register.js

@@ -159,6 +159,11 @@ export async function runRegisterAgent(opts) {
     else if (opts.twins && opts.twins.length > 0) {
         console.error("Enabled services: not reported by this pome cloud (older control plane) — twin scoping may not have taken effect.");
     }
+    // Deep-link the registered agent's dashboard page. `/agents/<slug>` is the
+    // same IA the runner's reliability handoff relies on (/agents/<slug>/tasks/…),
+    // so this lands on the agent, not a generic root.
+    const base = opts.dashboardBaseUrl.replace(/\/$/, "");
+    console.error(`Dashboard: ${base}/agents/${encodeURIComponent(agent.slug)}`);
 }
 function stripControlCharacters(value) {
     return value.replace(/[\u0000-\u001f\u007f]/g, "");

package/dist/src/cli/session.js

@@ -129,7 +129,7 @@ export async function runSessionCreate(opts) {
     });
     const session = await client.createSession({
         twins,
-        scenarioSource: "# ..\n",
+        taskSource: "# ..\n",
         idempotencyKey: randomUUID(),
         agentId: identity.agentId,
         agentVersion: identity.agentVersion,

package/dist/src/cli/tasks-catalog.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Catalog of tasks bundled with the CLI, grouped by twin.
+ *
+ * Single source of truth for `pome tasks` (browse + copy). `pome init`
+ * uses the GitHub twin entries from this catalog as its starter scaffold while
+ * Stripe/Slack tasks remain opt-in via `pome tasks <twin> --copy`.
+ *
+ * `runnable: false` marks a seed-only reference document (not a task
+ * to execute) — copy commands skip these.
+ */
+export interface CatalogTask {
+    filename: string;
+    title: string;
+    summary: string;
+    runnable: boolean;
+}
+export interface TaskTwin {
+    id: string;
+    label: string;
+    description: string;
+    tasks: CatalogTask[];
+}
+export declare const TASK_TWINS: TaskTwin[];
+export declare function findTwin(id: string): TaskTwin | null;
+export declare function runnableTasks(twin: TaskTwin): CatalogTask[];

package/dist/src/cli/{scenarios-catalog.js → tasks-catalog.js}

@@ -1,9 +1,9 @@
-export const SCENARIO_TWINS = [
+export const TASK_TWINS = [
     {
         id: "github",
         label: "GitHub twin",
         description: "Issue triage, labeling, PR review, and identity checks against a deterministic GitHub clone.",
-        scenarios: [
+        tasks: [
             {
                 filename: "00-default-seed.md",
                 title: "Default seed (reference)",
@@ -82,7 +82,7 @@ export const SCENARIO_TWINS = [
         id: "stripe",
         label: "Stripe twin",
         description: "Payments, refunds, events, and x402 flows against a deterministic Stripe clone.",
-        scenarios: [
+        tasks: [
             {
                 filename: "10-stripe-create-payment-intent.md",
                 title: "Create PaymentIntent",
@@ -125,7 +125,7 @@ export const SCENARIO_TWINS = [
         id: "slack",
         label: "Slack twin",
         description: "Channel summaries, DLP, and injection resistance against a deterministic Slack clone.",
-        scenarios: [
+        tasks: [
             {
                 filename: "20-slack-exfiltration.md",
                 title: "Secret exfiltration",
@@ -144,7 +144,7 @@ export const SCENARIO_TWINS = [
         id: "gmail",
         label: "Gmail twin",
         description: "Inbox triage, drafting, search, and label workflows against a deterministic Gmail clone.",
-        scenarios: [
+        tasks: [
             {
                 filename: "22-gmail-inbox-triage.md",
                 title: "Gmail inbox triage",
@@ -169,7 +169,7 @@ export const SCENARIO_TWINS = [
         id: "linear",
         label: "Linear twin",
         description: "Issue triage, comments, and project workflows against a deterministic Linear clone.",
-        scenarios: [
+        tasks: [
             {
                 filename: "24-linear-issue-triage.md",
                 title: "Linear issue triage",
@@ -189,8 +189,8 @@ export function findTwin(id) {
     const q = id.trim().toLowerCase();
     if (!q)
         return null;
-    return SCENARIO_TWINS.find((twin) => twin.id === q) ?? null;
+    return TASK_TWINS.find((twin) => twin.id === q) ?? null;
 }
-export function runnableScenarios(twin) {
-    return twin.scenarios.filter((s) => s.runnable);
+export function runnableTasks(twin) {
+    return twin.tasks.filter((t) => t.runnable);
 }

package/dist/src/cli/tasks.d.ts

@@ -0,0 +1,13 @@
+import { type TaskTwin } from "./tasks-catalog.js";
+export interface TasksCommandOptions {
+    copy?: boolean;
+    force?: boolean;
+    dest?: string;
+}
+export declare function runTasksCommand(twinArg: string | undefined, opts: TasksCommandOptions): Promise<void>;
+interface CopyOptions {
+    destDir: string;
+    force: boolean;
+}
+export declare function copyTwinTasks(twin: TaskTwin, opts: CopyOptions): Promise<void>;
+export {};