@aragon-agent/cli 0.6.38 → 0.6.39

package/dist/exec/threads/aggregate.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Summing N threads' accounts into one process-level answer
+ * (headless-threads-and-lifecycle-hooks section 2.3.7).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * `result` IS ONE EVENT FOR THE WHOLE PROCESS, so it cannot report any single
+ * thread's usage: it reports the sum. The two derived rules that are not obvious
+ * arithmetic are stated where they are implemented below.
+ */
+import type { ExecCost, ExecUsage } from '../events.js';
+import type { ExecThreadEndReason } from './limits.js';
+/** One thread's contribution to `result.threads.items` and to the process totals. */
+export interface ThreadAccount {
+    threadId: string;
+    sessionId: string;
+    requests: number;
+    turns: number;
+    usage: ExecUsage;
+    cost: ExecCost;
+    isError: boolean;
+    reason: ExecThreadEndReason;
+}
+export interface AggregateInput {
+    usage: ExecUsage;
+    cost: ExecCost;
+    totals: {
+        opened: number;
+        closed: number;
+        failed: number;
+    };
+}
+export declare function emptyUsage(): ExecUsage;
+export declare function aggregateAccounts(accounts: readonly ThreadAccount[]): AggregateInput;

package/dist/exec/threads/aggregate.js

