explorbot 0.3.4 → 0.4.0

package/bin/explorbot-cli.ts

@@ -146,6 +146,7 @@ addCommonOptions(
     .command('explore <path>')
     .description('Explore a page autonomously and run invented scenarios')
     .option('--max-tests <count>', 'Maximum number of tests to run')
+    .option('--max-duration <minutes>', 'Wall-clock budget in minutes for the whole run; wraps up before the limit is hit')
     .option('--focus <feature>', 'Focus area for exploration')
     .option('--configure <spec>', 'Reuse spec: keys new|from|style|subpages|pick_by|priority, e.g. "new:25%;pick_by=random;priority=critical,high"')
     .option('--dry-run', 'Mark picked tests as skipped without executing or generating new ones')
@@ -157,6 +158,8 @@ addCommonOptions(
     const { ExploreCommand } = await import('../src/commands/explore-command.js');
     const cmd = new ExploreCommand(explorBot);
     if (options.maxTests) cmd.maxTests = Number.parseInt(options.maxTests, 10);
+    if (options.maxDuration) cmd.maxDurationMinutes = Number.parseInt(options.maxDuration, 10);
+    else if (process.env.EXPLORBOT_MAX_DURATION) cmd.maxDurationMinutes = Number.parseInt(process.env.EXPLORBOT_MAX_DURATION, 10);
     if (options.dryRun) cmd.dryRun = true;
     const execArgs: string[] = [];
     if (options.focus) execArgs.push('--focus', `"${options.focus}"`);
@@ -257,14 +260,13 @@ addCommonOptions(program.command('plan <path>').description('Generate test plan
 
 addCommonOptions(program.command('plan:load <planfile> [index]').description('Load a plan file and display its tests. Pass index to see test details.')).action(async (planfile: string, index: string | undefined) => {
   try {
-    const resolvedPath = path.resolve(planfile);
-    if (!fs.existsSync(resolvedPath)) {
-      console.error(`Plan file not found: ${resolvedPath}`);
+    const plan = Plan.loadFromFile(planfile);
+    if (!plan?.filePath) {
+      console.error(`Plan file not found: ${planfile}`);
       process.exit(1);
     }
 
-    const plan = Plan.fromMarkdown(resolvedPath);
-    const planFile = path.basename(resolvedPath);
+    const planFile = path.basename(plan.filePath);
 
     if (index) {
       const idx = Number.parseInt(index, 10);
@@ -276,7 +278,7 @@ addCommonOptions(program.command('plan:load <planfile> [index]').description('Lo
       const lines: string[] = [];
       lines.push(`## #${idx} ${test.scenario}\n`);
       lines.push(`**Priority:** ${test.priority}`);
-      const planUrl = plan.url || plan.tests[0]?.startUrl;
+      const planUrl = plan.startUrl;
       if (planUrl) lines.push(`**Plan URL:** ${planUrl}`);
       if (test.startUrl && test.startUrl !== planUrl) lines.push(`**Test URL:** ${test.startUrl}`);
       if (test.plannedSteps.length) {
@@ -293,7 +295,7 @@ addCommonOptions(program.command('plan:load <planfile> [index]').description('Lo
       return;
     }
 
-    const planUrl = plan.url || plan.tests[0]?.startUrl;
+    const planUrl = plan.startUrl;
     const lines: string[] = [`**${plan.title}** (${plan.tests.length} tests)\n`];
     if (planUrl) {
       lines.push(`URL: ${planUrl}\n`);
@@ -325,9 +327,6 @@ addCommonOptions(program.command('plan:load <planfile> [index]').description('Lo
 addCommonOptions(program.command('test <planfile> [index]').description('Execute tests from a plan file. Index: 1, 1,3, 1-5, *, all').option('--grep <pattern>', 'Run tests matching pattern').option('--from-plan <file>', 'Load plan file when the first argument is a test index')).action(
   async (planfile, index, options) => {
     try {
-      const explorBot = new ExplorBot(buildExplorBotOptions(undefined, options));
-      await explorBot.start();
-
       let planfileArg = planfile;
       let indexArg = index;
       if (options.fromPlan) {
@@ -335,11 +334,16 @@ addCommonOptions(program.command('test <planfile> [index]').description('Execute
         indexArg = planfile;
       }
 
+      const planTarget = Plan.loadFromFile(planfileArg)?.startUrl;
+
+      const explorBot = new ExplorBot(buildExplorBotOptions(planTarget, options));
+      await explorBot.start();
+
       const plan = explorBot.loadPlan(planfileArg);
       const pending = plan.getPendingTests();
       log(`Plan loaded: "${plan.title}" (${plan.tests.length} tests, ${pending.length} pending)`);
 
-      const startUrl = plan.url || pending[0]?.startUrl;
+      const startUrl = plan.startUrl;
       if (!startUrl) {
         throw new Error('No URL found in plan or tests. Cannot determine where to navigate.');
       }
@@ -347,7 +351,7 @@ addCommonOptions(program.command('test <planfile> [index]').description('Execute
       log(`Navigating to ${startUrl}`);
       await explorBot.visit(startUrl);
 
-      let args = '';
+      let args = '*';
       if (indexArg) args = indexArg;
       else if (options.grep) args = options.grep;
 
@@ -437,10 +441,11 @@ addCommonOptions(
     .option('--shallow', 'Breadth-first: pick globally least-visited page')
     .option('--scope <prefix>', 'Restrict navigation to URL prefix')
     .option('--max-tests <count>', 'Maximum number of tests to run')
+    .option('--max-duration <minutes>', 'Wall-clock budget in minutes for the whole run')
 ).action(async (startUrl, options) => {
   const explorBot = new ExplorBot(buildExplorBotOptions(startUrl || '/', options));
   await explorBot.start();
-  const args = [options.deep && '--deep', options.shallow && '--shallow', options.scope && `--scope ${options.scope}`, options.maxTests && `--max-tests ${options.maxTests}`].filter(Boolean).join(' ');
+  const args = [options.deep && '--deep', options.shallow && '--shallow', options.scope && `--scope ${options.scope}`, options.maxTests && `--max-tests ${options.maxTests}`, options.maxDuration && `--max-duration ${options.maxDuration}`].filter(Boolean).join(' ');
   const { FreesailCommand } = await import('../src/commands/freesail-command.js');
   const cmd = new FreesailCommand(explorBot);
   await cmd.execute(args);

package/boat/doc-collector/src/cli.ts

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { Command } from 'commander';
 import { ConfigCommand } from '../../../src/commands/config-command.ts';
+import { remote } from '../../../src/remote.ts';
 import { isVerboseMode, setPreserveConsoleLogs, setQuietMode } from '../../../src/utils/logger.ts';
 import { DocBot, type DocbotOptions } from './docbot.ts';
 
@@ -59,9 +60,11 @@ export function createDocsCommands(name = 'docs'): Command {
       console.log(`Use in Explorbot: npx explorbot start ${startPath} --spec "${result.outputDir}"`);
 
       await bot.stop();
+      await remote.close(0);
       process.exit(0);
     } catch (error) {
       console.error('Failed:', error instanceof Error ? error.message : 'Unknown error');
+      await remote.close(1);
       process.exit(1);
     }
   });

package/boat/doc-collector/src/docbot.ts

@@ -465,7 +465,9 @@ class DocBot {
   private saveIndex(startPath: string, pages: DocumentedPage[], skipped: SkippedPage[], maxPages: number): { indexPath: string; diagramPath: string } {
     const outputDir = this.configParser.getOutputDir();
     const indexPath = path.join(outputDir, 'index.md');
-    writeFileSync(indexPath, renderSpecIndex(outputDir, startPath, pages, skipped, maxPages), 'utf8');
+    const index = renderSpecIndex(outputDir, startPath, pages, skipped, maxPages);
+    writeFileSync(indexPath, index, 'utf8');
+    tag('data').log('docs', { path: indexPath, content: index });
     const diagramPath = path.join(outputDir, 'state-diagram.mmd');
     writeFileSync(diagramPath, renderMermaidBody(outputDir, pages), 'utf8');
     return { indexPath, diagramPath };

package/boat/prima/src/cli.ts

@@ -31,9 +31,9 @@ const checkHelp = dedent`
               as false.
   Outcomes are settled against a screenshot of the whole page: what a user can see is
   the proof, and the run log only says what was done. CONTRADICTION means the two
-  disagree - reported with both sides rather than settled one way, and ### Artifacts
-  then names the html, aria and screenshot on disk so you can judge it yourself. Not
-  finding something in the picture is not enough on its own; that is "not verified".
+  disagree - reported with both sides rather than settled one way, so read the html,
+  aria and screenshot named under ### Artifacts and judge it yourself. Not finding
+  something in the picture is not enough on its own; that is "not verified".
   ok: follows those outcomes - false when one FAILED or CONTRADICTED, or when the run
   could not complete, which is reported as such rather than as an app failure.
   Page problems seen on the way appear under ### Answer, not as step failures.
@@ -53,6 +53,13 @@ const verifyHelp = dedent`
   could not be expressed, which is not the same as false.
 `;
 
+const statusHelp = dedent`
+  Reads the files a command recorded, so it needs no browser and outlives the session.
+  The hash is looked up across every recorded site. ### Artifacts names every file kept
+  under it: the aria tree, the html, the screenshot and network log when they were
+  captured, and the per-step captures of a do run.
+`;
+
 const reportHelp = dedent`
   Commands are logged as they run, so the report needs no browser and outlives the session.
   The most recent session is reported unless --pw-session names another.
@@ -122,7 +129,7 @@ function primaFor(options: any): Prima {
   return new Prima(buildOptions(options));
 }
 
-async function runPrima(options: any, command: string, run: (prima: Prima) => Promise<EnvelopeData>, record = true): Promise<void> {
+async function runPrima(options: any, command: string, run: (prima: Prima) => Promise<EnvelopeData>): Promise<void> {
   setQuietMode(!isVerboseMode());
   trackActivityLine();
   const prima = primaFor(options);
@@ -136,7 +143,7 @@ async function runPrima(options: any, command: string, run: (prima: Prima) => Pr
     envelope = await prima.toolFailureEnvelope(command, error);
   }
 
-  if (record) prima.record(envelope, Date.now() - startedAt);
+  prima.record(envelope, Date.now() - startedAt);
   clearActivityLine();
   console.log(renderEnvelope(envelope));
   await prima.stop().catch(() => {});
@@ -211,9 +218,15 @@ export function createPrimaCommands(name = 'prima'): Command {
       process.exit(0);
     });
 
-  addCommonOptions(cmd.command('status <hash>').description('Show the artifacts and page detail recorded for an earlier command')).action(async (hash, options) => {
-    await runPrima(options, `status ${hash}`, (prima) => prima.status(hash), false);
-  });
+  addCommonOptions(cmd.command('status <hash>').description('Show the artifacts and page detail recorded for an earlier command'))
+    .addHelpText('after', `\n${statusHelp}`)
+    .action(async (hash, options) => {
+      setQuietMode(!isVerboseMode());
+      const prima = primaFor(options);
+      const envelope = await prima.status(hash).catch((error: unknown) => prima.toolFailureEnvelope(`status ${hash}`, error));
+      console.log(renderEnvelope(envelope));
+      process.exit(envelope.ok ? 0 : 1);
+    });
 
   addCommonOptions(cmd.command('report').description('Turn every command of a session into one html and markdown report'))
     .addHelpText('after', `\n${reportHelp}`)

package/boat/prima/src/envelope.ts

@@ -1,6 +1,10 @@
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 
+export const STATUS_FILE = 'status.json';
+
+const ARTIFACT_FILES = { aria: 'aria.yml', html: 'page.html', screenshot: 'page.png', network: 'network.jsonl' };
+
 const EXPECTATION_LABELS = {
   passed: 'PASSED       ',
   failed: 'FAILED       ',
@@ -33,7 +37,7 @@ export interface EnvelopeData {
   failure?: { error: string; compactAria?: string };
   instance: InstanceInfo;
   status?: string;
-  artifacts?: { aria: string; html: string; screenshot?: string; network?: string };
+  artifacts?: ArtifactPaths;
 }
 
 export function renderEnvelope(data: EnvelopeData): string {
@@ -41,27 +45,40 @@ export function renderEnvelope(data: EnvelopeData): string {
   return sections.filter((section) => section).join('\n\n');
 }
 
-export function writeArtifacts(dir: string, snapshot: { aria: string | null; html: string | null; screenshot?: Buffer; requests: unknown[] }): { aria: string; html: string; screenshot?: string; network?: string } {
+export function writeArtifacts(dir: string, snapshot: { aria: string | null; html: string | null; screenshot?: Buffer; requests: unknown[] }): ArtifactPaths {
   mkdirSync(dir, { recursive: true });
-  const paths: { aria: string; html: string; screenshot?: string; network?: string } = {
-    aria: path.resolve(dir, 'aria.yml'),
-    html: path.resolve(dir, 'page.html'),
+  const paths: ArtifactPaths = {
+    aria: path.resolve(dir, ARTIFACT_FILES.aria),
+    html: path.resolve(dir, ARTIFACT_FILES.html),
   };
   writeFileSync(paths.aria, snapshot.aria ?? '', 'utf-8');
   writeFileSync(paths.html, snapshot.html ?? '', 'utf-8');
 
   if (snapshot.screenshot) {
-    paths.screenshot = path.resolve(dir, 'page.png');
+    paths.screenshot = path.resolve(dir, ARTIFACT_FILES.screenshot);
     writeFileSync(paths.screenshot, snapshot.screenshot);
   }
 
   if (!snapshot.requests.length) return paths;
 
-  paths.network = path.resolve(dir, 'network.jsonl');
+  paths.network = path.resolve(dir, ARTIFACT_FILES.network);
   writeFileSync(paths.network, snapshot.requests.map((request) => `${JSON.stringify(request)}\n`).join(''), 'utf-8');
   return paths;
 }
 
+export function readArtifacts(dir: string): ArtifactPaths {
+  const paths: ArtifactPaths = { aria: path.resolve(dir, ARTIFACT_FILES.aria), html: path.resolve(dir, ARTIFACT_FILES.html) };
+  if (existsSync(path.resolve(dir, ARTIFACT_FILES.screenshot))) paths.screenshot = path.resolve(dir, ARTIFACT_FILES.screenshot);
+  if (existsSync(path.resolve(dir, ARTIFACT_FILES.network))) paths.network = path.resolve(dir, ARTIFACT_FILES.network);
+
+  const recorded = [...Object.values(ARTIFACT_FILES), STATUS_FILE];
+  const files = readdirSync(dir)
+    .filter((entry) => !recorded.includes(entry))
+    .sort();
+  if (files.length) paths.files = files;
+  return paths;
+}
+
 function renderResult(data: EnvelopeData): string {
   const lines = [`ok: ${data.ok}`, `command: ${data.command}`];
   if (data.used?.length) lines.push(`used: ${data.used.join('; ')}`);
@@ -100,7 +117,7 @@ function renderSteps(data: EnvelopeData): string | null {
     lines.push(`${index + 1}. ${mark} ${step.label}`);
     for (const line of (step.proof || '').split('\n').filter(Boolean)) lines.push(`      ${line}`);
   });
-  if (data.stepFiles) lines.push('', `page after each step: ${data.stepFiles}`);
+  if (data.stepFiles) lines.push('', `page after each step: ${data.stepFiles}/<n>-<step>.{aria.yaml,html,diff.yaml}`);
   return section('Steps', lines.join('\n'));
 }
 
@@ -178,6 +195,7 @@ export function renderArtifacts(data: EnvelopeData): string | null {
   const lines = [`aria:       ${data.artifacts.aria}`, `html:       ${data.artifacts.html}`];
   if (data.artifacts.screenshot) lines.push(`screenshot: ${data.artifacts.screenshot}`);
   if (data.artifacts.network) lines.push(`network:    ${data.artifacts.network}`);
+  if (data.artifacts.files?.length) lines.push(`also here:  ${data.artifacts.files.join(', ')}`);
   return section('Artifacts', lines.join('\n'));
 }
 
@@ -189,3 +207,11 @@ function align(label: string, marker: string, width: number): string {
 function section(title: string, body: string): string {
   return `### ${title}\n${body}`;
 }
+
+export interface ArtifactPaths {
+  aria: string;
+  html: string;
+  screenshot?: string;
+  network?: string;
+  files?: string[];
+}

package/boat/prima/src/prima.ts

@@ -25,7 +25,7 @@ import { browserErrorMessage } from '../../../src/utils/browser-errors.ts';
 import { pluralize } from '../../../src/utils/logger.ts';
 import { mdq } from '../../../src/utils/markdown-query.ts';
 import { safeFilename } from '../../../src/utils/strings.ts';
-import { type EnvelopeData, type InstanceInfo, writeArtifacts } from './envelope.ts';
+import { type EnvelopeData, type InstanceInfo, STATUS_FILE, readArtifacts, writeArtifacts } from './envelope.ts';
 import { isFunctionExpression, takePwValue, toCodeceptWrapper } from './pw-parser.ts';
 import { type PwServerDescriptor, readDescriptors, selectDescriptor } from './pw-registry.ts';
 import { type SessionRun, latestSessionFile, readSession, recordCommand, sessionFile, sessionsDir } from './session-log.ts';
@@ -376,7 +376,6 @@ export class Prima {
 
     const problems = [...unreached.map((expectation) => `not reached: ${expectation.text}`), ...contradicted.map((expectation) => `the picture and the run disagree about: ${expectation.text}`)];
     if (problems.length) envelope.failure = { error: problems.join('\n') };
-    if (contradicted.length) envelope.artifacts = this.artifacts;
 
     if (!test.hasFinished || test.isSkipped) {
       envelope.ok = false;
@@ -982,14 +981,17 @@ export class Prima {
   }
 
   private async successEnvelope(command: string, used: string[], result: ActionResult, previousState: WebPageState | null): Promise<EnvelopeData> {
+    const changes = await this.pageChanges(result, previousState, used[0]);
+    const status = await this.saveStatus(result);
     return {
       ok: true,
       command,
       used,
       page: this.pageBlock(result, previousState),
-      changes: await this.pageChanges(result, previousState, used[0]),
+      changes,
       instance: await this.instanceInfo(),
-      status: await this.saveStatus(result),
+      status,
+      artifacts: this.artifacts,
     };
   }
 
@@ -998,24 +1000,28 @@ export class Prima {
     const failure: EnvelopeData['failure'] = { error: browserErrorMessage(error) };
     if (result.ariaSnapshot) failure.compactAria = compactAriaSnapshot(result.ariaSnapshot, true);
 
+    const status = await this.saveStatus(result);
     return {
       ok: false,
       command,
       page: this.pageBlock(result, previousState),
       failure,
       instance: await this.instanceInfo(),
-      status: await this.saveStatus(result),
+      status,
+      artifacts: this.artifacts,
     };
   }
 
   private async reportEnvelope(command: string, result: ActionResult, previousState: WebPageState | null, outcome: Partial<EnvelopeData>): Promise<EnvelopeData> {
+    const status = await this.saveStatus(result);
     return {
       ok: true,
       command,
       page: this.pageBlock(result, previousState),
       ...outcome,
       instance: await this.instanceInfo(),
-      status: await this.saveStatus(result),
+      status,
+      artifacts: this.artifacts,
     };
   }
 
@@ -1060,9 +1066,16 @@ export class Prima {
   }
 
   async status(hash: string): Promise<EnvelopeData> {
+    if (!this.artifactsDir) {
+      const sites = listSites();
+      const site = sites.find((candidate) => existsSync(path.join(candidate.dir, 'output', 'prima', hash))) || sites[0];
+      if (site && !this.configBaseUrl()) this.sessionUrl = site.url;
+      await this.loadConfig();
+    }
+
     const dir = this.statusDir(hash);
-    const statusFile = path.join(dir, 'status.json');
-    if (!existsSync(statusFile)) return this.toolFailureEnvelope(`status ${hash}`, `No command was recorded under ${hash}. Every envelope prints its own hash on the Instance line.`);
+    const statusFile = path.join(dir, STATUS_FILE);
+    if (!existsSync(statusFile)) return this.toolFailureEnvelope(`status ${hash}`, `No command was recorded under ${dir}. Every envelope prints its own hash on the Instance line.`);
 
     const saved = JSON.parse(readFileSync(statusFile, 'utf-8'));
     return {
@@ -1070,14 +1083,14 @@ export class Prima {
       command: `status ${hash}`,
       page: saved.page,
       instance: await this.instanceInfo(),
-      artifacts: { aria: path.join(dir, 'aria.yml'), html: path.join(dir, 'page.html') },
+      artifacts: readArtifacts(dir),
     };
   }
 
   private async saveStatus(result: ActionResult): Promise<string> {
     const hash = this.statusHash();
     await this.writeSnapshot(result);
-    writeFileSync(path.join(this.statusDir(hash), 'status.json'), JSON.stringify({ page: this.pageBlock(result, null) }), 'utf-8');
+    writeFileSync(path.join(this.statusDir(hash), STATUS_FILE), JSON.stringify({ page: this.pageBlock(result, null) }), 'utf-8');
     return hash;
   }
 

package/dist/bin/explorbot-cli.js

@@ -114,6 +114,7 @@ addCommonOptions(program
     .command('explore <path>')
     .description('Explore a page autonomously and run invented scenarios')
     .option('--max-tests <count>', 'Maximum number of tests to run')
+    .option('--max-duration <minutes>', 'Wall-clock budget in minutes for the whole run; wraps up before the limit is hit')
     .option('--focus <feature>', 'Focus area for exploration')
     .option('--configure <spec>', 'Reuse spec: keys new|from|style|subpages|pick_by|priority, e.g. "new:25%;pick_by=random;priority=critical,high"')
     .option('--dry-run', 'Mark picked tests as skipped without executing or generating new ones')).action(async (explorePath, options) => {
@@ -125,6 +126,10 @@ addCommonOptions(program
         const cmd = new ExploreCommand(explorBot);
         if (options.maxTests)
             cmd.maxTests = Number.parseInt(options.maxTests, 10);
+        if (options.maxDuration)
+            cmd.maxDurationMinutes = Number.parseInt(options.maxDuration, 10);
+        else if (process.env.EXPLORBOT_MAX_DURATION)
+            cmd.maxDurationMinutes = Number.parseInt(process.env.EXPLORBOT_MAX_DURATION, 10);
         if (options.dryRun)
             cmd.dryRun = true;
         const execArgs = [];
@@ -219,13 +224,12 @@ addCommonOptions(program.command('plan <path>').description('Generate test plan
 });
 addCommonOptions(program.command('plan:load <planfile> [index]').description('Load a plan file and display its tests. Pass index to see test details.')).action(async (planfile, index) => {
     try {
-        const resolvedPath = path.resolve(planfile);
-        if (!fs.existsSync(resolvedPath)) {
-            console.error(`Plan file not found: ${resolvedPath}`);
+        const plan = Plan.loadFromFile(planfile);
+        if (!plan?.filePath) {
+            console.error(`Plan file not found: ${planfile}`);
             process.exit(1);
         }
-        const plan = Plan.fromMarkdown(resolvedPath);
-        const planFile = path.basename(resolvedPath);
+        const planFile = path.basename(plan.filePath);
         if (index) {
             const idx = Number.parseInt(index, 10);
             if (Number.isNaN(idx) || idx < 1 || idx > plan.tests.length) {
@@ -236,7 +240,7 @@ addCommonOptions(program.command('plan:load <planfile> [index]').description('Lo
             const lines = [];
             lines.push(`## #${idx} ${test.scenario}\n`);
             lines.push(`**Priority:** ${test.priority}`);
-            const planUrl = plan.url || plan.tests[0]?.startUrl;
+            const planUrl = plan.startUrl;
             if (planUrl)
                 lines.push(`**Plan URL:** ${planUrl}`);
             if (test.startUrl && test.startUrl !== planUrl)
@@ -256,7 +260,7 @@ addCommonOptions(program.command('plan:load <planfile> [index]').description('Lo
             console.log(parseMarkdownToTerminal(lines.join('\n')));
             return;
         }
-        const planUrl = plan.url || plan.tests[0]?.startUrl;
+        const planUrl = plan.startUrl;
         const lines = [`**${plan.title}** (${plan.tests.length} tests)\n`];
         if (planUrl) {
             lines.push(`URL: ${planUrl}\n`);
@@ -284,24 +288,25 @@ addCommonOptions(program.command('plan:load <planfile> [index]').description('Lo
 });
 addCommonOptions(program.command('test <planfile> [index]').description('Execute tests from a plan file. Index: 1, 1,3, 1-5, *, all').option('--grep <pattern>', 'Run tests matching pattern').option('--from-plan <file>', 'Load plan file when the first argument is a test index')).action(async (planfile, index, options) => {
     try {
-        const explorBot = new ExplorBot(buildExplorBotOptions(undefined, options));
-        await explorBot.start();
         let planfileArg = planfile;
         let indexArg = index;
         if (options.fromPlan) {
             planfileArg = options.fromPlan;
             indexArg = planfile;
         }
+        const planTarget = Plan.loadFromFile(planfileArg)?.startUrl;
+        const explorBot = new ExplorBot(buildExplorBotOptions(planTarget, options));
+        await explorBot.start();
         const plan = explorBot.loadPlan(planfileArg);
         const pending = plan.getPendingTests();
         log(`Plan loaded: "${plan.title}" (${plan.tests.length} tests, ${pending.length} pending)`);
-        const startUrl = plan.url || pending[0]?.startUrl;
+        const startUrl = plan.startUrl;
         if (!startUrl) {
             throw new Error('No URL found in plan or tests. Cannot determine where to navigate.');
         }
         log(`Navigating to ${startUrl}`);
         await explorBot.visit(startUrl);
-        let args = '';
+        let args = '*';
         if (indexArg)
             args = indexArg;
         else if (options.grep)
@@ -387,10 +392,11 @@ addCommonOptions(program
     .option('--deep', 'Depth-first: prioritize newly discovered pages')
     .option('--shallow', 'Breadth-first: pick globally least-visited page')
     .option('--scope <prefix>', 'Restrict navigation to URL prefix')
-    .option('--max-tests <count>', 'Maximum number of tests to run')).action(async (startUrl, options) => {
+    .option('--max-tests <count>', 'Maximum number of tests to run')
+    .option('--max-duration <minutes>', 'Wall-clock budget in minutes for the whole run')).action(async (startUrl, options) => {
     const explorBot = new ExplorBot(buildExplorBotOptions(startUrl || '/', options));
     await explorBot.start();
-    const args = [options.deep && '--deep', options.shallow && '--shallow', options.scope && `--scope ${options.scope}`, options.maxTests && `--max-tests ${options.maxTests}`].filter(Boolean).join(' ');
+    const args = [options.deep && '--deep', options.shallow && '--shallow', options.scope && `--scope ${options.scope}`, options.maxTests && `--max-tests ${options.maxTests}`, options.maxDuration && `--max-duration ${options.maxDuration}`].filter(Boolean).join(' ');
     const { FreesailCommand } = await import('../src/commands/freesail-command.js');
     const cmd = new FreesailCommand(explorBot);
     await cmd.execute(args);

package/dist/boat/doc-collector/src/cli.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { Command } from 'commander';
 import { ConfigCommand } from "../../../src/commands/config-command.js";
+import { remote } from "../../../src/remote.js";
 import { isVerboseMode, setPreserveConsoleLogs, setQuietMode } from "../../../src/utils/logger.js";
 import { DocBot } from "./docbot.js";
 function buildOptions(options) {
@@ -50,10 +51,12 @@ export function createDocsCommands(name = 'docs') {
             console.log(`Pages dir: ${path.join(result.outputDir, 'pages')}`);
             console.log(`Use in Explorbot: npx explorbot start ${startPath} --spec "${result.outputDir}"`);
             await bot.stop();
+            await remote.close(0);
             process.exit(0);
         }
         catch (error) {
             console.error('Failed:', error instanceof Error ? error.message : 'Unknown error');
+            await remote.close(1);
             process.exit(1);
         }
     });

package/dist/boat/doc-collector/src/docbot.js

@@ -409,7 +409,9 @@ class DocBot {
     saveIndex(startPath, pages, skipped, maxPages) {
         const outputDir = this.configParser.getOutputDir();
         const indexPath = path.join(outputDir, 'index.md');
-        writeFileSync(indexPath, renderSpecIndex(outputDir, startPath, pages, skipped, maxPages), 'utf8');
+        const index = renderSpecIndex(outputDir, startPath, pages, skipped, maxPages);
+        writeFileSync(indexPath, index, 'utf8');
+        tag('data').log('docs', { path: indexPath, content: index });
         const diagramPath = path.join(outputDir, 'state-diagram.mmd');
         writeFileSync(diagramPath, renderMermaidBody(outputDir, pages), 'utf8');
         return { indexPath, diagramPath };

package/dist/boat/prima/src/cli.js

@@ -29,9 +29,9 @@ const checkHelp = dedent `
               as false.
   Outcomes are settled against a screenshot of the whole page: what a user can see is
   the proof, and the run log only says what was done. CONTRADICTION means the two
-  disagree - reported with both sides rather than settled one way, and ### Artifacts
-  then names the html, aria and screenshot on disk so you can judge it yourself. Not
-  finding something in the picture is not enough on its own; that is "not verified".
+  disagree - reported with both sides rather than settled one way, so read the html,
+  aria and screenshot named under ### Artifacts and judge it yourself. Not finding
+  something in the picture is not enough on its own; that is "not verified".
   ok: follows those outcomes - false when one FAILED or CONTRADICTED, or when the run
   could not complete, which is reported as such rather than as an app failure.
   Page problems seen on the way appear under ### Answer, not as step failures.
@@ -48,6 +48,12 @@ const verifyHelp = dedent `
   and gives no overall verdict - read the lines and decide. "none ran" means the claim
   could not be expressed, which is not the same as false.
 `;
+const statusHelp = dedent `
+  Reads the files a command recorded, so it needs no browser and outlives the session.
+  The hash is looked up across every recorded site. ### Artifacts names every file kept
+  under it: the aria tree, the html, the screenshot and network log when they were
+  captured, and the per-step captures of a do run.
+`;
 const reportHelp = dedent `
   Commands are logged as they run, so the report needs no browser and outlives the session.
   The most recent session is reported unless --pw-session names another.
@@ -114,7 +120,7 @@ function primaFor(options) {
         process.env.EXPLORBOT_VISION_MODEL = options.visionModel;
     return new Prima(buildOptions(options));
 }
-async function runPrima(options, command, run, record = true) {
+async function runPrima(options, command, run) {
     setQuietMode(!isVerboseMode());
     trackActivityLine();
     const prima = primaFor(options);
@@ -127,8 +133,7 @@ async function runPrima(options, command, run, record = true) {
     catch (error) {
         envelope = await prima.toolFailureEnvelope(command, error);
     }
-    if (record)
-        prima.record(envelope, Date.now() - startedAt);
+    prima.record(envelope, Date.now() - startedAt);
     clearActivityLine();
     console.log(renderEnvelope(envelope));
     await prima.stop().catch(() => { });
@@ -191,8 +196,14 @@ export function createPrimaCommands(name = 'prima') {
         await prima.stop().catch(() => { });
         process.exit(0);
     });
-    addCommonOptions(cmd.command('status <hash>').description('Show the artifacts and page detail recorded for an earlier command')).action(async (hash, options) => {
-        await runPrima(options, `status ${hash}`, (prima) => prima.status(hash), false);
+    addCommonOptions(cmd.command('status <hash>').description('Show the artifacts and page detail recorded for an earlier command'))
+        .addHelpText('after', `\n${statusHelp}`)
+        .action(async (hash, options) => {
+        setQuietMode(!isVerboseMode());
+        const prima = primaFor(options);
+        const envelope = await prima.status(hash).catch((error) => prima.toolFailureEnvelope(`status ${hash}`, error));
+        console.log(renderEnvelope(envelope));
+        process.exit(envelope.ok ? 0 : 1);
     });
     addCommonOptions(cmd.command('report').description('Turn every command of a session into one html and markdown report'))
         .addHelpText('after', `\n${reportHelp}`)