@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/dist/harness/owed-undos.js

@@ -0,0 +1,200 @@
+/**
+ * The undos still owed, done at every turn's start: the one place a person's
+ * Undo on a turn that has ended reaches the files.
+ *
+ * Review never makes a turn wait (stigmer#1471): a turn with review on ends
+ * with its edits applied, and a person may undo a change set while it is the
+ * conversation's newest turn. Two turns can then take the tree next, in
+ * either order: the reconcile turn the decision started, and a message sent
+ * right after it (the workspace lock does not order its waiters,
+ * `shared/workspace/workspace-lock.ts`). So the undo is not left to one of
+ * them: every turn's start does whatever is owed, under the lock, before
+ * anything else touches the tree (the eval scaffold, the mounts, the capture
+ * baseline), and an Undo always lands before the next model call. Whichever
+ * turn takes the tree first does the work; the other reads its
+ * `stigmer.file_review.reconciled` and skips.
+ *
+ * What is owed is keyed per undo, never per change set: a set's files can be
+ * undone one at a time, each after the last was put back, and an undo can be
+ * decided while a reconcile turn that already read the log is still running.
+ * Each undo is answered by its own `reconciled`, whose id names the undo's
+ * `decided` event (`events/ids.ts` `fileReviewReconciledEventId`).
+ *
+ * What is owed is read from the session's log, never from a run: the
+ * reconcile result cannot land on the change set's run, which has finished
+ * and which this runner may not write. One bounded read, newest first, of
+ * `user.message`, `stigmer.file_review.decided` and
+ * `stigmer.file_review.reconciled`, back to and including the newest
+ * `user.message` that is not this run's: a change set is decidable only
+ * while its turn's message is the newest, so no undo older than that slice
+ * can still be owed. An `undo` decided in the slice with no `reconciled`
+ * answering it is owed. The change set's files are read from its run's
+ * file record (`getExecution`, `status.file_changes`), which the run's
+ * credential may view as the person who created this run. Its decisions are
+ * the slice's own `decided` events for the set, every `keep` and `undo`: a
+ * set is decidable only while its turn's message is the newest, so the
+ * slice, which reaches back to that message, holds every decision on any
+ * set with an undo owed.
+ *
+ * The work is `shared/filereview/capture.ts` `undoChangeSet`, once per
+ * change set with an undo owed, with its hash guard: it restores every file
+ * the set's decisions undo, so a file an earlier undo already put back is
+ * put back again, unchanged. Its outcome is written at once as one
+ * `reconciled` event per owed undo, naming the files that undo covers
+ * (`events/emitter.ts` `writeReconciled`). Nothing is written to any ledger.
+ *
+ * Then, in a message turn only, the capture refs of the previous message
+ * turn's run are dropped (`git-substrate.ts` `dropCaptureRefs`): that turn's
+ * window closed when this turn's message was sent, so nothing can undo it
+ * any more and its pinned trees would only pile up in the workspace. A
+ * reconcile turn drops nothing: the window of the turn it serves is still
+ * open.
+ */
+import { undoChangeSet } from "../shared/filereview/capture.js";
+import { casBlobReader } from "../shared/filereview/cas-substrate.js";
+import { changeSetIdParts } from "../shared/filereview/events.js";
+import { dropCaptureRefs } from "../shared/filereview/git-substrate.js";
+import { fileReviewReconciledEventId } from "./events/ids.js";
+/** The log types the owed read asks for. */
+export const OWED_UNDO_EVENT_TYPES = [
+    "user.message",
+    "stigmer.file_review.decided",
+    "stigmer.file_review.reconciled",
+];
+/** One page of the owed read: enough for an ordinary turn's decisions in one call. */
+const OWED_READ_PAGE_SIZE = 200;
+/**
+ * Read what is owed from the log (the module header). Pages newest first
+ * until the newest `user.message` that is not `runId`'s, that event
+ * included, or the log's start.
+ */
+export async function readOwedUndos(client, sessionId, runId) {
+    const slice = [];
+    let previousMessageRunId;
+    let pageToken = "";
+    read: do {
+        const page = await client.listSessionEvents(sessionId, {
+            types: OWED_UNDO_EVENT_TYPES,
+            order: "desc",
+            pageSize: OWED_READ_PAGE_SIZE,
+            pageToken,
+        });
+        for (const event of page.events) {
+            slice.push(event);
+            if (event.event.case === "userMessage" && event.runId !== runId) {
+                previousMessageRunId = event.runId;
+                break read;
+            }
+        }
+        pageToken = page.nextPageToken;
+    } while (pageToken !== "");
+    return { undos: owedUndos(slice), decisions: decisionsBySet(slice), previousMessageRunId };
+}
+/**
+ * The `decided` events in `slice` (newest first, as read), by change set,
+ * oldest first. A decision on a set is written under the set's own run (the
+ * set id's `<run id>:` part); one written under any other run decides
+ * nothing here.
+ */
+export function decisionsBySet(slice) {
+    const out = new Map();
+    for (const event of [...slice].reverse()) {
+        if (event.event.case !== "stigmerFileReviewDecided")
+            continue;
+        const { changeSetId, scope, fileChangeId, action } = event.event.value;
+        if (event.runId !== changeSetIdParts(changeSetId).runId)
+            continue;
+        const list = out.get(changeSetId) ?? [];
+        list.push({ scope, fileChangeId, action });
+        out.set(changeSetId, list);
+    }
+    return out;
+}
+/**
+ * The undos decided in `slice` (newest first, as read) that no `reconciled`
+ * answers, oldest first, each once.
+ */
+export function owedUndos(slice) {
+    const answered = new Set();
+    for (const event of slice) {
+        if (event.event.case === "stigmerFileReviewReconciled")
+            answered.add(event.event.value.id);
+    }
+    const owed = [];
+    for (const event of [...slice].reverse()) {
+        if (event.event.case !== "stigmerFileReviewDecided" || event.event.value.action !== "undo")
+            continue;
+        const { id, changeSetId, scope, fileChangeId } = event.event.value;
+        if (answered.has(fileReviewReconciledEventId(changeSetId, id)) || owed.some((undo) => undo.decidedEventId === id))
+            continue;
+        owed.push({ decidedEventId: id, changeSetId, scope, fileChangeId });
+    }
+    return owed;
+}
+/**
+ * Do every undo still owed (the module header) and return what each change
+ * set put back. A turn with no primary tree has no files to put back and
+ * reads nothing. A change set that cannot be read from its run answers
+ * `reconcile_failed`, so its undos are recorded once and not tried again by
+ * every later start of the same window.
+ */
+export async function reconcileOwedUndos(deps) {
+    const { client, runId, sessionId, workspace } = deps;
+    const gitRoot = workspace.primaryDir;
+    if (!gitRoot)
+        return [];
+    const owed = await readOwedUndos(client, sessionId, runId);
+    const outcomes = [];
+    const answers = [];
+    for (const changeSetId of [...new Set(owed.undos.map((undo) => undo.changeSetId))]) {
+        const outcome = await undoOne(deps, gitRoot, changeSetId, owed.decisions.get(changeSetId) ?? []);
+        outcomes.push(outcome);
+        for (const undo of owed.undos.filter((owedUndo) => owedUndo.changeSetId === changeSetId)) {
+            answers.push(answerFor(undo, outcome));
+        }
+    }
+    if (outcomes.length > 0) {
+        for (const outcome of outcomes) {
+            console.log(`[owed-undos] run=${runId}: change set ${outcome.changeSetId}: ` +
+                (outcome.failure === "" ? `put back ${outcome.undonePaths.length} file(s)` : `${outcome.failure}: ${outcome.failureDetail}`));
+        }
+        await deps.recordReconciled(answers);
+    }
+    if (!deps.reconcileTurn && workspace.gitWorkspace && owed.previousMessageRunId !== undefined) {
+        await dropCaptureRefs(gitRoot, owed.previousMessageRunId);
+    }
+    return outcomes;
+}
+/**
+ * One undo's answer from its change set's outcome: the files it covers that
+ * were put back (every one for a change-set undo, its own file for a file
+ * undo), or the set's failure.
+ */
+function answerFor(undo, outcome) {
+    const undonePaths = outcome.failure !== "" || undo.scope !== "file"
+        ? outcome.undonePaths
+        : outcome.undonePaths.filter((path) => `${undo.changeSetId}:${path}` === undo.fileChangeId);
+    return { ...outcome, undonePaths, decidedEventId: undo.decidedEventId };
+}
+/** One owed change set: read its files from its run's file record, then undo it under the decisions the log holds. */
+async function undoOne(deps, gitRoot, changeSetId, decisions) {
+    const failed = (failureDetail) => ({ changeSetId, undonePaths: [], failure: "reconcile_failed", failureDetail });
+    let run;
+    try {
+        run = await deps.client.getExecution(changeSetIdParts(changeSetId).runId);
+    }
+    catch (err) {
+        return failed(`the turn's changes could not be read: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const changeSet = run.status?.fileChanges.find((set) => set.id === changeSetId);
+    if (changeSet === undefined)
+        return failed("the turn holds no such change set");
+    return undoChangeSet({
+        gitRoot,
+        changeSet,
+        decisions,
+        gitWorkspace: deps.workspace.gitWorkspace,
+        readBlob: deps.artifactStorage ? casBlobReader(deps.artifactStorage) : undefined,
+    });
+}
+//# sourceMappingURL=owed-undos.js.map

package/dist/harness/owed-undos.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"owed-undos.js","sourceRoot":"","sources":["../../src/harness/owed-undos.ts"],"names":[],"mappings":"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"}

package/dist/harness/persist-chokepoint.d.ts

@@ -0,0 +1,113 @@
+/**
+ * The turn runtime's single persist chokepoint: every write of the
+ * execution status during a turn — the adapter's streaming requests, the
+ * runtime's own terminal writes — goes through here and nowhere else, so
+ * the guards that must never be skipped cannot be skipped by a call site
+ * that forgot them.
+ *
+ * What one write does, in order:
+ *  1. The never-persist-secret backstop: content is withheld from
+ *     any built-in write row targeting a secret-like path, top-level and
+ *     sub-agent, before the rows reach the session's log. The single
+ *     airtight choke point for a deny-gate harness and the only guarantee
+ *     under `auto_approve_all`. Idempotent.
+ *  2. `file_change_progress` is refreshed from the turn's capture (the "N
+ *     files changed so far" strip) when the turn is in capture mode:
+ *     the tree is read at most once per floor interval and only re-attached
+ *     when it moved (`shared/filereview/progress.ts`), so a write that
+ *     changed nothing on disk carries the snapshot it already had. Before
+ *     #1096 each adapter's stream loop did this before its own persists; the
+ *     runtime owns the capture now, so the display field it derives is
+ *     refreshed where every other runtime-owned field is — here. A capture
+ *     that fails is skipped there, never thrown, so it never fails the write
+ *     and `request()` keeps its promise to the adapters.
+ *  3. `streaming_usage` is refreshed from the accumulator when it has turns,
+ *     so the summary the UI shows is the one the write carries.
+ *  4. The run's file record: the change sets of the rows' ledger the server
+ *     has not seen as they stand (`shared/filereview/record.ts`
+ *     `FileRecordSender`), on this write only; marked sent once it lands.
+ *  5. `persistStatus` (`shared/status.ts`): tool-output offload over the
+ *     rows, then the
+ *     session event flush (`events/emitter.ts`: what the agent did, read from
+ *     the rows as offloaded and appended to the session's log before the
+ *     status that follows it), then the aggregate size cap, transient
+ *     retry, oversize recovery. Never rejects. The flush is a second RPC
+ *     under the same single flight: an adapter's coalesced follow-up covers
+ *     both. The status sent carries lifecycle, stamps and files, never the
+ *     rows.
+ *  6. A Temporal heartbeat, so a long streaming turn's liveness is proven by
+ *     the writes it makes.
+ *  7. The control plane's answer: STOP becomes the runtime's platform-stop
+ *     cause on the stop controller, which aborts the adapter's signal.
+ *
+ * Single-flight with coalescing: an adapter's `requestPersist()` while a
+ * write is in flight does not start a second concurrent write (two writes of
+ * one status racing on the wire is the drift the chokepoint exists to
+ * prevent); it schedules ONE follow-up write after the current one lands,
+ * and resolves when that follow-up has. The promise it returns therefore
+ * always means "the state as of my request is on the control plane", which
+ * is what lets the Cursor loop await it and see a STOP before it pulls the
+ * next event, exactly as its own inline persist did.
+ *
+ * The runtime's terminal writes use the same path (`write()`), so the
+ * secret backstop and the usage summary ride the final status too, as they
+ * did when the orchestrator's `persist` closure was the one place to write.
+ */
+import type { RunStatus } from "@stigmer/apis/ai/stigmer/agentic/run/v1/api_pb";
+import type { StigmerClient } from "../client/stigmer-client.js";
+import type { ToolOutputOffloadContext } from "../shared/status-offload.js";
+import type { SessionEventEmitter } from "./events/emitter.js";
+import type { TurnProgress } from "./capture.js";
+import type { UsageAccumulator } from "./usage-accumulator.js";
+import type { TurnRows } from "../gen/turn/ai/stigmer/runner/turn/v1/rows_pb.js";
+export interface PersistChokepointDeps {
+    readonly client: StigmerClient;
+    readonly executionId: string;
+    readonly status: RunStatus;
+    /** The turn's rows: bounded and read into the session's log on every write, never sent with the status. */
+    readonly rows: TurnRows;
+    /** Present when artifact storage resolved; enables tool-output offload on every write. */
+    readonly offload: ToolOutputOffloadContext | undefined;
+    /**
+     * The accumulator, read at WRITE time: it exists only once the runtime has
+     * the turn's model preferences, after resolution, so it arrives as a thunk
+     * and is `undefined` for a write made before then (no usage yet anyway).
+     */
+    readonly usage: () => UsageAccumulator | undefined;
+    /**
+     * The turn's mid-run progress, read at WRITE time for the same reason as
+     * `usage`: it exists only once the runtime has pinned the capture baseline,
+     * after resolution, and is `undefined` outside capture mode.
+     */
+    readonly progress: () => TurnProgress | undefined;
+    /** The Temporal heartbeat, pulsed after each write. */
+    readonly heartbeat: () => void;
+    /** The control plane answered STOP to this write. */
+    readonly onPlatformStop: () => void;
+    /** Writes the session's events from the rows each write carries; absent in tests that do not read the log. */
+    readonly events?: Pick<SessionEventEmitter, "flush">;
+}
+export declare class PersistChokepoint {
+    private readonly deps;
+    private inFlight;
+    private followUp;
+    private readonly fileRecord;
+    constructor(deps: PersistChokepointDeps);
+    /**
+     * The adapter's `requestPersist()`: a write now, or one follow-up write
+     * after the in-flight one. Resolves when the state as of this call has
+     * been written. Never rejects.
+     */
+    request(): Promise<void>;
+    /**
+     * One write, now. The runtime's own writes (a settlement, a terminal
+     * status) call this directly: they run when no adapter write can be in
+     * flight (before `runTurn` or after it settled), so they need no
+     * coalescing, and they must not be deferred behind one. `final` marks the
+     * turn's terminal write: the boundary has run and nothing streams, so the
+     * session event emitter writes every row that is left.
+     */
+    write(opts?: {
+        readonly final?: boolean;
+    }): Promise<void>;
+}

package/dist/harness/persist-chokepoint.js

@@ -0,0 +1,126 @@
+/**
+ * The turn runtime's single persist chokepoint: every write of the
+ * execution status during a turn — the adapter's streaming requests, the
+ * runtime's own terminal writes — goes through here and nowhere else, so
+ * the guards that must never be skipped cannot be skipped by a call site
+ * that forgot them.
+ *
+ * What one write does, in order:
+ *  1. The never-persist-secret backstop: content is withheld from
+ *     any built-in write row targeting a secret-like path, top-level and
+ *     sub-agent, before the rows reach the session's log. The single
+ *     airtight choke point for a deny-gate harness and the only guarantee
+ *     under `auto_approve_all`. Idempotent.
+ *  2. `file_change_progress` is refreshed from the turn's capture (the "N
+ *     files changed so far" strip) when the turn is in capture mode:
+ *     the tree is read at most once per floor interval and only re-attached
+ *     when it moved (`shared/filereview/progress.ts`), so a write that
+ *     changed nothing on disk carries the snapshot it already had. Before
+ *     #1096 each adapter's stream loop did this before its own persists; the
+ *     runtime owns the capture now, so the display field it derives is
+ *     refreshed where every other runtime-owned field is — here. A capture
+ *     that fails is skipped there, never thrown, so it never fails the write
+ *     and `request()` keeps its promise to the adapters.
+ *  3. `streaming_usage` is refreshed from the accumulator when it has turns,
+ *     so the summary the UI shows is the one the write carries.
+ *  4. The run's file record: the change sets of the rows' ledger the server
+ *     has not seen as they stand (`shared/filereview/record.ts`
+ *     `FileRecordSender`), on this write only; marked sent once it lands.
+ *  5. `persistStatus` (`shared/status.ts`): tool-output offload over the
+ *     rows, then the
+ *     session event flush (`events/emitter.ts`: what the agent did, read from
+ *     the rows as offloaded and appended to the session's log before the
+ *     status that follows it), then the aggregate size cap, transient
+ *     retry, oversize recovery. Never rejects. The flush is a second RPC
+ *     under the same single flight: an adapter's coalesced follow-up covers
+ *     both. The status sent carries lifecycle, stamps and files, never the
+ *     rows.
+ *  6. A Temporal heartbeat, so a long streaming turn's liveness is proven by
+ *     the writes it makes.
+ *  7. The control plane's answer: STOP becomes the runtime's platform-stop
+ *     cause on the stop controller, which aborts the adapter's signal.
+ *
+ * Single-flight with coalescing: an adapter's `requestPersist()` while a
+ * write is in flight does not start a second concurrent write (two writes of
+ * one status racing on the wire is the drift the chokepoint exists to
+ * prevent); it schedules ONE follow-up write after the current one lands,
+ * and resolves when that follow-up has. The promise it returns therefore
+ * always means "the state as of my request is on the control plane", which
+ * is what lets the Cursor loop await it and see a STOP before it pulls the
+ * next event, exactly as its own inline persist did.
+ *
+ * The runtime's terminal writes use the same path (`write()`), so the
+ * secret backstop and the usage summary ride the final status too, as they
+ * did when the orchestrator's `persist` closure was the one place to write.
+ */
+import { create } from "@bufbuild/protobuf";
+import { RunControlSignal } from "@stigmer/apis/ai/stigmer/agentic/run/v1/enum_pb";
+import { StreamingUsageSummarySchema } from "@stigmer/apis/ai/stigmer/agentic/run/v1/usage_pb";
+import { captureFileChangeProgress } from "../shared/filereview/progress.js";
+import { FileRecordSender } from "../shared/filereview/record.js";
+import { persistStatus } from "../shared/status.js";
+import { withholdSecretContentFromMessages } from "../shared/tool-row.js";
+export class PersistChokepoint {
+    deps;
+    inFlight;
+    followUp;
+    fileRecord = new FileRecordSender();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * The adapter's `requestPersist()`: a write now, or one follow-up write
+     * after the in-flight one. Resolves when the state as of this call has
+     * been written. Never rejects.
+     */
+    request() {
+        if (this.inFlight === undefined) {
+            const write = this.write().finally(() => {
+                this.inFlight = undefined;
+            });
+            this.inFlight = write;
+            return write;
+        }
+        if (this.followUp === undefined) {
+            this.followUp = this.inFlight.then(() => {
+                this.followUp = undefined;
+                return this.request();
+            });
+        }
+        return this.followUp;
+    }
+    /**
+     * One write, now. The runtime's own writes (a settlement, a terminal
+     * status) call this directly: they run when no adapter write can be in
+     * flight (before `runTurn` or after it settled), so they need no
+     * coalescing, and they must not be deferred behind one. `final` marks the
+     * turn's terminal write: the boundary has run and nothing streams, so the
+     * session event emitter writes every row that is left.
+     */
+    async write(opts = {}) {
+        const { client, executionId, status, rows, offload, heartbeat } = this.deps;
+        withholdSecretContentFromMessages(rows.messages, rows.subAgentRuns);
+        const progress = this.deps.progress();
+        if (progress) {
+            await captureFileChangeProgress({ status, changeSetId: progress.changeSetId, substrate: progress.substrate, state: progress.state });
+        }
+        const usage = this.deps.usage();
+        if (usage?.hasTurns) {
+            status.streamingUsage = create(StreamingUsageSummarySchema, usage.snapshot());
+        }
+        const events = this.deps.events;
+        const record = this.fileRecord.pending(rows);
+        status.fileChanges = record;
+        const signal = await persistStatus(client, executionId, status, {
+            rows,
+            offload,
+            onWritten: () => this.fileRecord.written(record),
+            ...(events ? { afterOffload: () => events.flush(rows, { final: opts.final === true }) } : {}),
+        });
+        heartbeat();
+        if (signal === RunControlSignal.STOP) {
+            this.deps.onPlatformStop();
+        }
+    }
+}
+//# sourceMappingURL=persist-chokepoint.js.map

package/dist/harness/persist-chokepoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persist-chokepoint.js","sourceRoot":"","sources":["../../src/harness/persist-chokepoint.ts"],"names":[],"mappings":"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"}

package/dist/harness/registry.d.ts

@@ -0,0 +1,108 @@
+/**
+ * The harness registry — the lifecycle fan-out over the adapters a worker
+ * runs, and the byte-pinned binding from harness to Temporal activity name.
+ *
+ * Plain functions over an `adapters` argument, no module state and no DI
+ * (the composition roots are staged plain functions; a missing adapter is a
+ * compile error or a loud boot throw, never a silent no-op). ORDER IS
+ * LOAD-BEARING: `bootHarnesses` runs adapters in declaration order because
+ * the Cursor harness's interceptors must patch `node:http2` before anything
+ * dials the control plane, and `shutdownHarnesses` runs them in reverse so
+ * what was set up last is torn down first.
+ *
+ * Error posture (fixed in #1064):
+ *  - Boot validates the whole table BEFORE booting anything (a duplicate name
+ *    is a configuration defect, and a half-booted worker is the worst state to
+ *    discover it in), then fails fast at the first adapter that rejects. A
+ *    worker that cannot boot a harness must not start.
+ *  - Shutdown and session release CONTINUE past a failing adapter and throw
+ *    one `AggregateError` at the end naming each failure, so one bad teardown
+ *    never leaks the others' resources.
+ *
+ * `createHarnessActivities` binds each row to its Temporal activity over the
+ * turn runtime (`run-turn.ts`). The table of real rows is NOT here: it lives
+ * at the source root (`src/harness-adapters.ts`), because a row imports its
+ * adapter from `activities/` and nothing under `src/harness/` may
+ * (`__tests__/import-direction.test.ts`). The registry knows rows,
+ * never which adapters exist.
+ *
+ * `HarnessName` lives here and not in `types.ts` on purpose: the wire
+ * vocabulary is the registry's concern. An adapter never declares the
+ * activity it is bound to (its `name` is a diagnostic identity); the registry
+ * row does.
+ *
+ * THIS MODULE'S STATIC GRAPH MUST STAY CONNECT-FREE. Both composition roots
+ * import it BEFORE they boot the harnesses, and the Cursor adapter's boot
+ * patches `node:http2` (its HTTP/2 auth interceptor); a static import of
+ * anything that loads `@connectrpc/connect-node` here would snapshot the
+ * `node:http2` ESM facade to the unpatched `connect` before that boot ran,
+ * and every BiDi stream would silently 401. So `StigmerClient` is loaded
+ * with a dynamic import inside `createHarnessActivities`, the runner's
+ * dynamic-import-for-order convention (`bootstrap.ts` documents the same
+ * omission for the same reason). `__tests__/harness-boot-order.test.ts`
+ * boots a fresh process through this module and fails if the facade froze.
+ */
+import type { Config } from "../config.js";
+import { type ExecuteActivityInput } from "../shared/activity-input.js";
+import type { HarnessAdapter } from "./types.js";
+/** The harnesses the control plane can dispatch to, as the registry knows them. */
+export type HarnessName = "cursor" | "deep-agent";
+/**
+ * Byte-pinned Temporal activity names, one per harness. The server side of
+ * the pin is `stigmer-server/src/temporal/agentexecution/names.ts`
+ * (`EXECUTE_CURSOR_ACTIVITY_NAME`, `EXECUTE_DEEP_AGENT_ACTIVITY_NAME`); the
+ * two must stay byte-identical or the workflow schedules an activity no
+ * worker registers. Never "cleaned up".
+ */
+export declare const HARNESS_ACTIVITY_NAMES: {
+    readonly cursor: "ExecuteCursor";
+    readonly "deep-agent": "ExecuteDeepAgent";
+};
+export type HarnessActivityName = (typeof HARNESS_ACTIVITY_NAMES)[HarnessName];
+/** One harness the worker serves: the wire name it answers to and the adapter that runs its turns. */
+export interface HarnessRow {
+    readonly harness: HarnessName;
+    readonly adapter: HarnessAdapter;
+}
+/**
+ * The legacy positional activity signature, kept as the wire shape both
+ * control planes send until they both send the typed object
+ * (`shared/activity-input.ts`). Every harness's activity has it.
+ */
+export type HarnessActivity = (arg0: ExecuteActivityInput | string, arg1?: string) => Promise<unknown>;
+/** The row serving `harness`; a harness the table lacks is a wiring defect, so it throws. */
+export declare function harnessRowFor(rows: readonly HarnessRow[], harness: HarnessName): HarnessRow;
+/** The adapters of a row list, for the lifecycle functions below. */
+export declare function adaptersOf(rows: readonly HarnessRow[]): HarnessAdapter[];
+/**
+ * One Temporal activity per row, under the row's byte-pinned name, over ONE
+ * `StigmerClient` for all of them (each harness used to build its own). The
+ * activity normalizes the wire input, brackets the turn with the idle
+ * watchdog, and hands the turn runtime the adapter. The roots spread the
+ * result into the worker's activity map beside the activities the runtime
+ * does not own.
+ *
+ * Async because the client is loaded here, not at the top of the module (see
+ * the header): the roots call this after the harnesses have booted, when
+ * connect-node may load.
+ */
+export declare function createHarnessActivities(rows: readonly HarnessRow[], config: Config): Promise<Partial<Record<HarnessActivityName, HarnessActivity>>>;
+/**
+ * Boot every adapter in declaration order, one at a time, awaiting each. The
+ * table is validated first; the first rejection stops the boot and propagates
+ * (adapters after it are never booted; adapters before it stay booted for the
+ * caller's shutdown path to release).
+ */
+export declare function bootHarnesses(adapters: readonly HarnessAdapter[], config: Config): Promise<void>;
+/**
+ * Shut every adapter down in reverse declaration order, continuing past
+ * failures. Rejects with one `AggregateError` carrying every failure once all
+ * adapters have been given their chance.
+ */
+export declare function shutdownHarnesses(adapters: readonly HarnessAdapter[]): Promise<void>;
+/**
+ * Tell every adapter the session is done on this host, in declaration order,
+ * continuing past failures. An adapter that parks nothing per session
+ * resolves as a no-op; the registry does not know which do.
+ */
+export declare function releaseHarnessSession(adapters: readonly HarnessAdapter[], sessionId: string): Promise<void>;