@cat-factory/executor-harness 1.132.1 → 1.134.0

package/dist/git.d.ts

@@ -149,9 +149,45 @@ export declare function commitTrackedEdits(dir: string, message: string, signal?
  * --exclude-standard`). The harness deliberately never blanket-stages new files (the
  * agent owns commit selection), so this is exactly what {@link commitTrackedEdits}
  * does NOT capture — a NEW file the agent created but forgot to commit. The caller
- * surfaces it as a warning so that silent loss is at least observable in the logs.
+ * surfaces it as a warning, and the salvage commits it, so that loss is at least observable.
+ *
+ * `-z` for the reason given on {@link splitNulPaths}: the default output C-QUOTES any path git
+ * considers unusual, and a quoted path is not the name of a file. The salvage stages exactly
+ * what this returns, so a single accented filename would make its one `git add` exit 128 and
+ * discard the whole all-or-nothing salvage.
  */
 export declare function listUntrackedFiles(dir: string, signal?: AbortSignal): Promise<string[]>;
+/**
+ * The raw `git status --porcelain -z --untracked-files=all` output for `dir` — every path git
+ * considers changed, with untracked files enumerated INDIVIDUALLY rather than collapsed to their
+ * directory.
+ *
+ * The raw string, not a parsed list, because its two consumers want different things from it and
+ * the parse ({@link changedPathsFromPorcelain}) is pure and shared: the workspace probe wants "is
+ * anything here at all", the salvage wants the paths themselves. Gitignored paths are absent by
+ * construction, which is what keeps a dependency install from reading as agent progress.
+ *
+ * NOTHING IS STAGED, unlike {@link hasAgentChanges}: this runs mid-flight, while the agent is
+ * still working, so a `git add -A` here would silently stage files the agent had not chosen and
+ * change what a later `commitTrackedEdits` captures.
+ */
+export declare function workingTreeStatus(dir: string, signal?: AbortSignal): Promise<string>;
+/**
+ * Stage exactly `paths` and commit them with `message`, returning the new commit's sha (or null
+ * when git found nothing to commit — a path that vanished between listing and staging).
+ *
+ * Three separate things stop a path being read as something other than a path. `--` terminates
+ * the options, so one beginning with `-` cannot be read as a flag. Each path is a separate argv
+ * entry, so no shell ever sees them. And each is prefixed `:(literal)`, which is what `--` does
+ * NOT cover: everything after `--` is a PATHSPEC, not a filename, so its leading `:` is read as
+ * pathspec magic and its wildcards are matched as a glob. An agent-authored `:notes.txt` makes a
+ * bare `git add -- :notes.txt` exit 128 on `did not match any files` — and since this stages every
+ * path in ONE command, that one name discards the whole all-or-nothing salvage, exactly as an
+ * unquoted accented name did. `:(literal)` matches the entry as itself and nothing else.
+ *
+ * The caller has already decided WHICH paths belong; this only commits them.
+ */
+export declare function commitPaths(dir: string, paths: string[], message: string, signal?: AbortSignal): Promise<string | null>;
 /**
  * The untracked, non-ignored paths in the working tree with whole untracked DIRECTORIES
  * collapsed to a single `dir/` entry (`--directory`), rather than every file beneath them.
@@ -233,10 +269,17 @@ export declare function changedFilesSinceBase(dir: string, baseBranch: string, g
  */
 export declare function hasDiffAgainstBase(dir: string, baseBranch: string, signal?: AbortSignal): Promise<boolean>;
 /**
- * Parse the paths out of `git status --porcelain` (v1) output. Each line is
- * `XY <path>`, or `XY <old> -> <new>` for a rename/copy (we keep the new path);
- * git quotes paths with special characters, which we unquote. Blank lines are
- * skipped. Pure so the no-op detection can be tested without spawning git.
+ * Parse the paths out of `git status --porcelain -z` (v1) output.
+ *
+ * `-z` rather than the default, for the reason given on {@link splitNulPaths}: the default
+ * C-QUOTES any path git considers unusual, so `caf\u00e9.ts` arrives as the seven-character
+ * literal `"caf\303\251.ts"` and every consumer that then touches the file misses it. In `-z`
+ * every field is a real path and nothing is escaped.
+ *
+ * Each NUL-terminated field is `XY <path>`. A rename or copy (`R`/`C` in either status column)
+ * spends a SECOND field on its original path, which is consumed and dropped: we keep the new
+ * path, the one that now exists in the tree. Pure so the no-op detection and the workspace
+ * probe's sentinel rule can be tested without spawning git.
  */
 export declare function changedPathsFromPorcelain(status: string): string[];
 /**

package/dist/git.js

@@ -470,14 +470,77 @@ export async function commitTrackedEdits(dir, message, signal) {
  * --exclude-standard`). The harness deliberately never blanket-stages new files (the
  * agent owns commit selection), so this is exactly what {@link commitTrackedEdits}
  * does NOT capture — a NEW file the agent created but forgot to commit. The caller
