@itookit/dsht 0.3.8 → 0.5.1

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,68 @@ 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) => { await controller.actions.cancelVerifierSession(sessionId); },
+        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 +224,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 +280,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>;

package/dist/cli/startup.js

@@ -0,0 +1,295 @@
+/** 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 { runCommand } from "../controller/index.js";
+import { errorText } from "../transport/wire.js";
+import { dirname } from 'node:path';
+import { ensureDirectory, renameFile, writePrivateFile } from "../storage/index.js";
+import { latestAssistantText } from "../controller/loop.js";
+import { parseVerdict } from "../controller/loop-contract.js";
+import { needsHumanLine } from "../controller/verifier.js";
+import { authorize, normalize } from "../slash/index.js";
+const POLL_MS = 250;
+/** How long a connection, session or workspace operation may take. */
+const STEP_TIMEOUT_MS = 30_000;
+/** How long a forked child may wait for the session it was pointed at to stream its snapshot. */
+const PROMPT_SNAPSHOT_TIMEOUT_MS = 180_000;
+/** How long the verdict may take to appear after the turn was reported idle. */
+const VERDICT_GRACE_MS = 5_000;
+/** How often the reply is re-read while that grace lasts. */
+const VERDICT_POLL_MS = 200;
+/** Wait until one condition holds.
+ * @param condition - Predicate polled until true.
+ * @param what - Human-readable subject for the timeout message.
+ * @param timeoutMs - Longest wait.
+ */
+async function until(condition, what, timeoutMs = STEP_TIMEOUT_MS) {
+    const deadline = Date.now() + timeoutMs;
+    while (!condition()) {
+        if (Date.now() >= deadline)
+            throw new Error(`Timed out waiting for ${what}`);
+        await new Promise(resolve => setTimeout(resolve, POLL_MS));
+    }
+}
+/** 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 async function runStartup(controller, plan, log) {
+    // `online` alone is too early: the startup picker runs after it and would overwrite a selection
+    // made here, which is exactly how a forked verifier used to lose its session.
+    await until(() => controller.state.online && controller.queries.connectionSettled, 'the host connection');
+    if (plan.workspace !== undefined && !await controller.actions.switchWorkspace(plan.workspace)) {
+        throw new Error(`Workspace not found: ${plan.workspace}`);
+    }
+    // An explicit `new`, or automation with no session named, starts a fresh conversation; the
+    // workspace defaults to the directory this client runs in, registered on demand.
+    if (plan.session === 'new' || plan.session === undefined && plan.commands.length > 0) {
+        await ensureWorkspace(controller, log);
+        if (!await controller.actions.createSession())
+            throw new Error('Could not create a session');
+    }
+    else if (plan.session !== undefined) {
+        if (!await controller.actions.selectSession(plan.session))
+            throw new Error(`Session not found: ${plan.session}`);
+    }
+    // A selected session is not sendable until its follow snapshot lands.
+    if (plan.commands.length) {
+        await until(() => controller.state.screen === 'chat' && controller.state.sessionId !== undefined && controller.queries.record.ready, 'the session snapshot');
+    }
+    // Start-up lines are one-shot action commands; the cancellable port is only used by searches
+    // and exports, which have no meaning before the operator is present.
+    const port = { run: (_label, operation) => operation(controller.connection.signal()) };
+    for (const line of plan.commands) {
+        // The scripted half runs the same two stages the composer does after `interpret`: a headless
+        // caller has no menus or screens, but it has every application fact `normalize`/`authorize` read.
+        const command = normalize({ kind: 'line', line }, {
+            sessionSelected: controller.state.sessionId !== undefined,
+            question: controller.state.pending[0]?.kind === 'question',
+            pending: controller.state.pending.length > 0,
+        });
+        if (command.kind === 'error')
+            throw new Error(command.message);
+        const verdict = await authorizeWhenReady(controller, command);
+        if (!verdict.allow)
+            throw new Error(verdict.error.message);
+        const result = await runCommand(controller, verdict.command, port);
+        if (result === undefined) {
+            const reason = controller.state.lastFailure;
+            throw new Error(`Command was not accepted: ${line}${reason ? ` (${reason})` : ''}`);
+        }
+        if (result.outcome !== 'ok') {
+            const failure = result.effects.find(effect => effect.kind === 'error');
+            throw new Error(failure?.kind === 'error' ? failure.text : `Command failed (${result.outcome}): ${line}`);
+        }
+        if (result.disposition === 'retain')
+            throw new Error(`Command did not settle: ${line}`);
+        for (const effect of result.effects)
+            if (effect.kind === 'notice')
+                log(effect.text);
+    }
+    // Both counts are taken before the prompt, because a turn can start and finish between two polls.
+    const finishedBefore = controller.queries.turnsCompleted;
+    const repliesBefore = controller.queries.record.messages.length;
+    if (plan.prompt !== undefined) {
+        // Sending a prompt needs the follow snapshot, and a verifier starts the instant a busy turn ends,
+        // so this wait is longer than a normal startup step: the host can be slow to open the new stream.
+        try {
+            await until(() => controller.state.sessionId !== undefined && controller.queries.record.ready, 'the verifier session snapshot', PROMPT_SNAPSHOT_TIMEOUT_MS);
+        }
+        catch (error) {
+            // Which of the three conditions failed is the whole diagnosis, so it travels with the error.
+            throw new Error(`${errorText(error)} (screen=${controller.state.screen}, session=${controller.state.sessionId ?? 'none'},`
+                + ` snapshot=${String(controller.queries.record.ready)}, online=${String(controller.state.online)})`);
+        }
+        await controller.actions.prompt(plan.prompt);
+    }
+    if (controller.queries.loop !== undefined)
+        return await waitForLoop(controller, plan.timeoutSeconds * 1000, log);
+    if (plan.wait) {
+        const outcome = await waitForTurn(controller, finishedBefore, plan.timeoutSeconds * 1000, log);
+        if (outcome === 'idle' && plan.verdict !== undefined)
+            await writeVerdict(controller, plan.verdict, repliesBefore, log);
+        return outcome;
+    }
+    return 'idle';
+}
+/** Authorize one startup line, waiting out a fact the policy queues behind.
+ *
+ * There is no composer here to hold a line, and failing a scripted run because the client happened to
+ * be mid-turn would make `--command` unusable in exactly the automation it exists for; so the scripted
+ * caller waits for the same fact the UI queue waits for, bounded by the step timeout.
+ * @param controller - Connected facade whose facts decide.
+ * @param command - Normalized line to run.
+ * @returns The verdict once the line may run, or the refusal it will never outlive.
+ */
+async function authorizeWhenReady(controller, command) {
+    const deadline = Date.now() + STEP_TIMEOUT_MS;
+    for (;;) {
+        const verdict = authorize(command, {
+            sessionSelected: controller.state.sessionId !== undefined,
+            pending: controller.state.pending.length > 0,
+            during: controller.queries.loop?.active === true ? 'loop' : controller.queries.running ? 'turn' : 'idle',
+            foreground: controller.queries.foreground !== undefined,
+        });
+        if (!verdict.allow || verdict.defer === undefined)
+            return verdict;
+        if (Date.now() >= deadline)
+            throw new Error(`Timed out waiting for the client to be free: ${command.kind}`);
+        await new Promise(resolve => setTimeout(resolve, POLL_MS));
+    }
+}
+/** Persist the verdict this session's reply just produced.
+ *
+ * The agent judges; this client owns the protocol file: the reply is parsed here and written through
+ * a temporary file that is renamed into place, so a reader never sees a half-written verdict.
+ * A reply with no usable verdict changes nothing — the parent validates whatever is there.
+ * @param controller - Connected facade whose transcript holds the reply.
+ * @param target - File to write and the identity the verdict must declare.
+ * @param repliesBefore - Messages on the transcript before the prompt was sent: only a reply that
+ *   arrived after it can be this turn's, so an idle from an earlier or replayed turn cannot be read
+ *   as the verdict.
+ * @param log - Progress sink.
+ */
+async function writeVerdict(controller, target, repliesBefore, log) {
+    const [, kind = '', step = '', attempt = ''] = target.identity.split('/');
+    const expect = { verificationId: target.identity, kind, step: Number(step), attempt: Number(attempt) };
+    // The host reports the turn idle just before that reply is committed, so an immediate parse can
+    // find nothing; the verdict is only missing once it has had time to arrive. Waiting on an
+    // assistant reply that did not exist when the prompt was sent is what ties the verdict to this
+    // prompt: the prompt itself only adds a user message, and an earlier turn's reply is behind the
+    // baseline.
+    const replyArrived = () => controller.queries.record.messages
+        .slice(repliesBefore).some(message => message.role === 'Assistant');
+    let parsed = replyArrived() ? parseVerdict(latestAssistantText(controller.queries.record.messages), expect) : undefined;
+    const deadline = Date.now() + VERDICT_GRACE_MS;
+    while (parsed === undefined && Date.now() < deadline) {
+        await new Promise(resolve => setTimeout(resolve, VERDICT_POLL_MS));
+        if (replyArrived())
+            parsed = parseVerdict(latestAssistantText(controller.queries.record.messages), expect);
+    }
+    if (parsed === undefined) {
+        // Say what actually happened: "no reply yet", "no JSON at all" and "JSON that is not this round"
+        // are different faults, and one line here is what tells them apart without another live run.
+        if (!replyArrived()) {
+            log('Turn ended but no reply was committed after the prompt; leaving the verdict file untouched');
+            return;
+        }
+        const tail = latestAssistantText(controller.queries.record.messages).slice(-240).replace(/\s+/g, ' ');
+        log(`No parsable verdict in the reply; leaving the verdict file untouched (reply tail: ${tail})`);
+        return;
+    }
+    const body = JSON.stringify({
+        verificationId: target.identity, kind, step: Number(step), attempt: Number(attempt),
+        ...(parsed.score === undefined ? {} : { score: parsed.score }),
+        ...(parsed.status === undefined ? {} : { status: parsed.status }),
+        ...(parsed.blocked === true ? { blocked: true } : {}),
+        ...(parsed.evidence === undefined ? {} : { evidence: parsed.evidence }),
+        ...(parsed.findings === undefined ? {} : { top_findings: parsed.findings }),
+    });
+    await ensureDirectory(dirname(target.file));
+    const temporary = `${target.file}.part`;
+    await writePrivateFile(temporary, body);
+    await renameFile(temporary, target.file);
+    log(`Verdict written to ${target.file}`);
+}
+/** Follow a sent prompt's turn to its end, which is what lets a forked child exit by itself.
+ *
+ * The host's idle event is the same signal the scored loop trusts: it cannot be missed by polling,
+ * and a turn that starts and ends between two polls still counts.
+ * @param controller - Connected application facade.
+ * @param finishedBefore - Turns completed before the prompt was sent.
+ * @param timeoutMs - Longest wait.
+ * @param log - Progress sink.
+ * @returns `idle` when the turn ended, `failed` on timeout.
+ */
+async function waitForTurn(controller, finishedBefore, timeoutMs, log) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        if (controller.queries.turnsCompleted > finishedBefore) {
+            log('Turn finished');
+            return 'idle';
+        }
+        // A headless verifier cannot answer an approval or a question: stop and say what is needed,
+        // instead of waiting for the deadline and being retried as an infrastructure failure.
+        const request = humanRequest(controller);
+        if (request !== undefined) {
+            log(needsHumanLine(request));
+            return 'needs-human';
+        }
+        if (Date.now() >= deadline) {
+            log('Turn timed out');
+            return 'failed';
+        }
+        await new Promise(resolve => setTimeout(resolve, POLL_MS));
+    }
+}
+/** The host interaction this client cannot answer itself, when one is pending.
+ * @param controller - Connected facade whose selected session is the verifier's session.
+ * @returns The request to report, or undefined when nothing is pending.
+ */
+function humanRequest(controller) {
+    const [pending] = controller.state.pending;
+    if (pending === undefined)
+        return undefined;
+    if (pending.kind === 'approval') {
+        return { kind: 'approval', text: pending.description === '' ? 'a tool approval is required' : pending.description };
+    }
+    return { kind: 'question', text: pending.questions[0]?.question ?? 'a question was asked' };
+}
+/** Select the directory this client runs in, registering it when the host does not know it yet. */
+async function ensureWorkspace(controller, log) {
+    if (controller.state.workspaceId !== undefined)
+        return;
+    if (await controller.actions.switchWorkspace(controller.localDirectory))
+        return;
+    log(`Registering ${controller.localDirectory} as a workspace`);
+    if (!await controller.actions.createWorkspace(controller.localDirectory)) {
+        throw new Error(`Could not use ${controller.localDirectory} as a workspace`);
+    }
+}
+/** Follow a running loop to its terminal phase, reporting progress changes.
+ * @returns `passed` when the loop met its threshold, `failed` otherwise.
+ */
+async function waitForLoop(controller, timeoutMs, log) {
+    const deadline = Date.now() + timeoutMs;
+    let previous = '';
+    for (;;) {
+        const progress = controller.queries.loop;
+        if (progress === undefined || progress.phase !== 'running') {
+            // A cancelled loop usually means the connection ended; say so, or the exit code is a mystery.
+            const why = controller.state.lastFailure || controller.state.status;
+            const interaction = progress?.interaction;
+            // `passed` only claims the rounds that ran, so a headless reader is told which ones.
+            const scope = progress?.phase === 'passed' ? ` · ${progress.scope}` : '';
+            log(`Loop ${progress?.phase ?? 'gone'}${scope}${why ? ` · ${why}` : ''}`
+                + `${interaction === undefined ? '' : ` · ${interaction.kind}: ${interaction.text}`}`
+                + `${progress?.note === undefined ? '' : ` · ${progress.note}`}`);
+            if (progress?.phase === 'passed')
+                return 'passed';
+            // A run stopped on a host request is not a failure: it is waiting for a person, and phase 1
+            // deliberately has no in-process answer path.
+            return progress?.phase === 'needs-human' ? 'needs-human' : 'failed';
+        }
+        const label = progress.stepLabel === undefined ? '' : ` · ${progress.stepLabel}`;
+        // The note carries why an attempt was decided the way it was — including why verification was
+        // unavailable — so a headless run is diagnosable without a renderer.
+        const note = progress.note === undefined ? '' : ` · ${progress.note}`;
+        const line = `${progress.title}${label} · step ${progress.step}/${progress.to} · attempt ${progress.attempt}/${progress.tries} · best ${progress.best}/${progress.score}${note}`;
+        if (line !== previous) {
+            previous = line;
+            log(line);
+        }
+        if (Date.now() >= deadline) {
+            controller.actions.stopLoop();
+            log('Loop timed out and was stopped');
+            return 'failed';
+        }
+        await new Promise(resolve => setTimeout(resolve, POLL_MS));
+    }
+}