@opsee/cli 0.11.11 → 0.11.13

package/README.md

@@ -102,15 +102,33 @@ environment, so an app that reads the variable needs no placeholder at all. Vite
 kind: it ignores `PORT` and takes `--port`, and `--strictPort` makes it fail rather than drift to
 the next free port, which is the silent-corruption hazard AGENTS.md describes for two dev servers.
 
-`opsee init` writes the block once. `start` defaults to `commands.dev` (then `commands.start`),
-`gates.test` and `gates.lint` to `commands.test` and `commands.lint`, the readiness URL to
-`http://localhost:{port}/` and the variable to `PORT`; `typecheck` has no analyzer equivalent and
-is asked for or left out. On a terminal the four are prompted with those defaults; otherwise the
-defaults and the flags `--start`, `--readiness-url`, `--port-env`, `--typecheck` stand, and a repo
-where nothing says how to start the app gets a `skipped` line instead of a recipe. An existing
-`foreman` block, the user's or the analyzer's, is never rewritten: a re-run reports `unchanged`
-whatever the flags say, and a block that cannot serve as a recipe (no `start`, no
-`readiness_url`) is reported and kept. The YAML is spliced textually, the block appended in the
+`opsee init` writes the block once. `gates.test` and `gates.lint` default to `commands.test` and
+`commands.lint`; `start` is written only when `commands.dev` (then `commands.start`) or `--start`
+already says how to serve the app, and the readiness URL and the port variable travel with it.
+`typecheck` has no analyzer equivalent, so it is the one value a terminal is asked for.
+
+**It never asks how to start the app.** That question has no answer at setup time in a repository
+with several programs: "the app" means whichever one a Task's Verification happens to exercise, and
+no Task exists yet. A block with Gates and no `start` is a complete recipe — the Gates are the whole
+Verdict for most repositories — and the Verifier says so when a Task does ask for a browser round.
+The flags `--start`, `--readiness-url` and `--port-env` still write one for anyone who wants it
+pinned.
+
+When a Task's Verification asks for a browser round and the recipe has no `start`, the Foreman runs
+a **Start turn** before giving up: one short unattended turn in the Task's Workspace
+(`core/start-discovery.ts`), given that Task's Verification section, which answers with the command
+that serves the program the Verification exercises. That is the whole reason `opsee init` can stop
+asking — in a repository with several programs the answer depends on the Task, and a Task exists by
+then. The answer must take the leased port (`{port}` or the port variable) or it is refused: a
+command that serves on its own default is the failure that looks like success, because the readiness
+URL answers from a server the Foreman never started. It is agent-authored, so it runs under the
+Gates' filtered environment like every other command from the repository, and it lands verbatim on
+the Run Record as the app's command.
+
+`start` without `readiness_url` is still refused: that is half a recipe, which would serve the app
+and never learn it came up. An existing `foreman` block, the user's or the analyzer's, is never
+rewritten: a re-run reports `unchanged` whatever the flags say, and a block whose `verify` is not a
+known word is reported and kept. The YAML is spliced textually, the block appended in the
 file's own indentation with no blank line before it, because a parsed-and-reserialised document
 would lose the analyzer's header comments; the JSON copy is re-serialised in its own indentation
 with `foreman` after the analyzer's members. The two are only ever both written when both exist

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opsee/cli",
-  "version": "0.11.11",
+  "version": "0.11.13",
   "description": "Opsee CLI — the opsee binary: login, whoami, and the home of the Foreman",
   "type": "module",
   "bin": {
@@ -17,7 +17,7 @@
     "@bufbuild/protobuf": "^2.14.0",
     "@connectrpc/connect": "^2.1.2",
     "@connectrpc/connect-node": "^2.1.2",
-    "@opsee/mcp-server": "0.11.11",
+    "@opsee/mcp-server": "0.11.13",
     "tsx": "^4.23.12"
   },
   "devDependencies": {

package/src/commands/foreman-debug.ts

@@ -2,7 +2,7 @@ import { resolve } from "node:path";
 import type { DebugTurnArgs } from "../args.js";
 import { AccountError, type Account } from "../foreman/account.js";
 import type { AccountStore } from "../foreman/account-store.js";
-import { loadRunRecipe, startApp, waitForReady, type RunRecipe, type StartOptions, type AppHandle, type WaitOptions, type Readiness } from "../foreman/run-recipe.js";
+import { loadRunRecipe, startable, startApp, waitForReady, type RunRecipe, type StartableRecipe, type StartOptions, type AppHandle, type WaitOptions, type Readiness } from "../foreman/run-recipe.js";
 import type { TrackerAdapter } from "../foreman/tracker-adapter.js";
 import type { TurnRequest, WorkerAdapter } from "../foreman/worker-adapter.js";
 
@@ -75,7 +75,7 @@ export interface ForemanDebugServeDeps {
   timeoutMs?: number;
   /** Test seams; the real recipe functions by default. */
   load?: (root: string) => RunRecipe;
-  start?: (recipe: RunRecipe, options: StartOptions) => AppHandle;
+  start?: (recipe: StartableRecipe, options: StartOptions) => AppHandle;
   wait?: (url: string, options: WaitOptions) => Promise<Readiness>;
 }
 
@@ -84,9 +84,16 @@ export interface ForemanDebugServeDeps {
  * the app up until Ctrl-C. Exit 1 when the recipe is missing or the app never becomes ready. */
 export async function runForemanDebugServe(deps: ForemanDebugServeDeps, port: number): Promise<number> {
   const recipe = (deps.load ?? loadRunRecipe)(deps.root);
+  // This command exists to serve the app, so a recipe that cannot is the whole failure, said here
+  // rather than as a spawn error from a command that is the empty string.
+  const servable = startable(recipe);
+  if (!servable) {
+    deps.out(`.opsee/config: the foreman block has no start command, so there is no app to serve. Add foreman.start, or let the Verifier work it out.`);
+    return 1;
+  }
   const timeoutMs = deps.timeoutMs ?? 120_000;
-  const app = (deps.start ?? startApp)(recipe, { port, cwd: deps.root, onOutput: (line) => deps.out(`  | ${line}`) });
-  deps.out(`starting: ${app.command}  (${recipe.portEnv}=${port}${app.pid ? `, pid ${app.pid}` : ""})`);
+  const app = (deps.start ?? startApp)(servable, { port, cwd: deps.root, onOutput: (line) => deps.out(`  | ${line}`) });
+  deps.out(`starting: ${app.command}  (${servable.portEnv}=${port}${app.pid ? `, pid ${app.pid}` : ""})`);
   deps.out(`waiting for ${app.readinessUrl} (up to ${timeoutMs}ms)`);
   try {
     const ready = await (deps.wait ?? waitForReady)(app.readinessUrl, { timeoutMs, signal: app.exitSignal });

package/src/commands/init.ts

@@ -15,7 +15,7 @@ import { pickProject, type ProjectChoice } from "../init/project.js";
 import { planRetire, RETIRED_SKILLS } from "../init/retire.js";
 import { listSkillFiles, skillNames } from "../init/skills.js";
 import { findReadyLabel, READY_LABEL, renderTrackerDoc, type Named, type TrackerDocData } from "../init/tracker-doc.js";
-import { existingRecipe, inferRecipe, mergeRecipeJson, mergeRecipeYaml, NO_START_COMMAND, type RecipeDefaults, type RecipeFlags } from "../init/run-recipe-config.js";
+import { existingRecipe, inferRecipe, mergeRecipeJson, mergeRecipeYaml, type RecipeDefaults, type RecipeFlags } from "../init/run-recipe-config.js";
 import { OPSEE_CONFIG_JSON, OPSEE_CONFIG_YAML, readOpseeConfigFiles } from "../opsee-config.js";
 import type { RunRecipe } from "../foreman/run-recipe.js";
 import { NOT_LOGGED_IN } from "./whoami.js";
@@ -47,7 +47,7 @@ export interface InitDeps extends Pick<CommandDeps, "isAuthenticated" | "out"> {
   recipeFlags: RecipeFlags;
   /** Asks for the Run Recipe with inferred defaults; null when there is no start command to
    * write. Only called when `.opsee/config` has no `foreman` block yet. */
-  askRecipe: (defaults: RecipeDefaults) => Promise<RunRecipe | null>;
+  askRecipe: (defaults: RecipeDefaults) => Promise<RunRecipe>;
 }
 
 export const CODEX_TRUST_HINT =
@@ -102,12 +102,8 @@ export async function runInit(deps: InitDeps): Promise<number> {
   // one of the two files is copied into the other, so they stay in step without a prompt.
   const config = readOpseeConfigFiles(deps.root);
   const answers = existingRecipe(config) ?? (await deps.askRecipe(inferRecipe(config, deps.recipeFlags)));
-  if (answers === null) {
-    deps.out(`skipped   ${OPSEE_CONFIG_YAML} — ${NO_START_COMMAND}`);
-  } else {
-    report.apply(OPSEE_CONFIG_YAML, mergeRecipeYaml(config.yaml, answers));
-    if (config.json !== null || config.yaml === null) report.apply(OPSEE_CONFIG_JSON, mergeRecipeJson(config.json, answers));
-  }
+  report.apply(OPSEE_CONFIG_YAML, mergeRecipeYaml(config.yaml, answers));
+  if (config.json !== null || config.yaml === null) report.apply(OPSEE_CONFIG_JSON, mergeRecipeJson(config.json, answers));
 
   deps.out("");
   deps.out(`Project ${project.name} (${project.key}, id ${project.id}); skills ${skillNames(skills).map((s) => `/${s}`).join(", ")}.`);

package/src/foreman/core/short-turn.ts

@@ -0,0 +1,80 @@
+/**
+ * Driving one short unattended turn to its terminal event.
+ *
+ * The Foreman runs a few of these beside the implementer turn: the Triage turn that drafts a
+ * missing Verification section, and the Start turn that works out how to serve the app for a
+ * browser round. They differ only in their prompt and their log label — the launch, the event
+ * drain, the rate-limit capture and the output tail are the same, and were the same code twice
+ * before this module existed.
+ */
+import type { Account } from "../account.js";
+import type { AdapterEvent, WorkerAdapter } from "../worker-adapter.js";
+import { tail } from "./install.js";
+
+export interface ShortTurnRequest {
+  worker: WorkerAdapter;
+  account: Account;
+  /** Where the turn runs: the Task's Workspace, so the Worker reads the real repository. */
+  cwd: string;
+  prompt: string;
+  /** Prefixes every log line, so a reader tells this turn from the implementer's. */
+  label: string;
+  maxTurns: number;
+  stallTimeoutMs?: number;
+  log: (line: string) => void;
+  now: () => number;
+}
+
+export interface DrainedTurn {
+  terminal: Extract<AdapterEvent, { type: "completed" | "failed" }>;
+  durationMs: number;
+  outputTail: string;
+  /** The vendor's rate-limit report, when one came (story 30). A short turn is a turn on the
+   * Account like any other, so a limit it hit Pauses the Account; the terminal event alone does not
+   * carry the reset the vendor named, which is what decides how long. */
+  rateLimit?: { resetAt?: string; message: string };
+}
+
+/** Runs one short turn to its terminal event, logging progress the way the dispatch loop does. */
+export async function driveShortTurn(req: ShortTurnRequest): Promise<DrainedTurn> {
+  const started = req.now();
+  const handle = req.worker.launch({
+    account: req.account,
+    cwd: req.cwd,
+    prompt: req.prompt,
+    maxTurns: req.maxTurns,
+    stallTimeoutMs: req.stallTimeoutMs,
+  });
+  const output: string[] = [];
+  let terminal: DrainedTurn["terminal"] | undefined;
+  let rateLimit: DrainedTurn["rateLimit"];
+  for await (const event of handle.events) {
+    switch (event.type) {
+      case "started":
+        req.log(`${req.label}: session ${event.sessionId}`);
+        break;
+      case "output":
+        for (const line of event.text.split("\n")) {
+          output.push(line);
+          req.log(`  | ${line}`);
+        }
+        break;
+      case "tool":
+        req.log(`  tool ${event.name}`);
+        break;
+      case "rate_limited":
+        rateLimit = { resetAt: event.resetAt, message: event.message };
+        req.log(`${req.label}: rate limited: ${event.message}${event.resetAt ? ` (resets ${event.resetAt})` : ""}`);
+        break;
+      case "stalled":
+        req.log(`${req.label}: stalled, no output for ${event.silentMs}ms`);
+        break;
+      case "completed":
+      case "failed":
+        terminal = event;
+        break;
+    }
+  }
+  if (!terminal) throw new Error("Worker Adapter contract violated: the event stream ended without a terminal event");
+  return { terminal, durationMs: req.now() - started, outputTail: tail(output.join("\n")), rateLimit };
+}

package/src/foreman/core/start-discovery.ts

@@ -0,0 +1,158 @@
+/**
+ * The Start turn: how the Foreman learns to serve the app when the Run Recipe does not say.
+ *
+ * `opsee init` no longer asks for a start command, because at setup time there is no Task and
+ * therefore no answer to "which of these programs?" in a repository that holds several. The
+ * question does have an answer later: a Task's Verification section describes a user journey, the
+ * Verifier needs that Task's app on a port, and the Workspace has the repository in it. So the
+ * Foreman asks then, in the Workspace, the way it asks for a missing Verification section in a
+ * Triage turn.
+ *
+ * What comes back is a command the Foreman then runs. It runs under the Gates' filtered
+ * environment (core/gates.ts `gateEnv`), which holds no credential of the Foreman's, and it lands
+ * verbatim on the Run Record as the app's command — so a reader can see what was run and who
+ * wrote it. Treat the answer as data, never as instructions.
+ */
+import type { Account } from "../account.js";
+import type { StartableRecipe } from "../run-recipe.js";
+import type { TrackerTask } from "../tracker-adapter.js";
+import type { WorkerAdapter } from "../worker-adapter.js";
+import { driveShortTurn } from "./short-turn.js";
+
+/** Reading a package manifest and naming one command is a handful of agentic turns, not a
+ * Worker's budget; the Run's own `maxTurns` lowers this, never raises it. */
+export const START_DISCOVERY_MAX_TURNS = 6;
+
+/** What a start command must contain to be usable: the Foreman leases a port per Task and the app
+ * has to take it. A command that ignores the port is the failure that looks like success — the app
+ * comes up on its own default, the readiness URL answers from a server nobody asked for, and two
+ * Tasks verified at once quietly share it. Vite is the common case: it ignores `PORT` and needs
+ * `--port {port} --strictPort`. */
+export function honoursPort(command: string, portEnv: string): boolean {
+  return command.includes("{port}") || command.includes(`$${portEnv}`) || command.includes(`\${${portEnv}}`);
+}
+
+export function startDiscoveryPrompt(task: Pick<TrackerTask, "identifier" | "title">, verification: string, workspace: { path: string }, portEnv: string): string {
+  return [
+    `You are a Worker run unattended by the Foreman for a Start turn on Task ${task.identifier}: ${task.title}.`,
+    "",
+    "A Verifier is about to prove this Task from the outside, in a browser. It needs the app running on a port the",
+    "Foreman leases. Nothing in this repository's Opsee config says how to start it. Work that out and report it.",
+    `Do not implement the Task and do not change any file: your working directory ${workspace.path} is the repository, read it.`,
+    "",
+    "## The Verification the Verifier will follow",
+    "",
+    verification,
+    "",
+    "## What to find",
+    "",
+    "The one program this Verification exercises — in a repository with several, the one whose pages it names —",
+    "and the command that serves it from the repository root, ready for a browser.",
+    "",
+    "## Rules for the command",
+    "",
+    `- It MUST take the port. Write the placeholder {port} where the port goes, or use $${portEnv}, which is set for it.`,
+    "  A command that ignores the port is worse than none: the app comes up on its own default and the Verifier",
+    "  drives a server it did not start.",
+    "- If the tool has a strict-port option, use it. Vite drifts to the next free port without --strictPort.",
+    "- It runs from the repository root, so include any directory change it needs.",
+    "- It serves; it does not build and exit.",
+    "",
+    "## Finishing",
+    "",
+    "End the turn with a Completion Report: outcome `done`, and the summary a single JSON object, nothing else:",
+    '{"start": "<command>", "readinessUrl": "<url that answers once it is up, with {port}>", "portEnv": "<variable name>"}',
+    "Report `blocked`, with the reason as a blocker, if this repository has no app a browser could drive.",
+  ].join("\n");
+}
+
+export interface StartAnswer {
+  recipe?: Pick<StartableRecipe, "start" | "readinessUrl" | "portEnv">;
+  /** Why the answer could not be used, for the log and the skip reason. */
+  reason?: string;
+}
+
+/**
+ * Reads the turn's summary back.
+ *
+ * Strict on purpose: this produces a shell command the Foreman executes, so a half-understood
+ * answer is refused rather than repaired. The port rule is the one that matters — see
+ * `honoursPort` for why a command that ignores it fails in the shape hardest to notice.
+ */
+export function parseStartAnswer(summary: string, fallbackPortEnv: string): StartAnswer {
+  const text = summary.trim();
+  const start = text.indexOf("{");
+  const end = text.lastIndexOf("}");
+  if (start === -1 || end <= start) return { reason: "the Start turn answered with no JSON object" };
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text.slice(start, end + 1));
+  } catch (error) {
+    return { reason: `the Start turn's answer is not valid JSON: ${error instanceof Error ? error.message : String(error)}` };
+  }
+  if (!parsed || typeof parsed !== "object") return { reason: "the Start turn's answer is not a JSON object" };
+  const block = parsed as Record<string, unknown>;
+  const str = (value: unknown) => (typeof value === "string" && value.trim() !== "" ? value.trim() : undefined);
+  const startCommand = str(block.start);
+  const readinessUrl = str(block.readinessUrl) ?? str(block.readiness_url);
+  const portEnv = str(block.portEnv) ?? str(block.port_env) ?? fallbackPortEnv;
+  if (!startCommand) return { reason: "the Start turn's answer has no start command" };
+  if (!readinessUrl) return { reason: "the Start turn's answer has no readiness URL" };
+  if (!honoursPort(startCommand, portEnv)) {
+    return { reason: `the Start turn's command ignores the port, so it would serve on its own: ${startCommand}` };
+  }
+  return { recipe: { start: startCommand, readinessUrl, portEnv } };
+}
+
+export interface StartDiscoveryRequest {
+  worker: WorkerAdapter;
+  account: Account;
+  task: Pick<TrackerTask, "identifier" | "title">;
+  verification: string;
+  workspace: { path: string };
+  portEnv: string;
+  maxTurns?: number;
+  stallTimeoutMs?: number;
+  log: (line: string) => void;
+  now: () => number;
+}
+
+/**
+ * Runs one Start turn and reads its answer. Never throws: a Start turn that fails is a browser
+ * round the Foreman cannot have, which is a skip, not an error.
+ *
+ * A rate limit here is logged and not acted on, which is the Verifier's own behaviour beside it:
+ * `VerifyOutcome` carries no way to report one, so run.ts cannot Pause the Account on a turn taken
+ * inside verification. A Triage turn does Pause, because it runs in run.ts where the Account is.
+ * Worth closing for both turns at once rather than for this one alone, and it is a spend of the
+ * cap either way rather than a wrong Verdict.
+ */
+export async function discoverStart(req: StartDiscoveryRequest): Promise<StartAnswer> {
+  const maxTurns = Math.min(START_DISCOVERY_MAX_TURNS, req.maxTurns ?? START_DISCOVERY_MAX_TURNS);
+  req.log(`start: ${req.account.vendor} turn on ${req.task.identifier} in ${req.workspace.path}, working out how to serve the app (at most ${maxTurns} turns)`);
+  let drained;
+  try {
+    drained = await driveShortTurn({
+      worker: req.worker,
+      account: req.account,
+      cwd: req.workspace.path,
+      prompt: startDiscoveryPrompt(req.task, req.verification, req.workspace, req.portEnv),
+      label: "start",
+      maxTurns,
+      stallTimeoutMs: req.stallTimeoutMs,
+      log: req.log,
+      now: req.now,
+    });
+  } catch (error) {
+    return { reason: `the Start turn failed: ${error instanceof Error ? error.message : String(error)}` };
+  }
+  if (drained.terminal.type !== "completed") {
+    return { reason: `the Start turn did not finish: ${drained.terminal.type === "failed" ? drained.terminal.reason : "no report"}` };
+  }
+  const summary = drained.terminal.report?.summary;
+  if (!summary) return { reason: "the Start turn finished without a Completion Report" };
+  const answer = parseStartAnswer(summary, req.portEnv);
+  if (answer.recipe) req.log(`start: ${req.task.identifier} will be served with: ${answer.recipe.start}  (agent-authored, read as data)`);
+  else req.log(`start: ${req.task.identifier} ${answer.reason}`);
+  return answer;
+}

package/src/foreman/core/triage.ts

@@ -10,9 +10,9 @@
  * drains the turn; run.ts records the outcome, since the Run Record write is the commit (ADR-0009).
  */
 import type { Account } from "../account.js";
+import { driveShortTurn, type DrainedTurn } from "./short-turn.js";
 import type { TrackerTask } from "../tracker-adapter.js";
-import type { AdapterEvent, WorkerAdapter } from "../worker-adapter.js";
-import { tail } from "./install.js";
+import type { WorkerAdapter } from "../worker-adapter.js";
 import type { WorkContract } from "./work-contract.js";
 
 /** Reading a few files and writing one section needs a handful of agentic turns, not a Worker's
@@ -81,58 +81,21 @@ export interface TriageTurnRequest {
   now: () => number;
 }
 
-export interface DrainedTurn {
-  terminal: Extract<AdapterEvent, { type: "completed" | "failed" }>;
-  durationMs: number;
-  outputTail: string;
-  /** The vendor's rate-limit report, when one came (story 30). A Triage turn is a turn on the
-   * Account like any other, so a limit it hit Pauses the Account; the terminal event alone does not
-   * carry the reset the vendor named, which is what decides how long. */
-  rateLimit?: { resetAt?: string; message: string };
-}
+export type { DrainedTurn };
 
-/** Runs one Triage turn to its terminal event, logging progress the way the dispatch loop does. */
+/** Runs one Triage turn to its terminal event. */
 export async function driveTriageTurn(req: TriageTurnRequest): Promise<DrainedTurn> {
   const maxTurns = Math.min(TRIAGE_MAX_TURNS, req.maxTurns ?? TRIAGE_MAX_TURNS);
-  const started = req.now();
-  const handle = req.worker.launch({
+  req.log(`triage: ${req.account.vendor} turn on ${req.task.identifier} in ${req.workspace.path} (at most ${maxTurns} turns)`);
+  return driveShortTurn({
+    worker: req.worker,
     account: req.account,
     cwd: req.workspace.path,
     prompt: triagePrompt(req.task, req.contract, req.workspace),
+    label: "triage",
     maxTurns,
     stallTimeoutMs: req.stallTimeoutMs,
+    log: req.log,
+    now: req.now,
   });
-  req.log(`triage: ${req.account.vendor} turn on ${req.task.identifier} in ${req.workspace.path} (at most ${maxTurns} turns)`);
-  const output: string[] = [];
-  let terminal: DrainedTurn["terminal"] | undefined;
-  let rateLimit: DrainedTurn["rateLimit"];
-  for await (const event of handle.events) {
-    switch (event.type) {
-      case "started":
-        req.log(`triage: session ${event.sessionId}`);
-        break;
-      case "output":
-        for (const line of event.text.split("\n")) {
-          output.push(line);
-          req.log(`  | ${line}`);
-        }
-        break;
-      case "tool":
-        req.log(`  tool ${event.name}`);
-        break;
-      case "rate_limited":
-        rateLimit = { resetAt: event.resetAt, message: event.message };
-        req.log(`triage: rate limited: ${event.message}${event.resetAt ? ` (resets ${event.resetAt})` : ""}`);
-        break;
-      case "stalled":
-        req.log(`triage: stalled, no output for ${event.silentMs}ms`);
-        break;
-      case "completed":
-      case "failed":
-        terminal = event;
-        break;
-    }
-  }
-  if (!terminal) throw new Error("Worker Adapter contract violated: the event stream ended without a terminal event");
-  return { terminal, durationMs: req.now() - started, outputTail: tail(output.join("\n")), rateLimit };
 }

package/src/foreman/core/verifier.ts

@@ -46,7 +46,8 @@ import { RunEventInputSchema, type RunEvent, type RunEventInput, type RunVerific
 import { parseOpseeJson, readYamlBlock, type OpseeConfigFiles } from "../../opsee-config.js";
 import type { Account } from "../account.js";
 import { foremanLocalDir } from "../local-dir.js";
-import { RECIPE_KEY, recipeFromConfig, startApp, waitForReady, type RunRecipe, type VerifyMode } from "../run-recipe.js";
+import { RECIPE_KEY, recipeFromConfig, startable, startApp, waitForReady, type RunRecipe, type StartableRecipe, type VerifyMode } from "../run-recipe.js";
+import { discoverStart, type StartAnswer } from "./start-discovery.js";
 import type { TrackerTask } from "../tracker-adapter.js";
 import { parseVerdict, VERDICT_CONTRACT, type Defect, type Verdict } from "../verdict.js";
 import type { AdapterEvent, McpServerSpec, WorkerAdapter } from "../worker-adapter.js";
@@ -423,6 +424,10 @@ export interface VerifierOptions {
    * default). */
   mcpFor?: (outputDir: string, allowedOrigins: readonly string[]) => McpServerSpec;
   ports?: PortLease;
+  /** How the Foreman works out a start command the Run Recipe does not carry (core/
+   * start-discovery.ts). A Start turn by default; a test hands in an answer instead. Set it to a
+   * function that answers with a reason to turn discovery off. */
+  discoverStart?: (input: { task: Pick<TrackerTask, "identifier" | "title">; verification: string; workspace: { path: string }; portEnv: string }) => Promise<StartAnswer>;
   log?: (line: string) => void;
   now?: () => number;
 }
@@ -461,15 +466,57 @@ export function verifierWith(options: VerifierOptions): VerifierFn {
       log(`verify: ${task.identifier} skipped: ${decision.reason}; the Gates are the whole verification`);
       return { kind: "skipped", reason: decision.reason };
     }
-    log(`verify: ${task.identifier} browser verification: ${decision.reason} (Run Recipe read from ${source})`);
+    // The round is wanted; whether it can happen is a second question. A block with Gates and no
+    // start is the ordinary shape of a repository that never asked for a browser -- `opsee init`
+    // stopped asking, because at setup time nobody knows which of a repository's programs a Task
+    // will exercise. Now there is a Task, a Verification section and a Workspace, so the Foreman
+    // asks a Start turn rather than giving up.
+    let servable = startable(recipe);
+    let discovered: string | undefined;
+    if (!servable) {
+      const ask =
+        options.discoverStart ??
+        ((input) =>
+          discoverStart({
+            worker: options.worker,
+            account: options.account,
+            task: input.task,
+            verification: input.verification,
+            workspace: input.workspace,
+            portEnv: input.portEnv,
+            maxTurns: options.maxTurns,
+            stallTimeoutMs: options.stallTimeoutMs,
+            log,
+            now,
+          }));
+      const answer = await ask({ task, verification: input.verification, workspace, portEnv: recipe.portEnv });
+      if (answer.recipe) {
+        servable = { ...recipe, ...answer.recipe } satisfies StartableRecipe;
+        discovered = answer.recipe.start;
+      } else {
+        log(`verify: ${task.identifier} could not work out how to serve the app: ${answer.reason}`);
+      }
+    }
+    if (!servable) {
+      const missing = `the Run Recipe has no start command, so the app cannot be served (read from ${source})`;
+      if (recipe.verify === "browser") {
+        log(`verify: ${task.identifier} the Run Recipe says verify: browser but ${missing}; the round failed`);
+        return { kind: "failed", reason: `the Run Recipe says verify: browser but ${missing}`, durationMs: 0 };
+      }
+      log(`verify: ${task.identifier} skipped: ${missing}; the Gates are the whole verification`);
+      return { kind: "skipped", reason: missing };
+    }
+    log(
+      `verify: ${task.identifier} browser verification: ${decision.reason} (Run Recipe read from ${source}${discovered ? ", start command from a Start turn" : ""})`,
+    );
 
     const started = now();
     const port = await ports.acquire(task.id);
     const output: string[] = [];
-    const app = startApp(recipe, { port, cwd: workspace.path, env: gateEnv(options.account), onOutput: (line) => output.push(line) });
+    const app = startApp(servable, { port, cwd: workspace.path, env: gateEnv(options.account), onOutput: (line) => output.push(line) });
     input.onPid?.("app", app.pid);
     const appAt = now();
-    log(`verify: ${task.identifier} starting the app on port ${port}: ${app.command} (${recipe.portEnv}=${port}${app.pid ? `, pid ${app.pid}` : ""})`);
+    log(`verify: ${task.identifier} starting the app on port ${port}: ${app.command} (${servable.portEnv}=${port}${app.pid ? `, pid ${app.pid}` : ""})`);
     const appRun = (ready: boolean, error?: string): AppRun => ({
       command: app.command,
       cwd: workspace.path,

package/src/foreman/run-recipe.ts

@@ -32,10 +32,16 @@ export const VERIFY_MODES = ["auto", "browser", "none"] as const;
 export type VerifyMode = (typeof VERIFY_MODES)[number];
 
 export interface RunRecipe {
-  /** Shell command that serves the app; `{port}` and the port variable are substituted. */
-  start: string;
-  /** URL that answers once the app is up; `{port}` and the port variable are substituted. */
-  readinessUrl: string;
+  /** Shell command that serves the app; `{port}` and the port variable are substituted.
+   *
+   * Optional, because only the Verifier's browser round needs it and most repositories never ask
+   * for one. The Gates are the rest of the block and they run without it. `opsee init` writes it
+   * when the analyzer already knows a dev command and otherwise leaves it out rather than asking
+   * a question whose answer is "which of these six programs?" in a monorepo. */
+  start?: string;
+  /** URL that answers once the app is up; `{port}` and the port variable are substituted. Absent
+   * with `start`, present with it. */
+  readinessUrl?: string;
   /** Name of the environment variable set to the port when `start` runs. */
   portEnv: string;
   gates: RunRecipeGates;
@@ -81,10 +87,17 @@ function nonEmptyString(value: unknown): string | undefined {
 export function recipeFromConfig(raw: unknown, source: string): RunRecipe {
   if (!raw || typeof raw !== "object") throw new Error(`${source} has no foreman block; run opsee init to write the Run Recipe.`);
   const block = raw as Record<string, unknown>;
+  // Neither is required. A block with Gates and no start is a repository that never wanted a
+  // browser round, which is most of them; the Verifier says so and the Gates give the Verdict.
+  //
+  // A start command without a readiness URL is different: it is a half-written recipe. It would
+  // start the app and never know it was up, so the round would skip for a reason that looks like
+  // "you did not configure this" when the truth is "you configured half of it".
   const start = nonEmptyString(block.start);
   const readinessUrl = nonEmptyString(block.readiness_url);
-  if (!start) throw new Error(`${source}: foreman.start is missing; it is the command that serves the app.`);
-  if (!readinessUrl) throw new Error(`${source}: foreman.readiness_url is missing; it is the URL that answers once the app is up.`);
+  if (start && !readinessUrl) {
+    throw new Error(`${source}: foreman.start is set but foreman.readiness_url is missing; it is the URL that answers once the app is up.`);
+  }
   const gatesRaw = block.gates && typeof block.gates === "object" ? (block.gates as Record<string, unknown>) : {};
   const gates: RunRecipeGates = {};
   for (const name of ["test", "lint", "typecheck"] as const) {
@@ -97,7 +110,13 @@ export function recipeFromConfig(raw: unknown, source: string): RunRecipe {
   } catch (error) {
     throw new Error(`${source}: ${error instanceof Error ? error.message : String(error)}`);
   }
-  return { start, readinessUrl, portEnv: nonEmptyString(block.port_env) ?? DEFAULT_PORT_ENV, gates, ...(block.verify === undefined ? {} : { verify }) };
+  return {
+    ...(start === undefined ? {} : { start }),
+    ...(readinessUrl === undefined ? {} : { readinessUrl }),
+    portEnv: nonEmptyString(block.port_env) ?? DEFAULT_PORT_ENV,
+    gates,
+    ...(block.verify === undefined ? {} : { verify }),
+  };
 }
 
 /** Resolves the Run Recipe of the repo at `root`. The JSON copy is authoritative when present
@@ -146,7 +165,17 @@ export interface AppHandle {
  * wrapper spawned underneath it. The child goes on this process's live registry
  * (worker-process.ts `trackLiveProcess`) beside the Workers, so a Foreman that is signalled or
  * exits stops the app with them rather than orphaning it. */
-export function startApp(recipe: RunRecipe, options: StartOptions): AppHandle {
+/** A recipe that can actually serve the app: both halves present. `startApp` takes this rather
+ * than a RunRecipe so a caller cannot forget the check, and the Verifier's "cannot start the app"
+ * branch is the one place that decides what to do about it. */
+export type StartableRecipe = RunRecipe & { start: string; readinessUrl: string };
+
+/** The recipe when it can serve the app, undefined when it cannot. */
+export function startable(recipe: RunRecipe): StartableRecipe | undefined {
+  return recipe.start && recipe.readinessUrl ? (recipe as StartableRecipe) : undefined;
+}
+
+export function startApp(recipe: StartableRecipe, options: StartOptions): AppHandle {
   const command = substitutePort(recipe.start, options.port, recipe.portEnv);
   const readinessUrl = substitutePort(recipe.readinessUrl, options.port, recipe.portEnv);
   const child = spawn(command, {

package/src/init/prompt.ts

@@ -3,26 +3,25 @@ import type { ProjectChoice } from "./project.js";
 import type { RunRecipe } from "../foreman/run-recipe.js";
 import type { RecipeDefaults } from "./run-recipe-config.js";
 
-/** Asks for the Run Recipe with the inferred values as defaults (Enter keeps them). Without a
- * terminal the defaults stand as they are, and null comes back when no start command could be
- * inferred, since a recipe without one cannot start anything. */
-export async function askRecipe(defaults: RecipeDefaults): Promise<RunRecipe | null> {
-  if (!process.stdin.isTTY) {
-    return defaults.start ? { ...defaults, start: defaults.start } : null;
-  }
+/**
+ * Asks for the one Run Recipe value nothing else can infer: the typecheck Gate.
+ *
+ * It no longer asks how to start the app. That question has no answer at setup time in a
+ * repository with more than one program -- "the app" means whichever one a Task's Verification
+ * happens to exercise, which is not known until there is a Task. The analyzer's dev command is
+ * still written when it exists, and the Verifier works the rest out when a browser round is
+ * actually wanted.
+ *
+ * Without a terminal the inferred values stand as they are.
+ */
+export async function askRecipe(defaults: RecipeDefaults): Promise<RunRecipe> {
+  if (!process.stdin.isTTY) return { ...defaults };
   const rl = createInterface({ input: process.stdin, output: process.stdout });
-  const ask = async (label: string, fallback: string | undefined): Promise<string> => {
-    const answer = (await rl.question(`${label}${fallback ? ` [${fallback}]` : ""}: `)).trim();
-    return answer || fallback || "";
-  };
   try {
-    rl.write("Run Recipe (how the Foreman starts the app for verification; {port} is the Worker's port):\n");
-    const start = await ask("Start command", defaults.start);
-    if (!start) return null;
-    const readinessUrl = await ask("Readiness URL", defaults.readinessUrl);
-    const portEnv = await ask("Port variable", defaults.portEnv);
-    const typecheck = await ask("Typecheck command (blank for none)", defaults.gates.typecheck);
-    return { start, readinessUrl, portEnv, gates: { ...defaults.gates, typecheck: typecheck || undefined } };
+    const fallback = defaults.gates.typecheck;
+    const answer = (await rl.question(`Typecheck command for the Foreman's Gates (blank for none)${fallback ? ` [${fallback}]` : ""}: `)).trim();
+    const typecheck = answer || fallback;
+    return { ...defaults, gates: { ...defaults.gates, typecheck: typecheck || undefined } };
   } finally {
     rl.close();
   }

package/src/init/run-recipe-config.ts

@@ -33,18 +33,16 @@ export function commandsOf(files: OpseeConfigFiles): Record<string, string> {
  * Gate has no analyzer equivalent and is only ever a flag or a prompt answer. */
 export function inferRecipe(files: OpseeConfigFiles, flags: RecipeFlags): RecipeDefaults {
   const commands = commandsOf(files);
+  const start = flags.start ?? commands.dev ?? commands.start;
   return {
-    start: flags.start ?? commands.dev ?? commands.start,
-    readinessUrl: flags.readinessUrl ?? DEFAULT_READINESS_URL,
+    // The pair travels together or not at all: a readiness URL with nothing to start is a line
+    // that answers a question nobody asked, and `recipeFromConfig` rejects the other half-pair.
+    ...(start === undefined ? {} : { start, readinessUrl: flags.readinessUrl ?? DEFAULT_READINESS_URL }),
     portEnv: flags.portEnv ?? DEFAULT_PORT_ENV,
     gates: { test: commands.test, lint: commands.lint, typecheck: flags.typecheck },
   };
 }
 
-/** Why `init` skipped the recipe when nothing said how to start the app. */
-export const NO_START_COMMAND =
-  "no start command: pass --start <cmd>, answer the prompt on a terminal, or set commands.dev in .opsee/config";
-
 /** The recipe a config file already carries, so a block present in one of the two files is copied
  * into the other rather than asked for again; null when neither has a block that can serve as a
  * recipe. The YAML is the analyzer's primary file and wins when both have one. */
@@ -68,12 +66,13 @@ function gateEntries(gates: RunRecipeGates): Array<[string, string]> {
 }
 
 function yamlRecipeBlock(recipe: RunRecipe, indent: string): string {
-  const lines = [
-    `${RECIPE_KEY}:`,
-    `${indent}start: ${yamlScalar(recipe.start)}`,
-    `${indent}readiness_url: ${yamlScalar(recipe.readinessUrl)}`,
-    `${indent}port_env: ${yamlScalar(recipe.portEnv)}`,
-  ];
+  // start and readiness_url only when something already knew them: the analyzer's dev command, or
+  // an --start flag. A block with neither is a complete recipe for a repository whose Verdict comes
+  // from its Gates.
+  const lines = [`${RECIPE_KEY}:`];
+  if (recipe.start) lines.push(`${indent}start: ${yamlScalar(recipe.start)}`);
+  if (recipe.readinessUrl) lines.push(`${indent}readiness_url: ${yamlScalar(recipe.readinessUrl)}`);
+  lines.push(`${indent}port_env: ${yamlScalar(recipe.portEnv)}`);
   const gates = gateEntries(recipe.gates);
   if (gates.length > 0) {
     lines.push(`${indent}gates:`);