@pome-sh/cli 0.4.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,11 +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 { runSkillsInstall } from "./skills.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";
@@ -31,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 {
@@ -68,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 &&
@@ -82,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;
@@ -107,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.
@@ -116,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
@@ -141,19 +182,16 @@ export function createProgram() {
     });
     program
         .command("install")
-        .description("Wire this repo to pome with your own coding agent: checks auth (routes through pome login when needed), runs the wiring headless on your own Claude credentials, shows the full diff in this terminal, and applies it only on [y] — then verifies with pome doctor. --interactive hands off to a live agent session instead; no coding agent on PATH → prints manual wiring steps + a paste-into-any-agent prompt.")
-        .option("--interactive", "Hand off to an interactive agent session (approve edits in the agent's own UI) instead of the headless staged-diff flow.")
-        .option("--api-url <url>", "Control-plane base URL.", process.env.POME_API_URL ?? DEFAULT_CONTROL_PLANE_URL)
-        .option("--dashboard-url <url>", "App URL for Clerk sign-in (must serve /cli/login).", process.env.POME_DASHBOARD_URL ?? DEFAULT_DASHBOARD_URL)
-        .action(async (opts) => {
-        // Dynamic import mirrors the doctor/run commands: keep install's
-        // dependency graph out of every other command's startup path.
+        // F-893 — the Gen-1 agent-driven wiring is retired; this is a redirect to
+        // the Gen-2 path. allowUnknownOption + allowExcessArguments keep old
+        // invocations (`pome install --interactive`, `--api-url …`) landing on the
+        // redirect instead of erroring on a now-removed flag or stray operand.
+        .allowUnknownOption()
+        .allowExcessArguments()
+        .description("Retired (F-893). Prints the Gen-2 wiring path: `claude mcp add … pome` + `npx skills add pome-sh/digital-twins`, then the pome-intake / REST-launch preflight.")
+        .action(async () => {
         const { runInstall } = await import("./install.js");
-        await runInstall({
-            apiUrl: opts.apiUrl,
-            dashboardUrl: opts.dashboardUrl,
-            interactive: opts.interactive,
-        });
+        runInstall();
     });
     program
         .command("login")
@@ -181,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)
@@ -211,22 +261,9 @@ export function createProgram() {
         if (code !== 0)
             process.exitCode = code;
     });
-    const skills = program
-        .command("skills")
-        .description("Manage the bundled pome agent skills (/pome-setup, /pome-test)");
-    skills
-        .command("install")
-        .description("Install /pome-setup and /pome-test into ~/.claude/skills/ (symlinked to this pome install by default)")
-        .option("--copy", "Copy each skill instead of symlinking (CI, Windows without symlink permission)", false)
-        .option("--force", "Overwrite an existing install of the same skill", false)
-        .option("--dest <dir>", "Install into <dir> instead of ~/.claude/skills/ (testing and advanced users)")
-        .action(async (opts) => {
-        await runSkillsInstall({
-            copy: opts.copy,
-            force: opts.force,
-            dest: opts.dest,
-        });
-    });
+    // F-893 — `pome skills` / `pome skills install` retired. It only symlinked
+    // the two Gen-1 tombstone skills into ~/.claude/skills/; the Gen-2 coach set
+    // installs via `npx skills add pome-sh/digital-twins`.
     const register = program
         .command("register")
         .description("Register a cloud entity (agent, ...) and link this project to it");
@@ -241,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),
@@ -333,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 " +
@@ -351,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
@@ -374,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);
@@ -406,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).
@@ -483,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
@@ -499,7 +578,7 @@ export function createProgram() {
                                 ? fileForRerun
                                 : file} -n ${k}`;
                         const groupResult = await runTrialGroup({
-                            scenarioPath: file,
+                            taskPath: file,
                             agentCommand,
                             agentCommandSource: options.agent
                                 ? "--agent"
@@ -522,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 },
@@ -552,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`.
@@ -606,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`).")
@@ -618,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;
@@ -672,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);
@@ -689,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")
@@ -710,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;
@@ -733,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
@@ -894,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
@@ -912,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")),
     ]);
 }
@@ -930,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[];
@@ -11,26 +15,4 @@ interface RegisterAgentOptions extends InteractiveSeams {
 /** Normalize a `--twins github,slack` comma list to a validated twin array. */
 export declare function normalizeRegisterTwins(raw: string | undefined): string[] | undefined;
 export declare function runRegisterAgent(opts: RegisterAgentOptions): Promise<void>;
-export interface EnsureAgentRegisteredOptions extends InteractiveSeams {
-    apiBaseUrl: string;
-    /** Where to look for the manifest. Defaults to process.cwd(). */
-    cwd?: string;
-    /** Test seam — forwarded to resolveCredentials. */
-    credentialsPath?: string;
-}
-export type EnsureAgentRegisteredResult = {
-    status: "registered";
-    agentId: string;
-    agentSlug: string;
-} | {
-    status: "already-registered";
-    agentId: string;
-    agentSlug?: string;
-} | {
-    status: "no-config";
-};
-/** Idempotent registration for `pome install`: a repo already linked under the
- *  caller's team keeps its id (no network, no duplicate); a fresh repo registers
- *  under the manifest name (or the config directory's basename). */
-export declare function ensureAgentRegistered(opts: EnsureAgentRegisteredOptions): Promise<EnsureAgentRegisteredResult>;
 export { friendlyHostedError };