- * surfaces it as a warning so that silent loss is at least observable in the logs.
+ * surfaces it as a warning, and the salvage commits it, so that loss is at least observable.
+ *
+ * `-z` for the reason given on {@link splitNulPaths}: the default output C-QUOTES any path git
+ * considers unusual, and a quoted path is not the name of a file. The salvage stages exactly
+ * what this returns, so a single accented filename would make its one `git add` exit 128 and
+ * discard the whole all-or-nothing salvage.
  */
 export async function listUntrackedFiles(dir, signal) {
-    const out = await git(['ls-files', '--others', '--exclude-standard'], { cwd: dir, signal });
-    return out
-        .split('\n')
-        .map((line) => line.replace(/\r$/, '').trim())
-        .filter((path) => path !== '');
+    return splitNulPaths(await git(['ls-files', '--others', '--exclude-standard', '-z'], { cwd: dir, signal }));
+}
+/**
+ * Split git's NUL-delimited path output into real, unescaped paths.
+ *
+ * Every path-listing git command here passes `-z`, and this is why: without it git renders a
+ * path containing a non-ASCII byte, a quote, a backslash or a newline as a C-QUOTED STRING
+ * (`"caf\303\251.ts"`), quotes and octal escapes included. That string is not a filename — feed
+ * it back to `git add` and the command exits 128 with `pathspec ... did not match any files`, and
+ * `stat` on it reports nothing. `-z` turns the quoting off entirely (a NUL cannot occur in a path,
+ * so no escaping is needed) and is the ONLY setting that is correct for every path: `core.quotePath
+ * =false` covers the non-ASCII case alone and still quotes the other three.
+ *
+ * A trailing NUL leaves an empty final field, which is dropped along with any other blank.
+ */
+function splitNulPaths(out) {
+    return out.split('\0').filter((path) => path !== '');
+}
+/**
+ * The raw `git status --porcelain -z --untracked-files=all` output for `dir` — every path git
+ * considers changed, with untracked files enumerated INDIVIDUALLY rather than collapsed to their
+ * directory.
+ *
+ * The raw string, not a parsed list, because its two consumers want different things from it and
+ * the parse ({@link changedPathsFromPorcelain}) is pure and shared: the workspace probe wants "is
+ * anything here at all", the salvage wants the paths themselves. Gitignored paths are absent by
+ * construction, which is what keeps a dependency install from reading as agent progress.
+ *
+ * NOTHING IS STAGED, unlike {@link hasAgentChanges}: this runs mid-flight, while the agent is
+ * still working, so a `git add -A` here would silently stage files the agent had not chosen and
+ * change what a later `commitTrackedEdits` captures.
+ */
+export async function workingTreeStatus(dir, signal) {
+    return git(['status', '--porcelain', '-z', '--untracked-files=all'], { cwd: dir, signal });
+}
+/**
+ * Stage exactly `paths` and commit them with `message`, returning the new commit's sha (or null
+ * when git found nothing to commit — a path that vanished between listing and staging).
+ *
+ * Three separate things stop a path being read as something other than a path. `--` terminates
+ * the options, so one beginning with `-` cannot be read as a flag. Each path is a separate argv
+ * entry, so no shell ever sees them. And each is prefixed `:(literal)`, which is what `--` does
+ * NOT cover: everything after `--` is a PATHSPEC, not a filename, so its leading `:` is read as
+ * pathspec magic and its wildcards are matched as a glob. An agent-authored `:notes.txt` makes a
+ * bare `git add -- :notes.txt` exit 128 on `did not match any files` — and since this stages every
+ * path in ONE command, that one name discards the whole all-or-nothing salvage, exactly as an
+ * unquoted accented name did. `:(literal)` matches the entry as itself and nothing else.
+ *
+ * The caller has already decided WHICH paths belong; this only commits them.
+ */
+export async function commitPaths(dir, paths, message, signal) {
+    if (paths.length === 0)
+        return null;
+    await git(['add', '--', ...paths.map(literalPathspec)], { cwd: dir, signal });
+    const staged = await git(['diff', '--cached', '--name-only'], { cwd: dir, signal });
+    if (staged.trim() === '')
+        return null;
+    await git(['commit', '-m', message], { cwd: dir, signal });
+    return headCommit(dir, signal);
+}
+/** One path as a pathspec that matches only itself — see {@link commitPaths} for why. */
+function literalPathspec(path) {
+    return `:(literal)${path}`;
 }
 /**
  * The untracked, non-ignored paths in the working tree with whole untracked DIRECTORIES
@@ -489,11 +552,7 @@ export async function listUntrackedFiles(dir, signal) {
  * and enumerating them would cost a multi-megabyte listing to learn a single name.
  */
 export async function listUntrackedPaths(dir, signal) {
-    const out = await git(['ls-files', '--others', '--exclude-standard', '--directory', '--no-empty-directory'], { cwd: dir, signal });
-    return out
-        .split('\n')
-        .map((line) => line.replace(/\r$/, '').trim())
-        .filter((path) => path !== '');
+    return splitNulPaths(await git(['ls-files', '--others', '--exclude-standard', '--directory', '--no-empty-directory', '-z'], { cwd: dir, signal }));
 }
 /**
  * Locally exclude `pattern` from this checkout via `.git/info/exclude` — a per-clone
@@ -628,24 +687,32 @@ export async function hasDiffAgainstBase(dir, baseBranch, signal) {
     }
 }
 /**
- * Parse the paths out of `git status --porcelain` (v1) output. Each line is
- * `XY <path>`, or `XY <old> -> <new>` for a rename/copy (we keep the new path);
- * git quotes paths with special characters, which we unquote. Blank lines are
- * skipped. Pure so the no-op detection can be tested without spawning git.
+ * Parse the paths out of `git status --porcelain -z` (v1) output.
+ *
+ * `-z` rather than the default, for the reason given on {@link splitNulPaths}: the default
+ * C-QUOTES any path git considers unusual, so `caf\u00e9.ts` arrives as the seven-character
+ * literal `"caf\303\251.ts"` and every consumer that then touches the file misses it. In `-z`
+ * every field is a real path and nothing is escaped.
+ *
+ * Each NUL-terminated field is `XY <path>`. A rename or copy (`R`/`C` in either status column)
+ * spends a SECOND field on its original path, which is consumed and dropped: we keep the new
+ * path, the one that now exists in the tree. Pure so the no-op detection and the workspace
+ * probe's sentinel rule can be tested without spawning git.
  */
 export function changedPathsFromPorcelain(status) {
+    const fields = status.split('\0');
     const paths = [];
-    for (const raw of status.split('\n')) {
-        const line = raw.replace(/\r$/, '');
-        if (line.trim() === '')
+    for (let index = 0; index < fields.length; index++) {
+        const entry = fields[index] ?? '';
+        if (entry === '')
+            continue;
+        // `XY ` then the path. A field too short to hold both is not a status entry (a stray
+        // trailing fragment), so there is no path in it to keep.
+        if (entry.length <= 3)
             continue;
-        let path = line.slice(3);
-        const arrow = path.indexOf(' -> ');
-        if (arrow !== -1)
-            path = path.slice(arrow + 4);
-        path = path.trim().replace(/^"(.*)"$/, '$1');
-        if (path)
-            paths.push(path);
+        if (entry[0] === 'R' || entry[0] === 'C' || entry[1] === 'R' || entry[1] === 'C')
+            index++;
+        paths.push(entry.slice(3));
     }
     return paths;
 }
@@ -658,7 +725,7 @@ export function changedPathsFromPorcelain(status) {
  */
 export async function hasAgentChanges(dir, signal) {
     await git(['add', '-A'], { cwd: dir, signal });
-    const status = await git(['status', '--porcelain'], { cwd: dir, signal });
+    const status = await git(['status', '--porcelain', '-z'], { cwd: dir, signal });
     return changedPathsFromPorcelain(status).length > 0;
 }
 /** The commit SHA at `dir`'s HEAD — captured right after clone as the base tip. */

package/dist/guard-driver.d.ts

@@ -0,0 +1,71 @@
+import { ProgressGuard, type ProgressGuardLimits } from './progress-guard.js';
+import type { WorkspaceProbe } from './workspace-probe.js';
+import { type Logger } from './logger.js';
+/** One run's guard plus the async settlement of the bound the stream alone cannot decide. */
+export interface GuardDriver {
+    /** Feed one tool-call signal (name + error flag) — the claude-code runner's shape. */
+    observeSignal: (tool: {
+        name: string;
+        isError: boolean;
+    }) => void;
+    /** Feed one parsed Pi `--mode json` event; a non-tool-call event is a no-op. */
+    observeEvent: (event: Record<string, unknown>) => void;
+    /** Whether the guard has decided to kill this run. */
+    aborted: () => boolean;
+}
+/**
+ * Drive one run's {@link ProgressGuard}, resolving the one verdict the stream cannot settle.
+ *
+ * An `abort` verdict fires {@link onAbort} immediately: every streak bound (consecutive errors /
+ * web calls / MCP calls / non-action calls) reads only the stream, so the stream is all the
+ * evidence there is.
+ *
+ * A `needs-workspace-evidence` verdict — the no-edit bound — starts a probe of the working tree
+ * and acts on its answer:
+ *
+ *  - MUTATED: the run has changed the repository, whichever tool it used. The bound is satisfied
+ *    permanently, exactly as a recognised edit-tool call satisfies it, so no second probe is ever
+ *    made and the run continues.
+ *  - CLEAN: abort, with the evidence in the message.
+ *  - THREW: inconclusive, which is neither a pass nor a fail. The bound is re-armed (it can trip
+ *    again after another `maxToolCallsWithoutEdit` action calls) and the cause is warned. Failing
+ *    open is deliberate: killing a productive run is the expensive error, and the streak bounds,
+ *    the inactivity watchdog and the wall-clock cap all still hold the run.
+ *
+ * With no probe wired the bound falls back to its old tool-name-only judgement, so a caller with
+ * no checkout to probe is no worse off than before.
+ */
+export declare function createGuardDriver(deps: {
+    guard: ProgressGuard;
+    probe?: WorkspaceProbe | undefined;
+    /** Kill the run with this diagnostic. Called at most once. */
+    onAbort: (reason: string) => void;
+    log?: Logger | undefined;
+}): GuardDriver;
+/** What {@link createClaudeProgressGuard} needs off the run options, and nothing more. */
+export interface ClaudeGuardOptions {
+    guardLimits?: ProgressGuardLimits | undefined;
+    expectsEdits?: boolean | undefined;
+    workspaceProbe?: WorkspaceProbe | undefined;
+    log?: Logger | undefined;
+}
+/**
+ * No-progress guard on the claude-code CLI's own tool stream — the claude-code analogue of runPi's
+ * guard, which cannot see the CLI's internal turns. The caller remembers each `tool_use` id's name
+ * off the assistant turn (`rememberTool`) and hands the following user turn's content to
+ * `feedGuard`, which pairs each `tool_result`'s `is_error` with that name.
+ *
+ * The first abort trips it: the diagnostic is recorded (readable via `reason()`, which the catch
+ * surfaces over the generic abort message) and `guardAbort` fires, folded into streamCli's signal
+ * so a tripped guard kills the CLI the same way the external watchdog does. Disabled when the
+ * caller supplies no limits (only the external watchdog then bounds the run).
+ *
+ * Lives here rather than in `agent-runner.ts` because the async half of it — the workspace probe
+ * behind the no-edit bound — is the same collaborator the Pi runner drives.
+ */
+export declare function createClaudeProgressGuard(opts: ClaudeGuardOptions): {
+    rememberTool: (id: string, name: string) => void;
+    feedGuard: (content: unknown[]) => void;
+    guardAbort: AbortController;
+    reason: () => string | undefined;
+};

package/dist/guard-driver.js

@@ -0,0 +1,171 @@
+import { ProgressGuard } from './progress-guard.js';
+import { log as defaultLog } from './logger.js';
+// The bridge between the SYNCHRONOUS {@link ProgressGuard} and the ASYNCHRONOUS evidence one of
+// its bounds needs. Both runners feed the guard from a sync stream handler (`pi.ts`'s JSONL line
+// reader, `agent-runner.ts`'s tool_result pairing) and neither can await inside one, so the driver
+// owns the probe's lifetime instead. Shared rather than copied per runner: a decision this one
+// ("has the run stopped making progress") must come out the same way on both, which is why
+// `ProgressGuard` itself was extracted in the first place.
+/** The whole cause chain of a thrown value, one line, so a probe failure names what actually broke. */
+function describeCause(error) {
+    const parts = [];
+    let current = error;
+    for (let depth = 0; depth < 8 && current !== undefined && current !== null; depth++) {
+        parts.push(current instanceof Error ? current.message : String(current));
+        current = current instanceof Error ? current.cause : undefined;
+    }
+    return parts.filter((part) => part !== '').join(': ');
+}
+/**
+ * Drive one run's {@link ProgressGuard}, resolving the one verdict the stream cannot settle.
+ *
+ * An `abort` verdict fires {@link onAbort} immediately: every streak bound (consecutive errors /
+ * web calls / MCP calls / non-action calls) reads only the stream, so the stream is all the
+ * evidence there is.
+ *
+ * A `needs-workspace-evidence` verdict — the no-edit bound — starts a probe of the working tree
+ * and acts on its answer:
+ *
+ *  - MUTATED: the run has changed the repository, whichever tool it used. The bound is satisfied
+ *    permanently, exactly as a recognised edit-tool call satisfies it, so no second probe is ever
+ *    made and the run continues.
+ *  - CLEAN: abort, with the evidence in the message.
+ *  - THREW: inconclusive, which is neither a pass nor a fail. The bound is re-armed (it can trip
+ *    again after another `maxToolCallsWithoutEdit` action calls) and the cause is warned. Failing
+ *    open is deliberate: killing a productive run is the expensive error, and the streak bounds,
+ *    the inactivity watchdog and the wall-clock cap all still hold the run.
+ *
+ * With no probe wired the bound falls back to its old tool-name-only judgement, so a caller with
+ * no checkout to probe is no worse off than before.
+ */
+export function createGuardDriver(deps) {
+    const logger = deps.log ?? defaultLog;
+    let aborted = false;
+    let probing = false;
+    const abort = (reason) => {
+        if (aborted)
+            return;
+        aborted = true;
+        deps.onAbort(reason);
+    };
+    const settleFromWorkspace = (provisional) => {
+        const probe = deps.probe;
+        if (!probe) {
+            // No checkout to probe: the tool-name reading is the only evidence there is, so act on it
+            // rather than leaving the bound permanently unenforceable.
+            abort(`${provisional} Aborting before it burns the whole run.`);
+            return;
+        }
+        probing = true;
+        void probe()
+            .then((evidence) => {
+            if (aborted)
+                return;
+            if (evidence.mutated) {
+                deps.guard.noteWorkspaceMutation();
+                logger.info('progress-guard: working tree shows the run IS changing the repository', {
+                    headSha: evidence.headSha,
+                    headMoved: evidence.headMoved,
+                    dirtyPathCount: evidence.dirtyPathCount,
+                });
+                return;
+            }
+            abort(`${provisional} The working tree agrees: at ${evidence.headSha} there is nothing ` +
+                `uncommitted and HEAD has not moved since this pass began, so the repository is ` +
+                `unchanged. Aborting before it burns the whole run.`);
+        })
+            .catch((error) => {
+            if (aborted)
+                return;
+            deps.guard.rearmNoEditBound();
+            logger.warn('progress-guard: workspace probe failed; treating it as inconclusive', {
+                error: describeCause(error),
+            });
+        })
+            .finally(() => {
+            probing = false;
+        });
+    };
+    const act = (verdict) => {
+        if (aborted || !verdict)
+            return;
+        if (verdict.kind === 'needs-workspace-evidence') {
+            // A probe already in flight owns the current question. The guard itself suppresses a second
+            // `needs-workspace-evidence` until one is answered; this is the belt to that braces.
+            if (!probing)
+                settleFromWorkspace(verdict.reason);
+            return;
+        }
+        abort(verdict.reason);
+    };
+    return {
+        observeSignal: (tool) => {
+            if (aborted)
+                return;
+            act(deps.guard.observeSignal(tool));
+        },
+        observeEvent: (event) => {
+            if (aborted)
+                return;
+            act(deps.guard.observe(event));
+        },
+        aborted: () => aborted,
+    };
+}
+/**
+ * No-progress guard on the claude-code CLI's own tool stream — the claude-code analogue of runPi's
+ * guard, which cannot see the CLI's internal turns. The caller remembers each `tool_use` id's name
+ * off the assistant turn (`rememberTool`) and hands the following user turn's content to
+ * `feedGuard`, which pairs each `tool_result`'s `is_error` with that name.
+ *
+ * The first abort trips it: the diagnostic is recorded (readable via `reason()`, which the catch
+ * surfaces over the generic abort message) and `guardAbort` fires, folded into streamCli's signal
+ * so a tripped guard kills the CLI the same way the external watchdog does. Disabled when the
+ * caller supplies no limits (only the external watchdog then bounds the run).
+ *
+ * Lives here rather than in `agent-runner.ts` because the async half of it — the workspace probe
+ * behind the no-edit bound — is the same collaborator the Pi runner drives.
+ */
+export function createClaudeProgressGuard(opts) {
+    const toolNames = new Map();
+    const guardAbort = new AbortController();
+    let guardReason;
+    const limits = opts.guardLimits;
+    const driver = limits
+        ? createGuardDriver({
+            guard: new ProgressGuard(limits, opts.expectsEdits ?? true),
+            probe: opts.workspaceProbe,
+            log: opts.log,
+            onAbort: (reason) => {
+                guardReason = reason;
+                guardAbort.abort();
+            },
+        })
+        : undefined;
+    const feedGuard = (content) => {
+        if (!driver || driver.aborted())
+            return;
+        for (const block of content) {
+            if (!isRecord(block) || block.type !== 'tool_result')
+                continue;
+            const id = typeof block.tool_use_id === 'string' ? block.tool_use_id : undefined;
+            const name = id ? toolNames.get(id) : undefined;
+            if (id)
+                toolNames.delete(id);
+            if (!name)
+                continue;
+            driver.observeSignal({ name, isError: block.is_error === true });
+            if (driver.aborted())
+                return;
+        }
+    };
+    return {
+        rememberTool: (id, name) => toolNames.set(id, name),
+        feedGuard,
+        guardAbort,
+        reason: () => guardReason,
+    };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}

package/dist/harness-server.js

@@ -5,6 +5,7 @@ import { parseAgentJob, parseInlineJob } from './job.js';
 import { handleAgent } from './agent.js';
 import { handleInline } from './inline.js';
 import { redactSecrets } from './git.js';
+import { readDockerStatus } from './docker-status.js';
 import { JobRegistry, loadRunnerLimits } from './runner.js';
 import { log } from './logger.js';
 import { HARNESS_VERSION } from './version.js';
@@ -109,10 +110,22 @@ const server = createServer((req, res) => {
             // fail loudly early (see version.ts). Unauthenticated like the rest of /health — the
             // version is not a secret. An old image predating this field simply omits it, which the
             // backend treats as a stale signal.
+            //
+            // `docker` is this container's own verdict on its daemon (see docker-status.ts). It rides
+            // /health because that is where an operator and a boot-time probe already look, and because
+            // the alternative was every agent discovering an absent daemon for itself, one failed
+            // compose command at a time. Reported, never enforced here: what REFUSES on it is the
+            // stand-up in agent.ts, which is the only place that knows a job wanted a daemon.
+            //
+            // Deliberately the BOOT record, not a live probe. /health is polled, and a probe per poll
+            // would spawn a process per poll to answer a question this endpoint is not the one to act
+            // on; the stand-up re-confirms a recorded absence at the moment it matters
+            // (`resolveDockerVerdict`), so a stale negative here never becomes a stale refusal there.
             return send(res, 200, {
                 status: 'ok',
                 ...(HARNESS_VERSION ? { version: HARNESS_VERSION } : {}),
                 capabilities: HARNESS_BODY_CAPABILITIES,
+                docker: await readDockerStatus(),
             });
         }
         // All non-health endpoints are gated by the optional shared secret.

package/dist/infra-standup.d.ts

@@ -0,0 +1,69 @@
+import type { AgentInfraSpec, InfraSetupRecord, ServiceInfraSpec } from './job.js';
+import { type DockerProbe } from './docker-status.js';
+import type { RunOptions } from './runner.js';
+import type { Logger } from './logger.js';
+/**
+ * Bring the service's docker-compose dependencies up (local infra only). Best-effort:
+ * runs `docker compose -f <path> up -d --wait` in the checkout. A compose failure is logged
+ * and surfaced to the agent (as a prompt note) rather than failing the job — the agent can
+ * still run unit-level tests and report what it could. A no-op for ephemeral / no-infra /
+ * no-compose-path runs.
+ *
+ * A CONFIRMED absence of a Docker daemon short-circuits it: the container's own probe
+ * ({@link readDockerStatus}, recorded by `entrypoint.sh`) already knows there is nothing to
+ * talk to, so running compose against it would only turn a fact this container holds into a
+ * connection error the agent has to interpret. The record then carries `dockerAvailable: false`
+ * and the stated cause, which is what makes the Tester step say why it ran no infra instead of
+ * looking like a Tester that simply chose not to. Anything OTHER than a confirmed absence
+ * attempts as before (`DockerStatus.available` in docker-status.ts states why "undecided" is its
+ * own value).
+ *
+ * "Confirmed", not merely recorded: {@link resolveDockerVerdict} re-checks a recorded absence
+ * against a live daemon first, so a warm-pool container whose sidecar came up late is not
+ * latched into refusing infra that works. `probe` is that check, injected so the unit suite can
+ * state both answers on a machine that has its own daemon either way.
+ *
+ * Whether it succeeds or fails, the (redacted, bounded) command output is captured into a
+ * {@link InfraSetupRecord} returned alongside the prompt `note`, so the backend can surface
+ * the in-container dependency stand-up logs on the Tester step — the failure-class artifact
+ * the orchestrator-side provisioning logs can't see.
+ *
+ * Exported for the unit suite (like {@link buildInfraNotes}): the refusal branch is a decision
+ * this container makes about itself, and the acceptance suite can only exercise it on a machine
+ * where the daemon genuinely fails.
+ */
+export declare function standUpInfra(dir: string, infra: ServiceInfraSpec, signal: AbortSignal | undefined, logger: Logger, probe?: DockerProbe): Promise<{
+    started: boolean;
+    note?: string;
+    record?: InfraSetupRecord;
+}>;
+/**
+ * Stand the run's infra up and return a single cleanup handle, dispatching on the spec's
+ * `kind`: the frontend UI-test flow (`kind: 'frontend'`) builds/serves the app + WireMock as
+ * processes (torn down by killing them); the default backend-service flow stands the
+ * docker-compose stack up (torn down with `docker compose down`). Unifying the two here keeps
+ * `runExploreMode` free of the branch and guarantees the matching teardown runs in its finally.
+ *
+ * `dir` is the clone ROOT; `workDir` is the service subtree (equal to `dir` when the run is not
+ * monorepo-scoped). The docker-compose stand-up runs at the root (its `composePath` is
+ * repo-relative), but the FRONTEND stand-up runs in `workDir`: a monorepo frontend's
+ * `package.json` / `outputDir` / `mocks/` all live under the service subtree, so installing,
+ * building, serving and seeding WireMock from the root would target the wrong directory.
+ */
+export declare function manageInfra(dir: string, workDir: string, infra: AgentInfraSpec, opts: RunOptions, logger: Logger): Promise<{
+    note?: string;
+    serveUrl?: string;
+    record?: InfraSetupRecord;
+    cleanup: () => Promise<void>;
+}>;
+/**
+ * Build the dynamic infra notes appended to the agent's user prompt from a stand-up outcome.
+ * A stand-up problem (a failed build / compose) is flagged as a concern to test around; a
+ * frontend serve URL points the UI tester at the app that was just built + served and pre-empts
+ * a live-backend CORS failure being mis-reported as an app defect. Pure (no IO) so the exact
+ * wording + ordering is unit-tested; returns the notes in order (problem first, serve URL next).
+ */
+export declare function buildInfraNotes(managed: {
+    note?: string;
+    serveUrl?: string;
+}): string[];