@molecule/api-ai-tools 1.9.16 → 1.9.18

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-10-18T12:49:51.606Z
+Generated: 2026-10-18T15:48:52.035Z
 -->
 
 # @molecule/api-ai-tools
@@ -309,6 +309,17 @@ interface ToolSchema {
 }
 ```
 
+#### `ForegroundServer`
+
+A foreground command that starts a server, as the refusal names it.
+
+```typescript
+interface ForegroundServer {
+  /** The program (and script, when there is one) that serves. */
+  readonly program: string
+}
+```
+
 #### `LeadingSleep`
 
 The leading `sleep` a command opens with, and the command that follows it.
@@ -345,6 +356,20 @@ interface SuiteRunInFlight {
 }
 ```
 
+#### `DiagnosisRunContext`
+
+What a caller knows about the run being judged beyond its command text.
+
+```typescript
+interface DiagnosisRunContext {
+  /**
+   * The test titles the person's request excludes by name — the same reading molecule-dev's
+   * `excludedTestTitles` gives the rest of the platform.
+   */
+  approvedExclusions?: readonly string[]
+}
+```
+
 #### `InstalledPackageFacts`
 
 What the filesystem says about a write target under `node_modules` — the half
@@ -512,6 +537,30 @@ interface TraceContextEvidence {
 }
 ```
 
+#### `TraceMissingText`
+
+The text a failing assertion waited for that a same-page API response carried and the page never
+rendered.
+
+The assertion's own error names the text (a `has-text(…)` / `getByText(…)` / `toContainText(…)`
+argument), and the trace's network log holds the response that contained it. That pair is the
+whole diagnosis: the API returned the value and the page dropped it before rendering, so the cut
+is in the component that maps the response onto the list — not in the API, the route or the
+selector. xr-molecule-flash-m169 (+13:09) spent its fix rounds on the wrong component and on a
+markup detail while `GET /api/tags` was returning the missing "trending" and `PopularTags`
+sliced the response to its first 20 entries (the m99 top-N class, in the frontend).
+
+```typescript
+interface TraceMissingText {
+  /** The text the assertion waited for (`trending`). */
+  text: string
+  /** The method of the response that carried it (`GET`). */
+  method: string
+  /** The path of the response that carried it (`/api/tags`). */
+  path: string
+}
+```
+
 #### `TraceArtifact`
 
 What one trace says: the test it belongs to, the requests it made, and its console lines.
@@ -581,6 +630,17 @@ interface TraceArtifact {
    * and on traces read before this field existed.
    */
   otherContexts?: TraceContextEvidence[]
+  /**
+   * The text the failing assertion waited for and a same-page API response carried, when the trace
+   * recorded both. The note leads with it: the value reached the browser and the page did not
+   * render it, so the next read is where that response is mapped — never the API or the selector
+   * (xr-molecule-flash-m169).
+   *
+   * Absent when the assertion waited for no text (a text-free selector, a strict-mode violation),
+   * when no page-scoped `fetch`/`xhr` answered 2xx/3xx with the text in its body, and on traces
+   * read before this field existed.
+   */
+  missingText?: TraceMissingText
 }
 ```
 
@@ -627,6 +687,14 @@ interface TraceRunReport {
    * contradicts it.
    */
   productionBuildAdvised?: boolean
+  /**
+   * The endpoints the app's own auth config names for a credential exchange — a login, a
+   * registration, a token endpoint (`loginEndpoint: '/users/login'`, resolved from the app's
+   * source). A 401/403 there answers credentials the app was ASKED to check, never a token the
+   * client failed to attach, so the note says so even when the path is mounted somewhere unusual.
+   * Empty when the caller could not read the app's config.
+   */
+  authEndpoints?: readonly string[]
 }
 ```
 
@@ -695,6 +763,33 @@ interface ExecutionBackend {
 }
 ```
 