@@ -0,0 +1,30 @@
+export function emptyUsage() {
+    return { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+}
+export function aggregateAccounts(accounts) {
+    const usage = emptyUsage();
+    let amount = 0;
+    // `every`, NOT `some`: a thread whose model has no price table makes the whole
+    // answer unknown. "One thread knew the price" must not launder the other thread's
+    // confident zero, which is the same rule `request/scope.ts` applies to `known`.
+    let known = accounts.length > 0;
+    let failed = 0;
+    for (const account of accounts) {
+        usage.inputTokens += account.usage.inputTokens;
+        usage.outputTokens += account.usage.outputTokens;
+        usage.totalTokens += account.usage.totalTokens;
+        amount += account.cost.amount;
+        known = known && account.cost.known;
+        if (account.isError)
+            failed += 1;
+    }
+    // A THREAD IS COUNTED AS CLOSED BECAUSE ITS RECORD EXISTS, not because its reason is
+    // literally `closed`: an aborted or timed-out thread is finished too, and counting
+    // only the settled ones would make `result.threads.closed` disagree with every
+    // `thread_state{phase:'closed'}` the caller already received.
+    return {
+        usage,
+        cost: { amount, currency: 'USD', known },
+        totals: { opened: accounts.length, closed: accounts.length, failed },
+    };
+}

package/dist/exec/threads/capacity.d.ts

@@ -0,0 +1,23 @@
+export type CapacityCode = 'thread_limit' | 'thread_capacity';
+export interface OpenCapacityInput {
+    /** Threads in `opening` / `open` / `closing`. Closed records do not count. */
+    active: number;
+    /** `--max-open-threads`, already clamped by the flag parser. */
+    maxOpenThreads: number;
+}
+/**
+ * May another thread be opened?
+ *
+ * `>=` rather than `>`: `--max-open-threads 1` means exactly one thread, which is
+ * the default thread alone - a legal (if pointless) configuration that must not
+ * admit a second.
+ */
+export declare function canOpen(input: OpenCapacityInput): true | CapacityCode;
+/**
+ * May this thread serve one more request?
+ *
+ * The ceiling is a leak guard, not a policy: a thread that has served a hundred
+ * thousand requests in one process has almost certainly been used as a queue, and
+ * the caller should have closed it and opened another.
+ */
+export declare function withinRequestCap(requests: number): boolean;

package/dist/exec/threads/capacity.js

@@ -0,0 +1,38 @@
+/**
+ * The two capacities a thread run enforces (headless-threads-and-lifecycle-hooks
+ * section 2.3.10, I-T8).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * TWO CEILINGS, TWO QUESTIONS, AND THEY ARE NOT THE SAME ONE:
+ *   - `maxOpenThreads`   bounds how many conversations exist;
+ *   - `thread-concurrency` (the gate) bounds how many are RUNNING a request.
+ *
+ * A closed thread stops occupying the first and never occupied the second, which is
+ * the rule that lets a wrapper cycle tenants through a bounded pool.
+ *
+ * SPLIT OUT OF `registry.ts` on purpose (review P2-6): the registry is a state
+ * machine, and mixing arithmetic into it made the file the first thing to cross the
+ * 400-line budget.
+ */
+import { THREAD_LIMITS } from './limits.js';
+/**
+ * May another thread be opened?
+ *
+ * `>=` rather than `>`: `--max-open-threads 1` means exactly one thread, which is
+ * the default thread alone - a legal (if pointless) configuration that must not
+ * admit a second.
+ */
+export function canOpen(input) {
+    return input.active < input.maxOpenThreads ? true : 'thread_limit';
+}
+/**
+ * May this thread serve one more request?
+ *
+ * The ceiling is a leak guard, not a policy: a thread that has served a hundred
+ * thousand requests in one process has almost certainly been used as a queue, and
+ * the caller should have closed it and opened another.
+ */
+export function withinRequestCap(requests) {
+    return requests < THREAD_LIMITS.maxRequestsPerThread;
+}

package/dist/exec/threads/dispatch-source.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The single stdin reader in thread mode
+ * (headless-threads-and-lifecycle-hooks section 2.3.3; review P1-3).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * STDIN HAS EXACTLY ONE PARSER. `bridge/source.ts` attaches `data` / `end` / `error`
+ * listeners at construction, so a pre-built `prompts` source and this one would be two
+ * splitters on the same bytes: everything after the first newline would land in
+ * whichever of the two happened to be registered first. `exec/index.ts` therefore
+ * refuses the combination outright and `executeThreads` receives the STREAM, not a
+ * source.
+ *
+ * IT IS A ROUTER, NOT A STATE MACHINE. `thread_open` is asynchronous (it constructs a
+ * controller and takes a session lock) while `handleLine` is synchronous, so the
+ * routing decision below is "which port does this belong to" and nothing else: the
+ * registry owns the `opening` state and its own queue. That split is what lets a
+ * caller send `thread_open` and `prompt` back to back - the normal Web-backend shape -
+ * without a prompt being dropped or served early.
+ */
+import type { ExecPromptSource } from '../runner.js';
+import { type BridgeHookAnswerFrame, type BridgeInputFrame } from '../bridge/protocol.js';
+/** Everything the router needs. The registry supplies all of it. */
+export interface ThreadDispatchPorts {
+    /** A `prompt` frame for a thread; the registry queues it (even mid-`opening`). */
+    deliverPrompt(threadId: string, text: string, frameId: string | undefined): void;
+    /** A control frame for a thread's own bridge server. */
+    deliverControl(threadId: string, frame: BridgeInputFrame): void;
+    /** `hook_answer` for a thread's hook dispatcher. */
+    deliverHookAnswer(threadId: string, frame: BridgeHookAnswerFrame): void;
+    /** `thread_open` / `thread_close` / `thread_list`. */
+    handleThreadFrame(frame: BridgeInputFrame): void;
+    /**
+     * `interrupt` WITHOUT a `threadId`. Process-level by definition (section 2.3.2): it
+     * never enters a thread's server, because "stop this run" cannot be answered by
+     * aborting one of N threads.
+     */
+    interruptProcess(): void;
+    /** `interrupt` WITH a `threadId`: refused, and the refusal is the whole behaviour. */
+    rejectThreadedInterrupt(threadId: string, frameId: string | undefined): void;
+    /** `end` frame, EOF, or the process shutting down. */
+    finishAll(): void;
+    /** A malformed line, already carrying its stable `code`. */
+    onBadLine(code: string, message: string): void;
+}
+export interface ThreadDispatchSource {
+    /** The source one thread's runner consumes; `undefined` before the thread exists. */
+    sourceFor(threadId: string): ExecPromptSource | undefined;
+    /** End every thread's input (`end` frame or EOF). */
+    finishAll(): void;
+    /** Detach the listeners so the process can exit. */
+    close(): void;
+    isFinished(): boolean;
+    queueDepth(threadId: string): number;
+}
+export interface ThreadDispatchOptions {
+    input: NodeJS.ReadableStream;
+    ports: ThreadDispatchPorts;
+}
+export declare function createThreadDispatchSource(options: ThreadDispatchOptions): ThreadDispatchSource;

package/dist/exec/threads/dispatch-source.js

@@ -0,0 +1,106 @@
+import { createNdjsonSplitter } from '../bridge/ndjson.js';
+import { parseBridgeInput, } from '../bridge/protocol.js';
+import { DEFAULT_THREAD_ID } from './identity.js';
+function isThreadFrame(frame) {
+    return (frame.type === 'thread_open' ||
+        frame.type === 'thread_close' ||
+        frame.type === 'thread_list');
+}
+export function createThreadDispatchSource(options) {
+    const ports = options.ports;
+    let finished = false;
+    const finishAll = () => {
+        if (finished)
+            return;
+        finished = true;
+        ports.finishAll();
+    };
+    const handleLine = (line) => {
+        const parsed = parseBridgeInput(line);
+        if (!parsed.ok) {
+            ports.onBadLine(parsed.code, parsed.message);
+            return;
+        }
+        const frame = parsed.frame;
+        if (frame.type === 'prompt') {
+            // AFTER `end` NOTHING IS A TURN - the v1 rule, preserved by `bridge/source.ts`
+            // and preserved here for the same reason: a caller that said "that is my last
+            // prompt" must not have a late one silently start a conversation.
+            if (finished)
+                return;
+            ports.deliverPrompt(frame.threadId ?? DEFAULT_THREAD_ID, frame.text, frame.id);
+            return;
+        }
+        if (frame.type === 'end') {
+            finishAll();
+            return;
+        }
+        if (frame.type === 'ignored')
+            return;
+        if (isThreadFrame(frame)) {
+            ports.handleThreadFrame(frame);
+            return;
+        }
+        if (frame.type === 'interrupt') {
+            // THE HARD DECISION, IN ONE PLACE, AND IT HAS THREE ANSWERS (section 2.3.3's routing
+            // table, last row). With a `threadId` this frame is refused: silently degrading it to
+            // `cancel_request` would make "the user pressed Ctrl-C" and "the backend withdrew one
+            // request" indistinguishable after the fact - and their exit codes, persistence and
+            // `result` differ completely.
+            if (frame.threadId !== undefined) {
+                ports.rejectThreadedInterrupt(frame.threadId, frame.id);
+                return;
+            }
+            // WITH A `requestId` IT IS NOT A PROCESS INTERRUPT AT ALL: it names one queued turn,
+            // and v1 answers it by deleting that turn and acking `cancelled:'queued'`
+            // (`bridge/source.ts` -> the runner's `onInterruptFrame`). Promoting it to a
+            // process-level stop here would answer a routine "withdraw that message" by killing
+            // the run with exit 130 - the v1 caller regression I-C4 forbids.
+            if (frame.requestId !== undefined) {
+                ports.deliverControl(DEFAULT_THREAD_ID, frame);
+                return;
+            }
+            ports.interruptProcess();
+            return;
+        }
+        if (frame.type === 'hook_answer') {
+            ports.deliverHookAnswer(frame.threadId ?? DEFAULT_THREAD_ID, frame);
+            return;
+        }
+        // Every other control frame (`decision`, `tool_result`, `steer`, `cancel_request`,
+        // `tool_register`, `hook_register`, `ping`) goes to that thread's own server. A
+        // missing `threadId` lands on `main`, which is what makes a v1 caller work
+        // unchanged (AC-11).
+        const route = 'threadId' in frame ? frame.threadId : undefined;
+        ports.deliverControl(route ?? DEFAULT_THREAD_ID, frame);
+    };
+    const splitter = createNdjsonSplitter({
+        onLine: handleLine,
+        onTooLarge: (bytes) => ports.onBadLine('bridge_frame_too_large', `Skipped a bridge frame of ${bytes} bytes.`),
+    });
+    const onData = (chunk) => splitter.push(chunk);
+    const onEnd = () => {
+        splitter.end();
+        finishAll();
+    };
+    const onError = () => finishAll();
+    options.input.setEncoding?.('utf-8');
+    options.input.on('data', onData);
+    options.input.on('end', onEnd);
+    options.input.on('error', onError);
+    return {
+        // THE REGISTRY OWNS THE SOURCES; this object only knows where stdin goes, so the
+        // one thing it cannot do is hand out a source of its own.
+        sourceFor: () => undefined,
+        finishAll,
+        close: () => {
+            finished = true;
+            options.input.removeListener('data', onData);
+            options.input.removeListener('end', onEnd);
+            options.input.removeListener('error', onError);
+            options.input.pause?.();
+        },
+        isFinished: () => finished,
+        queueDepth: () => 0,
+    };
+}

package/dist/exec/threads/execute-threads.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `execute()`'s equivalent for thread mode: one process, N conversations
+ * (headless-threads-and-lifecycle-hooks sections 2.3.3 / 2.3.7 / 2.3.8).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * THIS FILE OWNS EXACTLY FOUR THINGS, and everything else belongs to a thread:
+ *
+ *   1. the ONE writer and the ONE emitter (`seq` gap-free, `init` first, `result` last);
+ *   2. the ONE admission gate and the ONE thread registry;
+ *   3. the ONE process-level signal owner and the ONE process-level timer;
+ *   4. the ONE `decideProcessOutcome` call - the only place a process stop reason and exit
+ *      code are decided (I-T11).
+ *
+ * "PROCESS ENDS WHEN" HAS ONE ANSWER: stdin ended (the `end` frame or EOF) AND every opened
+ * thread is `closed`. `registry.drained()` is that condition, waited once at the end.
+ */
+import type { CliFlags } from '../../config/load.js';
+import type { ExecOptions } from '../options.js';
+import type { ResultSchemaSpec } from '../result/schema.js';
+import type { RunExecContext } from '../index.js';
+import { type ThreadPersistInput } from './runtime.js';
+export interface ExecuteThreadsInput {
+    flags: CliFlags;
+    options: ExecOptions;
+    /** The process-level session identity, already planned. */
+    plan: {
+        id: string;
+        saving: boolean;
+        cwd: string;
+    };
+    ctx: RunExecContext;
+    out: NodeJS.WritableStream;
+    err: NodeJS.WritableStream;
+    now: () => number;
+    version: string;
+    /** The caller's schema, preflighted once and shared by every thread (section 2.5). */
+    resultSpec: ResultSchemaSpec | null;
+    /** The raw stdin stream. A pre-built source would be a second splitter (I-T12). */
+    stdin: NodeJS.ReadableStream;
+    /** Writes one thread's session file; `exec/index.ts` owns the persistence details. */
+    persist: (input: ThreadPersistInput) => void;
+}
+/**
+ * Run a thread-mode invocation and resolve with the process exit code.
+ *
+ * EXIT 2 IS NOT PRODUCED HERE. Every flag, schema and session failure is decided before
+ * this function is reached, which is what keeps "exit 2 with nothing on stdout" a property
+ * of one module instead of two.
+ */
+export declare function executeThreads(input: ExecuteThreadsInput): Promise<number>;
+/** Exported for the smoke test and for `exec/index.ts`'s capability stamp. */
+export declare function threadCapabilities(): string[];

package/dist/exec/threads/execute-threads.js

@@ -0,0 +1,234 @@
+import { sessionPathFor, tryAcquireSessionLock } from '../../session/store.js';
+import { createEmitter } from '../emitter.js';
+import { execCapabilities } from '../events.js';
+import { createBridgeWriter } from '../bridge/writer.js';
+import { aggregateAccounts } from './aggregate.js';
+import { createAdmissionGate } from './gate.js';
+import { createInterruptOwner } from './interrupt.js';
+import { DEFAULT_THREAD_ID, createThreadRegistry } from './registry.js';
+import { createThreadRuntime, ThreadOpenError } from './runtime.js';
+import { decideProcessOutcome } from './outcome.js';
+import { createThreadDispatchSource } from './dispatch-source.js';
+/**
+ * Run a thread-mode invocation and resolve with the process exit code.
+ *
+ * EXIT 2 IS NOT PRODUCED HERE. Every flag, schema and session failure is decided before
+ * this function is reached, which is what keeps "exit 2 with nothing on stdout" a property
+ * of one module instead of two.
+ */
+export async function executeThreads(input) {
+    const { options, plan, ctx, out, now } = input;
+    const startedAt = now();
+    /** Set by the writer when the caller stopped reading; the run must exit 1. */
+    const hardLimit = { fired: false };
+    // THE ONE WRITER. Every thread's frames go through it so `seq` stays global and gap-free
+    // (I-C3) - which is also why the writer is created here and passed DOWN, never per thread.
+    const writer = createBridgeWriter({
+        out,
+        sessionId: plan.id,
+        onHardLimit: () => {
+            hardLimit.fired = true;
+            // NO MORE WORK IS SERVED: the frames would only be dropped by the sealed writer, and
+            // the process has to reach its `result` to report exit 1 at all.
+            registry?.finishAll();
+        },
+    });
+    const emitter = createEmitter(options.outputFormat, out, writer);
+    // ONE LATCH FOR THE ONE `result` (I-C2). The interrupt owner may call this from a signal
+    // handler *and* the normal tail calls it - both must produce exactly one line.
+    let resultWritten = false;
+    const buildResult = (stopReason, exitCode) => {
+        const accounts = registry?.accounts() ?? [];
+        const aggregate = aggregateAccounts(accounts);
+        return {
+            sessionId: plan.id,
+            isError: exitCode === 1 || hardLimit.fired,
+            stopReason: hardLimit.fired ? 'error' : stopReason,
+            exitCode,
+            result: '',
+            turns: accounts.reduce((sum, a) => sum + a.turns, 0),
+            durationMs: now() - startedAt,
+            usage: aggregate.usage,
+            cost: aggregate.cost,
+            model: mainModel,
+            todos: null,
+            acceptance: null,
+            threads: {
+                opened: aggregate.totals.opened,
+                closed: aggregate.totals.closed,
+                failed: aggregate.totals.failed,
+                items: accounts.map((account) => ({
+                    threadId: account.threadId,
+                    sessionId: account.sessionId,
+                    requests: account.requests,
+                    turns: account.turns,
+                    usage: account.usage,
+                    cost: account.cost,
+                    isError: account.isError,
+                    reason: account.reason,
+                })),
+            },
+            error: null,
+        };
+    };
+    const ensureResult = (stopReason) => {
+        if (resultWritten)
+            return;
+        resultWritten = true;
+        const decided = decideProcessOutcome({
+            interrupt: stopReason === 'interrupted' ? { signo: owner.signo() ?? 2 } : null,
+            timedOut: stopReason === 'timeout',
+            hardLimited: hardLimit.fired,
+            accounts: registry?.accounts() ?? [],
+        });
+        emitter.result(buildResult(decided.stopReason, decided.exitCode));
+    };
+    let registry = null;
+    let timedOut = false;
+    /** The default thread's model, so `result.model` names what actually ran. */
+    let mainModel = { provider: 'unknown', id: 'unknown' };
+    const gate = createAdmissionGate({ limit: options.threadConcurrency });
+    registry = createThreadRegistry({
+        baseSessionId: plan.id,
+        saving: plan.saving,
+        maxOpenThreads: options.maxOpenThreads,
+        gate,
+        write: (event) => writer.write(event),
+        acquireLock: (sessionId) => tryAcquireSessionLock(sessionId),
+        sessionFileFor: (sessionId) => (plan.saving ? sessionPathFor(sessionId) : null),
+        // `system/init` IS WRITTEN HERE, from the first thread's own controller (so `tools` is
+        // the real union and `model` is the resolved one) and BEFORE any `thread_state` - the
+        // writer flushes strictly in arrival order, so this is the only safe moment.
+        onFirstOpen: () => {
+            const main = registry?.runtimeFor(DEFAULT_THREAD_ID);
+            const described = main?.describe();
+            if (described)
+                mainModel = { provider: described.model.provider, id: described.model.id };
+            emitter.init({
+                sessionId: plan.id,
+                cli: input.version,
+                cwd: described?.cwd ?? plan.cwd,
+                startedAt,
+                model: described?.model ?? { provider: 'unknown', id: 'unknown', baseUrl: null },
+                permissionMode: options.permissionMode,
+                tools: described?.tools ?? [],
+                resumed: false,
+                sessionFile: described?.sessionFile ?? null,
+                bridge: true,
+                ...(input.resultSpec ? { structuredResult: true } : {}),
+                // THE POOL, IN THE SHAPE AC-8 FIXES (`maxOpen` / `concurrency` / `default`):
+                // three numbers and one name, so a wrapper can decide whether opening a fifth
+                // conversation is worth the round trip, and which thread it is already talking to.
+                threads: {
+                    maxOpen: options.maxOpenThreads,
+                    concurrency: options.threadConcurrency,
+                    default: DEFAULT_THREAD_ID,
+                },
+                hooks: true,
+            });
+        },
+        makeRuntime: ({ threadId, sessionId, sessionFile, lock, source }) => createThreadRuntime({
+            threadId,
+            sessionId,
+            sessionFile,
+            lock,
+            source,
+            flags: input.flags,
+            options,
+            version: input.version,
+            makeController: ctx.makeController,
+            emitter,
+            writer,
+            now,
+            resultSpec: input.resultSpec,
+            persist: input.persist,
+            hookTimeoutMs: options.hookTimeoutMs ?? 5_000,
+            // THE GATE'S RELEASE IS THE SOURCE'S (see `ThreadRuntimeDeps.source`): the slot is
+            // taken by the queue's `acquire()` and freed by its `release()`, at request
+            // granularity, inside the runner's own settle path. Releasing the gate from here as
+            // well would leave the queue believing it still holds a slot, and from that thread's
+            // second request onward `--thread-concurrency` would silently stop applying.
+        }),
+    });
+    const owner = createInterruptOwner({ fanout: registry, ensureResult });
+    const dispatch = createThreadDispatchSource({
+        input: input.stdin,
+        ports: {
+            deliverPrompt: (threadId, text, frameId) => registry?.deliverPrompt(threadId, text, frameId),
+            deliverControl: (threadId, frame) => registry?.deliverControl(threadId, frame),
+            // `hook_answer` IS A CONTROL FRAME: the thread's own server owns the hook ports, so a
+            // second route would be a second place to forget.
+            deliverHookAnswer: (threadId, frame) => registry?.deliverControl(threadId, frame),
+            handleThreadFrame: (frame) => {
+                if (frame.type === 'thread_open')
+                    registry?.handleOpen(frame);
+                else if (frame.type === 'thread_close')
+                    registry?.handleClose(frame);
+                else if (frame.type === 'thread_list')
+                    registry?.handleList(frame);
+            },
+            interruptProcess: () => owner.requestInterrupt(2),
+            rejectThreadedInterrupt: (threadId, frameId) => registry?.rejectThreadedInterrupt(threadId, frameId),
+            finishAll: () => registry?.finishAll(),
+            onBadLine: (code, message) => writer.write({
+                type: 'error',
+                sessionId: plan.id,
+                fatal: false,
+                code,
+                message,
+            }),
+        },
+    });
+    // THE ONE PROCESS-LEVEL TIMER (section 2.3.8b). Per-thread timers would fire at N
+    // different moments for one `result`, so the budget is measured once, here.
+    const durationTimer = options.maxDurationMs !== undefined
+        ? setTimeout(() => {
+            timedOut = true;
+            registry?.timeoutAll();
+        }, options.maxDurationMs)
+        : null;
+    durationTimer?.unref?.();
+    // THE ONE PROCESS-LEVEL TERMINATOR (section 2.3.8a).
+    owner.install();
+    try {
+        await registry.openDefault();
+    }
+    catch (error) {
+        dispatch.close();
+        gate.close();
+        const message = error instanceof ThreadOpenError
+            ? error.message
+            : `The run could not start: ${String(error)}`;
+        input.err.write(`${message}\n`);
+        return 2;
+    }
+    try {
+        await registry.drained();
+    }
+    finally {
+        if (durationTimer)
+            clearTimeout(durationTimer);
+        dispatch.close();
+        gate.close();
+    }
+    const accounts = registry.accounts();
+    const decided = decideProcessOutcome({
+        interrupt: owner.signo() === null ? null : { signo: owner.signo() },
+        timedOut,
+        hardLimited: hardLimit.fired,
+        accounts,
+    });
+    // EVERYTHING QUEUED BEHIND `result` GOES OUT FIRST, then `result`, then the seal - the
+    // same order the single-run path uses, for the same reason (`result` must be last).
+    await writer.flush();
+    if (!resultWritten) {
+        resultWritten = true;
+        emitter.result(buildResult(decided.stopReason, decided.exitCode));
+    }
+    await writer.close();
+    return decided.exitCode;
+}
+/** Exported for the smoke test and for `exec/index.ts`'s capability stamp. */
+export function threadCapabilities() {
+    return execCapabilities({ bridge: true, structuredResult: true, threads: true, hooks: true });
+}

package/dist/exec/threads/gate.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The admission gate: how many threads may hold a request in flight
+ * (headless-threads-and-lifecycle-hooks section 2.3.5).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * A COUNTING SEMAPHORE WITH THREE RULES, and no fourth:
+ *   - `acquire` resolves when a slot is free, FIFO;
+ *   - `release` frees one slot, once;
+ *   - `close` makes every waiter (and every later acquirer) throw, so a process
+ *     that is shutting down cannot be parked behind a slot that will never come.
+ *
+ * WHY FIFO RATHER THAN "WHOEVER ASKS NEXT": a caller that opened eight tenants in
+ * order expects them served in order. Preemption would let a noisy tenant starve a
+ * quiet one forever, and the slot is released at REQUEST granularity (not thread
+ * granularity), so fairness is cheap here.
+ *
+ * IT DOES NOT KNOW WHAT A REQUEST IS. The holder decides when to release; the gate
+ * only counts. That is what keeps this file 100 lines instead of a scheduler.
+ */
+export declare class GateClosedError extends Error {
+    constructor(message?: string);
+}
+export interface AdmissionGate {
+    /** Resolve once a slot is held. Rejects with `GateClosedError` after `close()`. */
+    acquire(threadId: string): Promise<void>;
+    /**
+     * Free one slot. Idempotent per ACQUISITION, not per call: releasing twice for one
+     * acquire is a programming error and throws, because the alternative is a gate that
+     * silently admits more requests than `--thread-concurrency` allows.
+     */
+    release(threadId: string): void;
+    /** Every waiter (and every later acquirer) throws `GateClosedError`. */
+    close(): void;
+    /** Slots currently held, for `thread_list` and for tests. */
+    inUse(): number;
+}
+export interface AdmissionGateOptions {
+    /** `--thread-concurrency`: the number of simultaneous slots. */
+    limit: number;
+}
+export declare function createAdmissionGate(options: AdmissionGateOptions): AdmissionGate;