@itookit/dsht 0.3.8 → 0.5.2

package/dist/catalog/controller.js

@@ -1,88 +1,116 @@
 import { array, errorText, object, string } from "../transport/wire.js";
 /** Owns model-catalog and preset loads for the selected session. */
 export class CatalogController {
-    store;
     host;
     presetClient;
     revision = 0;
+    generation = new AbortController();
+    refreshAbort;
     tasks = new Set();
-    constructor(store, host) {
-        this.store = store;
+    constructor(host) {
         this.host = host;
     }
     /** Drop generation-scoped catalog state at the start of a connection generation. */
     reset() {
-        this.store.update({ modelError: undefined, defaultModel: undefined, presets: undefined, presetError: undefined });
+        this.close();
+        this.generation = new AbortController();
+        this.presetClient = undefined;
+        this.host.publish({ modelError: undefined, defaultModel: undefined, presets: undefined, presetError: undefined });
     }
+    /** Stop catalog requests before waiting for transport shutdown. Reset opens the next generation. */
+    close() { this.revision++; this.generation.abort(); }
     /** Wait for every in-flight catalog task, so shutdown leaves no pending request. */
-    async settle() { await Promise.all(this.tasks); }
+    async settle() { await Promise.allSettled(this.tasks); }
+    track(task) {
+        this.tasks.add(task);
+        void task.then(() => this.tasks.delete(task), () => this.tasks.delete(task));
+        return task;
+    }
+    signal(caller = this.host.signal()) {
+        return AbortSignal.any([caller, this.host.signal(), this.generation.signal]);
+    }
     /** Load the optional preset roster once per connection, only when a session names a preset. */
     loadPresetNames() {
         const client = this.host.client();
-        if (!client || !this.store.state.online || this.presetClient === client)
+        const signal = this.signal();
+        if (!client || !this.host.online() || this.presetClient === client || signal.aborted)
             return;
         this.presetClient = client;
-        const task = client.call('agentPresets/list', {}).then(value => {
-            if (client === this.host.client())
-                this.store.update({ presets: array(object(value).presets).map(object), presetError: undefined });
+        const current = () => !signal.aborted && client === this.host.client();
+        const task = client.call('agentPresets/list', {}, signal).then(value => {
+            if (current())
+                this.host.publish({ presets: array(object(value).presets).map(object), presetError: undefined });
         }).catch(error => {
-            if (client === this.host.client())
-                this.store.update({ presets: [], presetError: errorText(error) });
+            if (current())
+                this.host.publish({ presets: [], presetError: errorText(error) });
         });
-        this.tasks.add(task);
-        void task.finally(() => this.tasks.delete(task));
+        this.track(task);
     }
     /** Fetch current model routes and adapter-owned reasoning choices for the selected session.
      * @returns Host catalog; provider failures remain available to the selector.
      */
-    async modelCatalog() {
-        const sessionId = this.sessionId;
-        const selection = this.store.selection();
-        const value = object(await this.host.require().call('session/modelCatalog', {}));
-        if (selection !== this.store.selection() || sessionId !== this.store.state.sessionId)
-            throw new Error('Session changed while loading models');
-        return value;
+    async modelCatalog(caller) {
+        const selection = this.selected();
+        const signal = this.signal(caller);
+        signal.throwIfAborted();
+        return this.track((async () => {
+            const value = object(await this.host.require().call('session/modelCatalog', {}, signal));
+            signal.throwIfAborted();
+            if (!this.isSelected(selection))
+                throw new Error('Session changed while loading models');
+            return value;
+        })());
     }
     /** Select the next request's model; the host also attempts to save its deployment default.
      * @param provider - Host provider route ID.
      * @param model - Exact model ID.
      * @param reasoningEffort - Optional adapter-owned effort ID; omission uses its default.
      */
-    async selectModel(provider, model, reasoningEffort) {
-        const sessionId = this.sessionId;
-        const selection = this.store.selection();
-        const selected = object(object(await this.host.require().call('session/selectModel', { request: {
-                sessionId, provider, model, ...(reasoningEffort === undefined ? {} : { reasoningEffort }),
-            } })).selected);
-        if (selection !== this.store.selection() || sessionId !== this.store.state.sessionId)
-            return;
-        this.store.update({ status: `Next request: ${string(selected.provider)} / ${string(selected.model)}${selected.reasoningEffort ? ` · ${string(selected.reasoningEffort)}` : ''}` });
-        this.refresh();
+    async selectModel(provider, model, reasoningEffort, caller) {
+        const selection = this.selected();
+        const signal = this.signal(caller);
+        signal.throwIfAborted();
+        await this.track((async () => {
+            const selected = object(object(await this.host.require().call('session/selectModel', { request: {
+                    sessionId: selection.sessionId, provider, model, ...(reasoningEffort === undefined ? {} : { reasoningEffort }),
+                } }, signal)).selected);
+            signal.throwIfAborted();
+            if (!this.isSelected(selection))
+                return;
+            this.host.publish({ status: `Next request: ${string(selected.provider)} / ${string(selected.model)}${selected.reasoningEffort ? ` · ${string(selected.reasoningEffort)}` : ''}` });
+            this.refresh();
+        })());
     }
     /** Reload the default route and provider failures without touching session state. */
     refresh() {
         const client = this.host.client();
-        if (!client)
+        if (!client || !this.host.online())
+            return;
+        this.refreshAbort?.abort();
+        this.refreshAbort = new AbortController();
+        const signal = this.signal(this.refreshAbort.signal);
+        if (signal.aborted)
             return;
         const revision = ++this.revision;
-        const task = client.call('session/modelCatalog', {}).then(value => {
-            if (client === this.host.client() && revision === this.revision)
-                this.store.update({ defaultModel: object(object(value).default), modelError: undefined });
-        }, error => {
-            if (client === this.host.client() && revision === this.revision)
-                this.store.update({ defaultModel: undefined, modelError: errorText(error) });
+        const current = () => !signal.aborted && client === this.host.client() && revision === this.revision;
+        const task = client.call('session/modelCatalog', {}, signal).then(value => {
+            if (current())
+                this.host.publish({ defaultModel: object(object(value).default), modelError: undefined });
         }).catch(error => {
-            if (client === this.host.client() && revision === this.revision)
-                this.store.update({ defaultModel: undefined, modelError: errorText(error) });
+            if (current())
+                this.host.publish({ defaultModel: undefined, modelError: errorText(error) });
         });
-        this.tasks.add(task);
-        void task.finally(() => this.tasks.delete(task));
+        this.track(task);
     }
     /** @returns The selected session identity, or a `Select a session first` failure. */
-    get sessionId() {
-        const id = this.store.state.sessionId;
-        if (!id)
+    selected() {
+        const selected = this.host.selection();
+        if (!selected.sessionId)
             throw new Error('Select a session first');
-        return id;
+        return { ...selected, sessionId: selected.sessionId };
+    }
+    isSelected(selection) {
+        const current = this.host.selection();
+        return current.revision === selection.revision && current.sessionId === selection.sessionId;
     }
 }

package/dist/catalog/index.d.ts

@@ -1,2 +1,3 @@
 /** Catalog domain: model routes, reasoning efforts and agent-preset metadata. */
 export { CatalogController } from './controller.ts';
+export type { CatalogHost, CatalogUpdate } from './controller.ts';

package/dist/cli/dsht.js

@@ -6,62 +6,123 @@ import { join } from 'node:path';
 import { CostLedger, loadPrices } from "../cost/index.js";
 import { parseArgs } from 'node:util';
 import { mount } from "../ui/mount.js";
-import { ensureDirectory } from "../storage/index.js";
-import { sessionLabel } from "../session/navigation.js";
+import { ensureDirectory, readText } from "../storage/index.js";
+import { runStartup } from "./startup.js";
+import { sessionLabel } from "../session-title.js";
 import { CookieStore, login } from "../transport/auth.js";
 import { Client } from "../transport/client.js";
+import { fileURLToPath } from 'node:url';
 import { historyLimits } from "../session/memory.js";
+import { ProcessVerifier } from "./verifier.js";
 import { Controller } from "../controller/controller.js";
 import { endpoint } from "../transport/endpoint.js";
-import { errorText, safeText, string } from "../transport/wire.js";
-const HELP = `Usage: dsht [options] [list workspaces|list sessions]
+import { errorText, object, string } from "../transport/wire.js";
+import { formatTraceSummary, summarizeTrace } from "./trace-summary.js";
+import { safeText } from "../text.js";
+const HELP = `Usage: dsht [options] [list workspaces|list sessions|trace]
 
 With no command, choose a workspace and session interactively.
 
   --url <url>           Host URL, or the dsh web URL with ?token= (DSH_URL)
   --workspace <id>      Filter list sessions by workspace
-  --session <id>        Open a session directly
+  --session <id|new>    Open a session directly, or create one
+  --ws <id|name|path>   Select this workspace at startup (default: this directory)
+  --command <line>      Run this slash command once the session is ready (repeatable)
+  --prompt <text>       Send this plain prompt once the session is ready
+  --wait                With --headless, exit when the sent prompt's turn has finished
+  --verdict <path>      With --prompt/--wait, write the reply's verdict to this file
+  --verdict-identity <id>  <runId>/<kind>/<step>/<attempt>/<seq> the verdict must declare
+  --headless            Run --command without the terminal interface, then exit
+  --deadline <minutes>  Stop the whole loop after this many minutes (DSHT_LOOP_DEADLINE)
   --auth-dir <path>     Private cookie directory (or DSHT_AUTH_DIR)
   --history-records <n> Soft history record limit (default 2000)
   --history-mb <n>      Soft history payload budget in MiB (default 16)
   --memory-log <path>   Append runtime memory samples; a failing log stops itself
   --no-memory-log       Disable the runtime memory log (default: enabled)
+  --trace <path>        Append connection/screen/selection events (default: <state>/trace.log)
+                        With the trace command, read that file instead of appending to it
+  --no-trace            Disable the transition trace
+  --trace-verbose       Quote sanitized child output in verifier failure reasons
   --no-shell            Disable ! local commands (DSHT_NO_SHELL=1)
-  --json               Print machine-readable list output
+  --json               Print machine-readable list or trace output
+  --version            Print the package version and exit
   --help               Show this help
 
 The default host is http://127.0.0.1:3080.
 First login: export DSH_TOKEN, or export DSH_URL as the URL printed by dsh web.
 Cookies are saved per server origin and reused on later starts. Tokens are never saved.
 /cost shows the session and today CNY estimates.
+/prompt lists saved shortcut prompts; /prompt TEXT saves one in <state>/prompts.json.
 !command runs on this machine, not on the host, and prints its output in the transcript.
 DSHT_CONFIG_DIR overrides the prices.json directory; DSHT_STATE_DIR overrides usage storage.
 The memory log defaults to <state>/memory.log; DSHT_MEMORY_LOG sets another path or 'off'.
+The transition trace defaults to <state>/trace.log; DSHT_TRACE sets another path or 'off'.
 prices.json overrides the shipped rates and is seeded on first use; every scan re-decides the
 history with the table loaded then, so an edited table reaches past requests on the next scan.
 Examples:
   npx @itookit/dsht
   dsht list workspaces --json
   dsht list sessions --workspace <id> --json
+  dsht trace --json
 `;
+/** State root this client reads and writes logs under, honouring the same overrides as the client. */
+function stateRoot() {
+    return process.env.DSHT_STATE_DIR ?? join(process.env.XDG_STATE_HOME ?? join(homedir(), '.local', 'state'), 'dsht');
+}
+/** Read one trace file back as a few lines of facts.
+ *
+ * Needs no host and no credentials: the trace is the client's own record of what it did, and reading
+ * it is the whole point of having written it.
+ * @param requested - `--trace` value, when given.
+ * @param json - Print the summary as JSON instead of lines.
+ */
+async function printTrace(requested, json) {
+    const path = requested ?? process.env.DSHT_TRACE ?? join(stateRoot(), 'trace.log');
+    const text = await readText(path);
+    if (text === undefined) {
+        process.stdout.write(`No trace at ${path}\n`);
+        return;
+    }
+    const summary = summarizeTrace(text.split('\n').filter(line => line !== ''), path);
+    process.stdout.write(json ? `${JSON.stringify(summary, null, 2)}\n` : `${formatTraceSummary(summary).join('\n')}\n`);
+}
 async function main() {
     const { values, positionals } = parseArgs({ allowPositionals: true, options: {
             url: { type: 'string', default: process.env.DSH_URL ?? 'http://127.0.0.1:3080' },
             'history-records': { type: 'string' }, 'history-mb': { type: 'string' },
-            workspace: { type: 'string' }, session: { type: 'string' }, 'auth-dir': { type: 'string' }, json: { type: 'boolean' }, help: { type: 'boolean' },
+            workspace: { type: 'string' }, ws: { type: 'string' }, session: { type: 'string' }, 'auth-dir': { type: 'string' }, json: { type: 'boolean' }, help: { type: 'boolean' }, version: { type: 'boolean' },
+            command: { type: 'string', multiple: true }, prompt: { type: 'string' }, wait: { type: 'boolean' },
+            verdict: { type: 'string' }, 'verdict-identity': { type: 'string' }, headless: { type: 'boolean' },
+            deadline: { type: 'string' },
             'memory-log': { type: 'string' }, 'no-memory-log': { type: 'boolean' }, 'no-shell': { type: 'boolean' },
+            trace: { type: 'string' }, 'no-trace': { type: 'boolean' }, 'trace-verbose': { type: 'boolean' },
         } });
     if (values.help) {
         process.stdout.write(HELP);
         return;
     }
+    // The version is read from the manifest rather than repeated here, so a release never has to edit
+    // a string in this file; like `--help` it needs no host, no credentials and no terminal.
+    if (values.version) {
+        process.stdout.write(`${await packageVersion()}\n`);
+        return;
+    }
     const list = positionals[0] === 'list' && ['workspaces', 'sessions'].includes(positionals[1] ?? '') && positionals.length === 2;
-    if (positionals.length && !list)
+    const trace = positionals[0] === 'trace' && positionals.length === 1;
+    if (positionals.length && !list && !trace)
         throw new Error('Unknown command. Use --help.');
-    if (!list && (values.json || values.workspace))
-        throw new Error('--json and --workspace apply to list commands');
-    if (list && values.session)
+    if (!list && !trace && (values.json || values.workspace))
+        throw new Error('--json and --workspace apply to list or trace commands');
+    if ((list || trace) && values.session)
         throw new Error('--session applies to interactive mode');
+    if ((list || trace) && (values.ws || values.command?.length || values.prompt !== undefined || values.wait || values.headless || values.deadline)) {
+        throw new Error('--ws, --command, --prompt, --wait, --deadline and --headless apply to interactive mode');
+    }
+    // Reading a trace needs no host, no credentials and no terminal, so it runs before any of them.
+    if (trace) {
+        await printTrace(values.trace, values.json === true);
+        return;
+    }
     const limits = historyLimits(values['history-records'], values['history-mb']);
     const { url, token } = endpoint(values.url, process.env.DSH_TOKEN);
     const store = new CookieStore(values['auth-dir']);
@@ -93,14 +154,71 @@ async function main() {
     const costDirectory = join(stateRoot, 'cost', createHash('sha256').update(new URL(url).origin).digest('hex'));
     const costs = new CostLedger(prices, costDirectory, custom);
     await costs.load();
-    if (!process.stdin.isTTY || !process.stdout.isTTY)
-        throw new Error('Interactive mode requires a terminal. Use list workspaces or list sessions for scripts.');
+    if (!values.headless && (!process.stdin.isTTY || !process.stdout.isTTY)) {
+        throw new Error('Interactive mode requires a terminal. Use --headless or list workspaces/list sessions for scripts.');
+    }
     const shellEnabled = !values['no-shell'] && process.env.DSHT_NO_SHELL !== '1';
-    const controller = new Controller(url, token, values.session, undefined, client => login(client, token, store), costs, limits, memoryLogPath(stateRoot, values['memory-log'], values['no-memory-log']), undefined, shellEnabled);
+    const localDirectory = process.cwd();
+    // A scored review can delegate each round's verdict to a child client, which needs no shared state
+    // with this one: it is handed a session and a prompt, and answers through a file.
+    const verifier = process.env.DSHT_NO_VERIFY === '1' ? undefined : new ProcessVerifier({
+        command: [process.execPath, ...process.execArgv, process.argv[1] ?? fileURLToPath(import.meta.url)],
+        url: values.url,
+        ...(values['auth-dir'] === undefined ? {} : { authDir: values['auth-dir'] }),
+        cwd: localDirectory, env: process.env,
+        timeoutMs: verifyTimeoutMs(process.env.DSHT_VERIFY_TIMEOUT_MS),
+        createSession: (title) => controller.actions.createVerifierSession(title),
+        cancelSession: async (sessionId) => {
+            if (!await controller.actions.cancelVerifierSession(sessionId))
+                throw new Error('Verifier cancellation was not accepted');
+        },
+        onLine: line => { if (values.headless)
+            log(line); },
+        // Off by default: a verifier reason reaches the progress line and the trace, and that log may be
+        // pasted into a report, so the child's own words are quoted only when the operator asks.
+        verbose: values['trace-verbose'] === true || process.env.DSHT_TRACE_VERBOSE === '1',
+    });
+    const controller = new Controller({
+        base: url, token, initialSession: values.session === 'new' ? undefined : values.session,
+        authenticate: client => login(client, token, store),
+        localDirectory, verifier,
+        // Verdicts belong to this client rather than to the reviewed tree, and the client's own
+        // directory is the one place it is always allowed to write; DSHT_VERDICT_ROOT points them
+        // elsewhere when the review targets a workspace this machine cannot write.
+        verdictRoot: process.env.DSHT_VERDICT_ROOT ?? localDirectory,
+        costs, historyLimits: limits, shellEnabled,
+        deadlineMs: loopDeadlineMs(values.deadline ?? process.env.DSHT_LOOP_DEADLINE),
+        memoryLogPath: memoryLogPath(stateRoot, values['memory-log'], values['no-memory-log']),
+        tracePath: tracePath(stateRoot, values.trace, values['no-trace']),
+        promptsPath: join(stateRoot, 'prompts.json'),
+    });
+    const plan = {
+        ...(values.ws === undefined ? {} : { workspace: values.ws }),
+        ...(values.session === undefined ? {} : { session: values.session }),
+        commands: values.command ?? [],
+        ...(values.prompt === undefined ? {} : { prompt: values.prompt }),
+        ...(values.wait === undefined ? {} : { wait: values.wait }),
+        ...(values.verdict === undefined ? {} : { verdict: { file: values.verdict, identity: requireIdentity(values['verdict-identity']) } }),
+        timeoutSeconds: 3600,
+    };
+    const log = (line) => process.stderr.write(`${line}\n`);
+    controller.start();
+    if (values.headless) {
+        // No renderer: run the plan, follow a started loop to its verdict, and report it as the exit code.
+        try {
+            const outcome = await runStartup(controller, plan, log);
+            // 0 passed, 1 failed, 3 waiting for a person: a script can tell the three apart.
+            process.exitCode = outcome === 'failed' ? 1 : outcome === 'needs-human' ? 3 : 0;
+        }
+        finally {
+            await controller.shutdown();
+        }
+        return;
+    }
     const app = mount(controller);
     const terminate = () => app.unmount();
     process.once('SIGTERM', terminate);
-    controller.start();
+    void runStartup(controller, plan, log).catch(error => process.stderr.write(`${errorText(error)}\n`));
     try {
         await app.waitUntilExit();
     }
@@ -109,6 +227,55 @@ async function main() {
         await controller.shutdown();
     }
 }
+/** Read the published version from the manifest beside this entry point.
+ *
+ * The path is relative to this module, so it resolves both in the source tree (`src/cli/`) and in
+ * the published build (`dist/cli/`). The version is never repeated as a literal, which is what lets
+ * a release touch only `package.json` and the lockfile.
+ * @returns The `version` field of `package.json`.
+ */
+async function packageVersion() {
+    const manifest = await readText(fileURLToPath(new URL('../../package.json', import.meta.url)));
+    if (manifest === undefined)
+        throw new Error('package.json is missing beside the client entry point');
+    const version = string(object(JSON.parse(manifest)).version);
+    if (version === '')
+        throw new Error('package.json has no version');
+    return version;
+}
+/** The identity a written verdict must declare, refused when the flag that carries it is missing.
+ * @param value - `--verdict-identity` value.
+ * @returns The identity.
+ */
+function requireIdentity(value) {
+    if (value === undefined || value.trim() === '')
+        throw new Error('--verdict requires --verdict-identity');
+    return value;
+}
+/** Whole-run budget from `--deadline`/`DSHT_LOOP_DEADLINE`, in minutes.
+ *
+ * Absent means no budget, which keeps the old behaviour for callers that never set one. A value that
+ * is not a positive number is refused rather than silently ignored, because a run that was supposed
+ * to be bounded and is not is worse than a startup error.
+ * @param value - Flag or environment value.
+ * @returns The budget in milliseconds, or undefined when unbounded.
+ */
+function loopDeadlineMs(value) {
+    if (value === undefined || value.trim() === '')
+        return undefined;
+    const minutes = Number(value);
+    if (!Number.isFinite(minutes) || minutes <= 0)
+        throw new Error(`--deadline must be a positive number of minutes: ${value}`);
+    return Math.round(minutes * 60_000);
+}
+/** How long one forked verification may run, from a minute count in the environment.
+ * @param value - `DSHT_VERIFY_TIMEOUT_MS` when set.
+ * @returns The timeout in milliseconds, defaulting to twenty minutes.
+ */
+function verifyTimeoutMs(value) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 20 * 60_000;
+}
 /** Resolve the runtime memory log path: an explicit flag wins, then the environment, then the default.
  * @param stateRoot - Application state root used for the default path.
  * @param requested - `--memory-log` value, when given.
@@ -116,13 +283,34 @@ async function main() {
  * @returns Absolute log path, or undefined when the log is disabled.
  */
 function memoryLogPath(stateRoot, requested, disabled) {
+    return diagnosticLogPath('memory-log', 'memory.log', stateRoot, requested, disabled, process.env.DSHT_MEMORY_LOG);
+}
+/** Resolve the transition trace path: an explicit flag wins, then the environment, then the default.
+ * @param stateRoot - Application state root used for the default path.
+ * @param requested - `--trace` value, when given.
+ * @param disabled - `--no-trace` flag.
+ * @returns Absolute trace path, or undefined when the trace is disabled.
+ */
+function tracePath(stateRoot, requested, disabled) {
+    return diagnosticLogPath('trace', 'trace.log', stateRoot, requested, disabled, process.env.DSHT_TRACE);
+}
+/** Resolve one diagnostic log path shared by the memory log and the transition trace.
+ * @param flag - Long option name, used in the error for an empty value.
+ * @param file - Default filename under the state root.
+ * @param stateRoot - Application state root.
+ * @param requested - Flag value, when given; an empty string is a mistyped flag, not a default.
+ * @param disabled - `--no-<flag>` flag.
+ * @param environment - Environment override, where `off` disables the log.
+ * @returns Absolute log path, or undefined when the log is disabled.
+ */
+function diagnosticLogPath(flag, file, stateRoot, requested, disabled, environment) {
     if (requested !== undefined && requested.trim() === '')
-        throw new Error('--memory-log requires a path');
+        throw new Error(`--${flag} requires a path`);
     if (disabled)
         return undefined;
-    const chosen = (requested ?? process.env.DSHT_MEMORY_LOG)?.trim();
+    const chosen = (requested ?? environment)?.trim();
     if (chosen === undefined || chosen === '')
-        return join(stateRoot, 'memory.log');
+        return join(stateRoot, file);
     return chosen === 'off' ? undefined : chosen;
 }
 main().catch(error => { process.stderr.write(`${errorText(error)}\n`); process.exitCode = 1; });

package/dist/cli/startup.d.ts

@@ -0,0 +1,40 @@
+/** Startup automation: pick a workspace and a session, then run the requested slash lines.
+ *
+ * This is the scriptable half of the client — `dsht --ws X --session new --command "…"` — so a
+ * review can be launched without typing. It drives the same controller the UI drives, and reads only
+ * the outcome of each line: the presentational effects of a command belong to the UI.
+ */
+import { type Controller } from '../controller/index.ts';
+/** What the operator asked the client to do before/while taking over. */
+export interface StartupPlan {
+    /** Workspace ID, name or path; absent adopts the directory this client runs in. */
+    workspace?: string;
+    /** Session to open, or `new`; absent creates one when commands were given. */
+    session?: string;
+    /** Slash lines to run once the session is ready, in order. */
+    commands: readonly string[];
+    /** Plain prompt to send after the commands; a forked verifier drives a session this way. */
+    prompt?: string;
+    /** Wait for that prompt's turn to finish before returning, so the child exits on its own. */
+    wait?: boolean;
+    /** Where to persist the verdict this session produced, and the identity it must declare. */
+    verdict?: VerdictTarget;
+    /** Seconds a started loop may run before it is stopped. */
+    timeoutSeconds: number;
+}
+/** The verdict file a forked verifier session must leave behind. */
+export interface VerdictTarget {
+    /** Absolute path to write. */
+    file: string;
+    /** `<runId>/<kind>/<step>/<attempt>`, checked against the reply before anything is written. */
+    identity: string;
+}
+/** How the startup run ended. */
+export type StartupOutcome = 'passed' | 'idle' | 'failed' | 'needs-human';
+/** Run the plan against a started controller.
+ * @param controller - Connected application facade.
+ * @param plan - Workspace, session and lines to run.
+ * @param log - Progress sink, usually stderr in headless mode.
+ * @returns Whether a started loop passed, nothing ran, or the run failed.
+ */
+export declare function runStartup(controller: Controller, plan: StartupPlan, log: (line: string) => void): Promise<StartupOutcome>;