+#### `SuiteBudgetPin`
+
+The supplied suite's own settings, put back on a run whose runner config changes them.
+
+A graded suite is walked by the grader under its own per-test budget, worker count and
+timeouts. An executor's run that reads a config setting different numbers measures a run the
+grader never sees: a shorter budget fails tests the graded walk passes, a longer one passes
+tests the graded walk times out on. The platform that knows the suite supplies these values
+before the run ({@link ToolBuildConfig.suiteBudget}); the shared tool puts the flags on the
+runner's own command line, where Playwright lets them win over every config file.
+
+```typescript
+interface SuiteBudgetPin {
+  /**
+   * The Playwright flags that carry the suite's own settings onto the command
+   * (`--timeout=15000`, `--workers=1`), as the consumer's own scan reads them. Empty when the
+   * difference is in settings no flag carries — the pin is then the sentence alone.
+   */
+  flags: string[]
+  /**
+   * One sentence for the run's result: this run uses the suite's own budget, and which settings
+   * a config keeps because Playwright has no flag for them.
+   */
+  note: string
+}
+```
+
 #### `ToolBuildConfig`
 
 Configuration for building the tool set.
@@ -802,6 +897,23 @@ interface ToolBuildConfig {
    */
   excludedTestTitles?: () => readonly string[]
 
+  /**
+   * The supplied suite's own budget, when the Playwright config a command would load sets
+   * different settings, asked BEFORE the run executes. The consumer knows where the suite and its
+   * base config live; this shared package does not, so the reading is the consumer's and the
+   * mechanics — putting the flags on the runner's own arguments, before the pipeline and outside
+   * any redirect or group closer — are this tool's.
+   *
+   * Called for a Playwright suite command only, and only the LAST suite step is touched. A run
+   * that already keeps the suite's settings, or a sandbox with no supplied suite, answers `null`.
+   * Unset (or a hook that throws) changes nothing: the command runs as the model wrote it.
+   *
+   * @param command - The shell command, as the model sent it.
+   * @param cwd - The resolved working directory it will run in.
+   * @returns The flags and the sentence, or null when nothing is put back.
+   */
+  suiteBudget?: (command: string, cwd: string) => Promise<SuiteBudgetPin | null | undefined>
+
   /** Post-write hook (e.g. auto-format via Prettier/ESLint). Called after every write_file/edit_file. */
   onAfterWrite?: (path: string) => Promise<void>
 
@@ -1583,7 +1695,7 @@ function commandRunsNoTests(command: string): boolean
 
 **Returns:** True when the command invokes a runner only to print.
 
-#### `outputFilterAfterRunner(command, runs)`
+#### `outputFilterAfterRunner(command, runs, occurrence)`
 
 The output filter that follows the runner in `command`, or null when there is none.
 
@@ -1596,11 +1708,13 @@ middle stage were cut out, so a chain is not answered here at all. A filter befo
 function outputFilterAfterRunner(
   command: string,
   runs: (segment: CommandSegment) => boolean,
+  occurrence?: number,
 ): RunnerOutputFilter | null
 ```
 
 - `command` — The command as the executor sent it.
 - `runs` — Whether a segment is the runner this run is about (the caller knows its own kind: {@link CommandSegment.program} is the program, once wrapper words like `timeout 280` and `npx` are taken away).
+- `occurrence` — Which runner invocation the output belongs to, 1-based. A command can run the same runner more than once (xr-molecule-flash-m170: the suite bare, then with `HOST=…`), and each invocation carries its OWN pipe; a reader judging the second walk must name the second walk's cut, never the first's.
 
 **Returns:** The filter and the unfiltered command, or null.
 
@@ -1628,6 +1742,56 @@ function pipelineExitCodeNote(command: string, exitCode: number, output: string)
 
 **Returns:** One sentence naming the stage the code came from, or null.
 
+#### `startsServerProgram(command)`
+
+Whether a command, read from its TEXT alone, starts a server that stays up in the foreground.
+
+The over-budget reader's shape: at that point the command has already run, and only its text is
+left to say whether "run a smaller unit" was ever the right advice.
+
+```typescript
+function startsServerProgram(command: string): boolean
+```
+
+- `command` — The command as the executor sent it.
+
+**Returns:** True when a foreground statement of the command starts a server.
+
+#### `foregroundServerCommand(command, readScript)`
+
+A FOREGROUND command that starts a server, including one that only names a script whose SOURCE
+imports the app's server and calls its `create()`/`listen()`.
+
+The script read is best-effort: a path the backend will not answer for is a command this reading
+cannot classify, never a refusal. A backgrounded launch, a test runner and a test file are all
+left alone.
+
+```typescript
+function foregroundServerCommand(
+  command: string,
+  readScript: (path: string) => Promise<string>,
+): Promise<ForegroundServer | null>
+```
+
+- `command` — The command as the executor sent it.
+- `readScript` — Reads a script file the command names (`backend.readFile`).
+
+**Returns:** The serving program, or null when the command starts no server in the foreground.
+
+#### `serverCommandRefusal(server, budgetSeconds)`
+
+The refusal for a foreground command that starts a server: why it would never return, and the
+two shapes that do work — a background launch, or a probe of the API already running.
+
+```typescript
+function serverCommandRefusal(server: ForegroundServer, budgetSeconds: number): string
+```
+
+- `server` — The serving program, from {@link foregroundServerCommand}.
+- `budgetSeconds` — The tool's budget, which a foreground server would consume whole.
+
+**Returns:** The refusal sentence.
+
 #### `leadingSleepPeek(command)`
 
 The leading `sleep` of a command, when the first statement is one and it asks for at least
@@ -1765,7 +1929,7 @@ function suiteRunInTheWay(candidate: { target: string }, inFlight: readonly T[])
 
 **Returns:** The first run in the way, or null.
 
-#### `isDiagnosisRun(command)`
+#### `isDiagnosisRun(command, context)`
 
 Whether a command walks a PART of a suite instead of all of it: a cap that stops it at a failure
 count, the failures the last run printed (`--last-failed`, `--only-changed`), a title filter, or
@@ -1794,10 +1958,11 @@ absorb it).
 _(description truncated — read the full text in `node_modules/@molecule/api-ai-tools/dist/suite-overlap.d.ts`.)_
 
 ```typescript
-function isDiagnosisRun(command: string): boolean
+function isDiagnosisRun(command: string, context?: DiagnosisRunContext): boolean
 ```
 
 - `command` — The command as the executor sent it.
+- `context` — The request's approved exclusions, when the caller knows them.
 
 **Returns:** True when the run is a diagnosis or a re-run, not the whole suite.
 
@@ -2126,15 +2291,21 @@ function suiteRecordsTraces(configText: string): boolean
 
 #### `diagnosisTraceCommand(args)`
 
-The command a DIAGNOSIS run needs to leave a readable trace behind, when the suite's config
+The command a Playwright run needs to leave a readable trace behind, when the suite's config
 would record none.
 
 The failing tests' requests are only readable if the run wrote them down (see the module doc),
 and the config is where the decision about that lives — the platform does not edit the suite's
-config, so it passes the flag instead, and only where it can do no harm: on a run narrowed to a
-part of the suite or capped ({@link isDiagnosisRun}), never on the whole-suite proof run, and
-never over a `--trace` the executor wrote itself. A capped walk is exactly the run whose
-failures someone is about to work on; the proof run is graded as it is.
+config, so it passes the flag instead, on every Playwright run that starts tests and does not
+already decide its own `--trace`. That includes the whole-suite proof run, which an earlier
+version of this function skipped on the reasoning that its flags are graded: the flag changes
+what is RETAINED, not what passes. `retain-on-failure` keeps the trace only of a test that
+fails — Playwright records it and deletes it when the test passes (playwright's
+`_shouldAbandonTrace` unlinks the temporary trace files of a passing test) — so a green proof
+run keeps nothing extra. A failing one keeps the network log its failures need.
+xr-molecule-flash-m163 (+24:58) is why the proof run is no longer skipped: its one deployed
+failure left only an `error-context.md`, the executor spent the next calls hunting a `trace.zip`
+that could not exist, and then shipped a guessed fix.
 
 ```typescript
 function diagnosisTraceCommand(args: {
@@ -2310,7 +2481,7 @@ function outputRedirectTarget(command: string): string | null
 
 **Returns:** The target, or null (`/dev/null` and `&1`/`&2` are not files).
 
-#### `streamingBackgroundCommand(command)`
+#### `streamingBackgroundCommand(command, context)`
 
 Rewrite a command about to run in the background so its log grows while it
 runs. Two shapes left the log empty until exit, and an empty log is what
@@ -2336,14 +2507,14 @@ into the log twice, which on X1 flash-m83 (2026-10-16) made a `--reporter=list,l
 _(description truncated — read the full text in `node_modules/@molecule/api-ai-tools/dist/utilities.d.ts`.)_
 
 ```typescript
-function streamingBackgroundCommand(command: string): {
-  command: string
-  changes: string[]
-  error?: string
-}
+function streamingBackgroundCommand(
+  command: string,
+  context?: DiagnosisRunContext,
+): { command: string; changes: string[]; error?: string }
 ```
 
 - `command` — The command as the executor sent it.
+- `context` — What the caller knows beyond the command: the tests the person's request excludes by name ({@link DiagnosisRunContext}). A `--grep-invert` of exactly those is the request's own scope, not a diagnosis, so it keeps the suite's retries on a deployed proof (xr-molecule-flash-m170 +33:16).
 
 **Returns:** The command to run and one sentence per change made (empty when none), or `error` when the command starts the suite more than once.
 
@@ -2381,6 +2552,61 @@ function isSuiteRunCommand(command: string): boolean
 
 **Returns:** True when the command starts one of those runners.
 
+#### `repeatedSuiteRunError(command)`
+
+The refusal for a command that starts the suite MORE THAN ONCE — the ONE reading every launch
+site asks, foreground and background alike.
+
+Each statement is a whole walk of the same suite against the same app, and only the last of them
+is rewritten, so the earlier ones measure nothing the first did. X1 xr-molecule-flash-m157
+(+14:02) chained two whole walks of one 138-test suite with `;` (4.5 minutes each) and the
+background launcher refused it; X1 xr-molecule-flash-m170 (+06:02) chained two invocations of the
+suite's own runner script in the foreground, where nothing counted them, and the note reported
+the passing second walk as the first walk's 13 failures.
+
+The one run handed back is the LAST suite statement, rewritten exactly as
+{@link streamingBackgroundCommand} rewrites a run (a filter or `| tail` after the runner is
+dropped, and a Playwright run gets the reporter that prints failures). Its own count is one —
+guarded, so this cannot recurse.
+
+```typescript
+function repeatedSuiteRunError(command: string): string | null
+```
+
+- `command` — The shell command as the executor sent it.
+
+**Returns:** The refusal sentence, or null when the command starts the suite zero or one time.
+
+#### `suiteRunBudgetCommand(command, flags)`
+
+A command with the supplied suite's own settings written back onto its runner as Playwright
+flags, and the flags that could not be placed.
+
+The grader walks the suite under its OWN budget, so a run whose runner config sets a different
+timeout or worker count measures a run the grader never sees (xr-molecule-flash-m169: a 60 s
+wrapper config produced a green local proof the official 15 s grader then failed). Playwright
+lets a command-line flag win over every config file, so the suite's values are put on the
+runner's own arguments — written where {@link statementArgumentEnd} places them, never after a
+pipe, redirect or group closer. Only the command's LAST suite step is touched: that is the run
+every launch site measures.
+
+A flag the command already carries is REWRITTEN in place (last occurrence wins, as it does for
+Playwright); a flag it does not carry is inserted at the end of the runner's arguments. A
+command whose runner cannot be placed is returned exactly as written, with every flag reported
+as unplaced, so the caller states the fact instead of claiming a pin it did not make.
+
+```typescript
+function suiteRunBudgetCommand(
+  command: string,
+  flags: readonly string[],
+): { command: string; placed: string[]; unplaced: string[] }
+```
+
+- `command` — The shell command about to run.
+- `flags` — The flags to put on it, each as `--name=value`.
+
+**Returns:** The command to run, the flags placed on it, and the ones it could not carry.
+
 #### `withoutSuiteTimeout(command)`
 
 The command with the `timeout <N>` wrapper lifted off the statement that runs the suite, and the
@@ -3323,6 +3549,35 @@ Canonical tool schemas shared by the agent runtime and documentation.
 const TOOL_SCHEMAS: Record<string, ToolSchema>
 ```
 
+#### `BACKGROUNDED`
+
+A background launch: a single `&` (not `&&`, not a `2>&1`) or an explicit detacher. A
+backgrounded launch never holds the tool, so every reading here stops at it.
+
+```typescript
+const BACKGROUNDED: RegExp
+```
+
+#### `SERVER_PROGRAM`
+
+A program that SERVES: the scaffold's entry (`server.ts`/`server.js`), a package manager's
+`start`/`dev`/`serve`/`preview` script, a Vite dev or preview server, `next start|dev`, or a
+Python WSGI server. Matched against a command segment's own text, and against a script's SOURCE
+when the command only names the script file.
+
+```typescript
+const SERVER_PROGRAM: RegExp
+```
+
+#### `SERVER_OVER_BUDGET_ADVICE`
+
+The closing advice on an over-budget message for a command recognised as a server start: there
+is no tally to split, and the run has to leave the foreground budget to keep serving.
+
+```typescript
+const SERVER_OVER_BUDGET_ADVICE: string
+```
+
 #### `MIN_PEEK_SLEEP_SECONDS`
 
 The shortest leading sleep the platform drops: below it the wall clock it costs is noise, and a

package/dist/index.d.ts

@@ -141,6 +141,7 @@ export * from './no-test-run.js';
 export * from './output-filter.js';
 export * from './pipeline-exit-note.js';
 export * from './schemas.js';
+export * from './server-command.js';
 export * from './sleep-peek.js';
 export * from './suite-overlap.js';
 export * from './system-prompt.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkIG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,cAAc,CAAA;AAC5B,cAAc,mBAAmB,CAAA;AACjC,cAAc,uBAAuB,CAAA;AACrC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,kBAAkB,CAAA;AAChC,cAAc,oBAAoB,CAAA;AAClC,cAAc,yBAAyB,CAAA;AACvC,cAAc,cAAc,CAAA;AAC5B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAC1B,cAAc,sBAAsB,CAAA;AACpC,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkIG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,cAAc,CAAA;AAC5B,cAAc,mBAAmB,CAAA;AACjC,cAAc,uBAAuB,CAAA;AACrC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,kBAAkB,CAAA;AAChC,cAAc,oBAAoB,CAAA;AAClC,cAAc,yBAAyB,CAAA;AACvC,cAAc,cAAc,CAAA;AAC5B,cAAc,qBAAqB,CAAA;AACnC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAC1B,cAAc,sBAAsB,CAAA;AACpC,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}

package/dist/index.js

@@ -141,6 +141,7 @@ export * from './no-test-run.js';
 export * from './output-filter.js';
 export * from './pipeline-exit-note.js';
 export * from './schemas.js';
+export * from './server-command.js';
 export * from './sleep-peek.js';
 export * from './suite-overlap.js';
 export * from './system-prompt.js';

package/dist/output-filter.d.ts

@@ -42,7 +42,11 @@ export interface RunnerOutputFilter {
  * @param runs - Whether a segment is the runner this run is about (the caller knows its own kind:
  *   {@link CommandSegment.program} is the program, once wrapper words like `timeout 280` and
  *   `npx` are taken away).
+ * @param occurrence - Which runner invocation the output belongs to, 1-based. A command can run
+ *   the same runner more than once (xr-molecule-flash-m170: the suite bare, then with `HOST=…`),
+ *   and each invocation carries its OWN pipe; a reader judging the second walk must name the
+ *   second walk's cut, never the first's.
  * @returns The filter and the unfiltered command, or null.
  */
-export declare function outputFilterAfterRunner(command: string, runs: (segment: CommandSegment) => boolean): RunnerOutputFilter | null;
+export declare function outputFilterAfterRunner(command: string, runs: (segment: CommandSegment) => boolean, occurrence?: number): RunnerOutputFilter | null;
 //# sourceMappingURL=output-filter.d.ts.map

package/dist/output-filter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"output-filter.d.ts","sourceRoot":"","sources":["../src/output-filter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,KAAK,cAAc,EAA0B,MAAM,uBAAuB,CAAA;AASnF,4FAA4F;AAC5F,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAA;IACb,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,GACzC,kBAAkB,GAAG,IAAI,CAkB3B"}
+{"version":3,"file":"output-filter.d.ts","sourceRoot":"","sources":["../src/output-filter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,KAAK,cAAc,EAA0B,MAAM,uBAAuB,CAAA;AASnF,4FAA4F;AAC5F,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAA;IACb,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,EAC1C,UAAU,SAAI,GACb,kBAAkB,GAAG,IAAI,CAsB3B"}

package/dist/output-filter.js

@@ -35,14 +35,23 @@ const CUTTING_FILTERS = new Set(['awk', 'cut', 'grep', 'head', 'sed', 'tail']);
  * @param runs - Whether a segment is the runner this run is about (the caller knows its own kind:
  *   {@link CommandSegment.program} is the program, once wrapper words like `timeout 280` and
  *   `npx` are taken away).
+ * @param occurrence - Which runner invocation the output belongs to, 1-based. A command can run
+ *   the same runner more than once (xr-molecule-flash-m170: the suite bare, then with `HOST=…`),
+ *   and each invocation carries its OWN pipe; a reader judging the second walk must name the
+ *   second walk's cut, never the first's.
  * @returns The filter and the unfiltered command, or null.
  */
-export function outputFilterAfterRunner(command, runs) {
+export function outputFilterAfterRunner(command, runs, occurrence = 1) {
     if (typeof command !== 'string' || command.trim() === '')
         return null;
     const entries = locatedCommandSegments(command);
-    const runnerAt = entries.findIndex((entry) => entry.segment !== null && runs(entry.segment));
-    if (runnerAt < 0 || runnerAt + 1 >= entries.length)
+    const runners = [];
+    entries.forEach((entry, index) => {
+        if (entry.segment !== null && runs(entry.segment))
+            runners.push(index);
+    });
+    const runnerAt = runners[occurrence - 1];
+    if (runnerAt === undefined || runnerAt + 1 >= entries.length)
         return null;
     const runner = entries[runnerAt];
     const filter = entries[runnerAt + 1];

package/dist/server-command.d.ts

@@ -0,0 +1,73 @@
+/**
+ * "This command starts a server, and a server never exits" — ONE reading of a server launch,
+ * shared by the `exec_command` refusal, the over-budget advice, and the platform's own-server note
+ * (`molecule-dev/api/src/ai/own-server-note.ts` imports {@link SERVER_PROGRAM} and
+ * {@link BACKGROUNDED} from here), so every surface that names a server names the same commands.
+ *
+ * X1 xr-molecule-flash-m167 (+19:16 → +24:04) wrote `/tmp/probe.mts` whose body imports the app's
+ * `api/src/server.ts` and calls its `create(0)`, then ran it in the FOREGROUND:
+ * `npx tsx --env-file=.env /tmp/probe.mts 2>&1 | tail -15`. The scaffold's `create()` calls
+ * `server.listen(port)` and returns the server, so the process never exits — and behind `| tail`
+ * it printed nothing until it did. The tool waited its whole 290 s budget and answered with "run
+ * a smaller unit", advice about the wrong axis for a process that was never going to return.
+ *
+ * A server started in the background is a different thing: it is the launch the platform records
+ * and hands a task id for, and the over-budget advice below keeps it off the foreground budget.
+ *
+ * @module
+ */
+/**
+ * A background launch: a single `&` (not `&&`, not a `2>&1`) or an explicit detacher. A
+ * backgrounded launch never holds the tool, so every reading here stops at it.
+ */
+export declare const BACKGROUNDED: RegExp;
+/**
+ * A program that SERVES: the scaffold's entry (`server.ts`/`server.js`), a package manager's
+ * `start`/`dev`/`serve`/`preview` script, a Vite dev or preview server, `next start|dev`, or a
+ * Python WSGI server. Matched against a command segment's own text, and against a script's SOURCE
+ * when the command only names the script file.
+ */
+export declare const SERVER_PROGRAM: RegExp;
+/**
+ * Whether a command, read from its TEXT alone, starts a server that stays up in the foreground.
+ *
+ * The over-budget reader's shape: at that point the command has already run, and only its text is
+ * left to say whether "run a smaller unit" was ever the right advice.
+ *
+ * @param command - The command as the executor sent it.
+ * @returns True when a foreground statement of the command starts a server.
+ */
+export declare function startsServerProgram(command: string): boolean;
+/** A foreground command that starts a server, as the refusal names it. */
+export interface ForegroundServer {
+    /** The program (and script, when there is one) that serves. */
+    readonly program: string;
+}
+/**
+ * A FOREGROUND command that starts a server, including one that only names a script whose SOURCE
+ * imports the app's server and calls its `create()`/`listen()`.
+ *
+ * The script read is best-effort: a path the backend will not answer for is a command this reading
+ * cannot classify, never a refusal. A backgrounded launch, a test runner and a test file are all
+ * left alone.
+ *
+ * @param command - The command as the executor sent it.
+ * @param readScript - Reads a script file the command names (`backend.readFile`).
+ * @returns The serving program, or null when the command starts no server in the foreground.
+ */
+export declare function foregroundServerCommand(command: string, readScript: (path: string) => Promise<string>): Promise<ForegroundServer | null>;
+/**
+ * The refusal for a foreground command that starts a server: why it would never return, and the
+ * two shapes that do work — a background launch, or a probe of the API already running.
+ *
+ * @param server - The serving program, from {@link foregroundServerCommand}.
+ * @param budgetSeconds - The tool's budget, which a foreground server would consume whole.
+ * @returns The refusal sentence.
+ */
+export declare function serverCommandRefusal(server: ForegroundServer, budgetSeconds: number): string;
+/**
+ * The closing advice on an over-budget message for a command recognised as a server start: there
+ * is no tally to split, and the run has to leave the foreground budget to keep serving.
+ */
+export declare const SERVER_OVER_BUDGET_ADVICE: string;
+//# sourceMappingURL=server-command.d.ts.map

package/dist/server-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-command.d.ts","sourceRoot":"","sources":["../src/server-command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH;;;GAGG;AACH,eAAO,MAAM,YAAY,QAA6C,CAAA;AAEtE;;;;;GAKG;AACH,eAAO,MAAM,cAAc,QACmP,CAAA;AAmF9Q;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAI5D;AAED,0EAA0E;AAC1E,MAAM,WAAW,gBAAgB;IAC/B,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GAC5C,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAmBlC;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAO5F;AAED;;;GAGG;AACH,eAAO,MAAM,yBAAyB,QAG0B,CAAA"}