@inflexa-ai/harness 0.45.1 → 0.46.0

package/dist/workflows/sandbox-step.js

@@ -7,10 +7,10 @@
  *
  *  1. `mark-running`        — update `cortex_step_executions` to running.
  *  2. `createSandbox`       — provision the sandbox; persist its handle.
- *  3. `runAgent`            — the harness agent loop. Every LLM and tool
- *                             call inside is its own durableStep.
- *  4. `generateFileMetadata`— the file-metadata continuation of the step agent.
- *  5. `generateStepSummary` — the summary continuation of the step agent,
+ *  3. `runLoop`             — the harness agent loop. Every model call and
+ *                             tool call inside is its own durable step.
+ *  4. `generateFileMetadata`— the file-metadata follow-up request of the step agent.
+ *  5. `generateStepSummary` — the summary follow-up request of the step agent,
  *                             producing `output/summary.md`.
  *  6. `reconcile + register`— write artifact manifest entries to cortex_artifacts.
  *  7. `syncArtifacts`       — register provenance + upload missing file_ids
@@ -20,25 +20,24 @@
  * 10. `mark-terminal`       — write the final status, emit `data-step-activity`
  *                             onto the parent's DBOS stream.
  *
- * The parent owns sibling lifecycle: the halt cascade of a suspension lives
- * on the parent (`executeAnalysis`). This child owns its own teardown and its
- * own suspension (workflow-suspension spec): a `suspend` error of the agent
- * loop, or a refusal with the suspend flag of the label gate or the register
- * gate. The child records the reason on its row, sends the typed suspension on
- * `CHILD_SUSPENDED_TOPIC`, and self-cancels to CANCELLED (resumable, not ERROR).
+ * The parent owns sibling lifecycle. This child owns its own teardown and its
+ * own pause (work-pause spec): a failed model request of the agent loop with a
+ * cause of a pause, or a refusal with the suspend flag of the label gate or the
+ * register gate. The child waits in place, and the run row stays `running`. The
+ * other steps go on, and each one pauses at its own failure.
  */
-import { DBOS, Error as DBOSErrors } from "@dbos-inc/dbos-sdk";
+import { DBOS } from "@dbos-inc/dbos-sdk";
+import { isWorkflowCancellation } from "../runtime/dbos.js";
 import { insertStepExecution, updateStepExecution } from "../state/index.js";
 import { recordStepCompleted } from "../lib/metrics.js";
 import { createNoopLogger } from "../lib/console-logger.js";
 import { deliverNotice } from "../lib/hooks.js";
 import { unwrapOrThrow } from "../lib/result.js";
-import { runAgent } from "../loop/run-agent.js";
-import { durableStep } from "../loop/run-step.js";
-import { maskExcept } from "../loop/tool-mask.js";
+import { maskExcept } from "../loop/call-policy.js";
+import { runLoop } from "../loop/run-loop.js";
 import { READ_TOOL_OUTPUT_TOOL_ID } from "../loop/tool-output.js";
 import { lastExecOutcome } from "../sandbox/exec-outcome.js";
-import { activityEmission, activityForTool, applyTreeDelta, isChatDataPart, sandboxTreeDelta, stepPartId } from "../sandbox/sandbox-step-translate.js";
+import { activityEmission, activityForTool, applyTreeDelta, isChatDataPart, sandboxTreeDelta, stepPartId, toolActivityKey, } from "../sandbox/sandbox-step-translate.js";
 import { createDetailResolver } from "../tools/detail-resolver.js";
 import { forSubAgent } from "../auth/types.js";
 import { walkStepArtifacts } from "../execution/post-step.js";
@@ -46,9 +45,9 @@ import { collectStepOutputs, describeStepRegistrationFailure, generateStepFileMe
 import { mintSandboxIdentity } from "../sandbox/identity.js";
 import { keepSuspendingRefusal } from "../sandbox/sandbox-error.js";
 import { ProvenanceCollector } from "../provenance/collector.js";
-import { createBlockerHolder, recordedBlocker } from "../tools/sandbox/report-blocker.js";
+import { blockerOf } from "../tools/sandbox/report-blocker.js";
 import { createFileMetadataCell, SUBMIT_FILE_METADATA_TOOL_ID } from "../tools/sandbox/submit-file-metadata.js";
-import { cancelSelf, suspensionOfFailure, suspensionOfRefusal, suspensionOfSpawnRefusal } from "./suspension.js";
+import { pauseAtGate, workPause } from "./pause.js";
 /**
  * Fallback when the plan step omits `timeout`. Plans that need 3-hour runs
  * declare it explicitly.
@@ -60,14 +59,6 @@ export const DEFAULT_STEP_TIMEOUT_SECONDS = 3600;
  * never model output — the summarizer does not run on this path.
  */
 export const CAPPED_OUT_EMPTY_REASON = "The step hit its iteration cap with no output files persisted.";
-/**
- * DBOS message topic the child uses to tell the parent that it suspends. The
- * message goes BEFORE `DBOS.cancelWorkflow(self)`, thus the parent's recv
- * accumulator records the child before the child's terminal state lands.
- * Without it the parent observes only `DBOSWorkflowCancelledError` from
- * `getResult`, and it cannot tell a suspension from a cancel.
- */
-export const CHILD_SUSPENDED_TOPIC = "child-suspended";
 // ── Helpers ───────────────────────────────────────────────────────────
 const NO_STEP_FILE_METADATA = { entries: [], messages: [] };
 /** Normalizes a pre-`messages` checkpoint (a bare entries array) for replay. */
@@ -153,27 +144,33 @@ export async function runSandboxStepBody(input, deps) {
             childWorkflowId,
         }));
     }, { name: "mark-running" });
-    // The sandbox, if one stands, stays up for the resume. The steps run only on
-    // this path, and a replay takes the same path from the same checkpoints.
-    const suspendStep = async (suspension) => {
-        const durationMs = (await DBOS.now()) - startedAt;
-        await DBOS.runStep(async () => {
-            unwrapOrThrow(await updateStepExecution(deps.pool, input.runId, input.stepId, {
-                status: "canceled",
-                durationMs,
-                error: suspension.reason,
-                attempts: 1,
-                lastErrorClass: suspension.reason,
-            }));
-            recordStepCompleted({ agentId: input.agentId, status: "canceled", durationMs });
-        }, { name: "mark-suspended" });
-        const message = { kind: "suspended", childWorkflowId, stepId: input.stepId, reason: suspension.reason };
-        await DBOS.runStep(() => DBOS.send(input.parentWorkflowId, message, CHILD_SUSPENDED_TOPIC), { name: "notify-parent-suspended" });
-        return cancelSelf("self-cancel-suspended");
+    // Each step part goes to the CHILD's own `"events"` stream. `DBOS.writeStream`
+    // writes only to the stream of its own workflow, so the SSE route reads the
+    // parent's stream plus every active child's, addressed by
+    // `cortex_step_executions.child_workflow_id`. A failed write is non-fatal.
+    const emitToParentStream = (part) => DBOS.writeStream("events", part);
+    const safeEmit = async (part) => {
+        try {
+            await emitToParentStream(part);
+        }
+        catch (err) {
+            logger.warn("emitToParentStream failed (non-fatal)", logger.errorFields(err));
+        }
     };
+    // The step waits in place, and the sandbox, if one stands, stays up for the resume.
+    const pause = workPause({
+        pool: deps.pool,
+        workId: input.runId,
+        workKind: "run",
+        analysisId: input.analysisId,
+        emit: safeEmit,
+        retryDelaysMs: deps.pauseRetryDelaysMs,
+        run: { session: input.runSession, authorizer: deps.runAuthorizer },
+        logger,
+    });
     // Stamp the sandbox agent's id into provenance so loop events carry
     // `source.agentId === input.agentId` (the parent's RunSession still reads
-    // "conversation-agent"). `run-agent.ts` builds source from
+    // "conversation-agent"). `run-loop.ts` builds source from
     // `session.provenance.agentId`, and billing tags ride the same provenance.
     const session = forSubAgent(input.runSession, input.agentId);
     const writePrefix = await deps.resolveWritePrefix(input);
@@ -193,11 +190,15 @@ export async function runSandboxStepBody(input, deps) {
         extraEnv: input.extraEnv,
         resources: input.resources,
     };
-    const spawned = await DBOS.runStep(async () => keepSuspendingRefusal(await deps.sandboxClient.createSandbox(session, sandboxSpec, identity)), {
+    const spawn = () => DBOS.runStep(async () => keepSuspendingRefusal(await deps.sandboxClient.createSandbox(session, sandboxSpec, identity)), {
         name: "sandbox.create",
     });
-    if (spawned.isErr())
-        return suspendStep(suspensionOfSpawnRefusal(spawned.error));
+    let spawned = await spawn();
+    // A refusal of the label gate with the suspend flag waits in a pause, and the spawn runs again after the resume.
+    while (spawned.isErr()) {
+        await pauseAtGate(pause, spawned.error.reason);
+        spawned = await spawn();
+    }
     const sandbox = spawned.value;
     // Recovery path: re-check `isAlive` on the persisted ref before continuing.
     // A classified-dead sandbox triggers a fresh `createSandbox` (task 4.6).
@@ -210,7 +211,7 @@ export async function runSandboxStepBody(input, deps) {
             throw new Error(`sandbox ${sandbox.sandboxId} ${cause} — caller must restart the step`);
         }
     }, { name: "sandbox.recheck-alive" });
-    // (3) runAgent — the harness loop with durableStep.
+    // (3) runLoop — the harness loop, each call a durable step.
     // The step deadline is captured ONCE at step start from the checkpointed
     // clock so it reproduces on replay — a raw `Date.now()` here would grow the
     // deadline on each recovery (see the harness-durable-runtime spec). `deadlineMs` is a getter so
@@ -218,7 +219,6 @@ export async function runSandboxStepBody(input, deps) {
     // fresh `now + timeout` per call would make a step with N tool calls runnable
     // for up to N × `timeoutSeconds`.
     const stepDeadlineMs = (await DBOS.now()) + (input.timeoutSeconds ?? DEFAULT_STEP_TIMEOUT_SECONDS) * 1000;
-    const blockerHolder = createBlockerHolder();
     const fileMetadata = createFileMetadataCell();
     const agent = await deps.buildAgent({
         input,
@@ -227,10 +227,10 @@ export async function runSandboxStepBody(input, deps) {
         stepWritePrefix: writePrefix,
         deadlineMs: () => stepDeadlineMs,
         lineageCollector,
-        blockerHolder,
+        reportsBlocker: true,
         fileMetadata,
         citationResolver: deps.citationResolver,
-        ...(deps.toolOutputStore ? { toolOutputStore: deps.toolOutputStore } : {}),
+        toolOutputStore: deps.toolOutputStore,
     });
     if (deps.toolOutputStore !== undefined && !agent.tools.some((tool) => tool.id === READ_TOOL_OUTPUT_TOOL_ID)) {
         logger.warn("the step agent declares no read_tool_output, thus its loops keep no text of a cut tool result");
@@ -245,37 +245,23 @@ export async function runSandboxStepBody(input, deps) {
     // `tool-finished`) and model-output deltas are wrapped under the
     // `data-loop-event` envelope so the SSE consumer can route them.
     //
-    // Every emit is `await`ed in order (the loop awaits its own emits, and the
-    // exec awaits its sandbox-event emits). A body-path `DBOS.writeStream` lands
+    // Every emit is `await`ed in order. A body-path `DBOS.writeStream` lands
     // at a deterministic function-ID on replay (see the harness-durable-runtime
     // spec) — no fire-and-forget tail racing the next real op for the counter.
-    // A sandbox event arrives from inside the step of its tool call; a write from
-    // a step takes no function-ID, and a recovered step writes its events again.
+    // The events of a tool call arrive from inside the step of the call; a write
+    // from a step takes no function-ID, and a recovered step writes its events again.
     // `safeEmit` swallows a stream-write failure: a dropped UI frame is
     // non-fatal and must not fail the step.
-    // Pattern A (fan-in at route): write to the CHILD's own `"events"` stream.
-    // `DBOS.writeStream` writes only to the stream of its own workflow, so the
-    // SSE route reads the parent's stream plus every active child's, addressed
-    // by `cortex_step_executions.child_workflow_id`.
-    const emitToParentStream = (part) => DBOS.writeStream("events", part);
-    const safeEmit = async (part) => {
-        try {
-            await emitToParentStream(part);
-        }
-        catch (err) {
-            logger.warn("emitToParentStream failed (non-fatal)", logger.errorFields(err));
-        }
-    };
     // Schema-conformant step-activity emitter. `data-step-activity` has a stable id per (runId, stepId),
     // so the run-stream fold collapses every phase transition latest-wins. Each emission also leaves one
     // `data-activity-entry` that the fold keeps, thus a late subscriber gets each line with its time. The
     // two parts share one checkpointed clock read. `activitySeq` advances before the clock read and the
     // writes, and each write fails alone through `safeEmit`.
     let activitySeq = 0;
-    const emitActivity = async (phase, activity) => {
-        const seq = activitySeq++;
+    const emitActivity = async (phase, activity, toolUseId) => {
+        const key = toolUseId === undefined ? activitySeq++ : toolActivityKey(toolUseId);
         const at = new Date(await DBOS.now()).toISOString();
-        const parts = activityEmission(input, seq, phase, activity, at);
+        const parts = activityEmission(input, key, phase, activity, at);
         await safeEmit(parts.activity);
         await safeEmit(parts.entry);
     };
@@ -287,7 +273,7 @@ export async function runSandboxStepBody(input, deps) {
     // stay free of internal paths/hashes/managed-root jargon. A DBOS cancellation is
     // control-flow, not a failure — re-raise it verbatim.
     const failStep = async (errorClass, err) => {
-        if (err instanceof DBOSErrors.DBOSWorkflowCancelledError)
+        if (isWorkflowCancellation(err))
             throw err;
         await tryTeardown(logger, deps, sandbox);
         const durationMs = (await DBOS.now()) - startedAt;
@@ -302,7 +288,7 @@ export async function runSandboxStepBody(input, deps) {
             errorClass,
             durationMs,
             hitMaxSteps,
-            ...(lastExec ? { lastExec } : {}),
+            lastExec,
             ...logger.errorFields(err),
         });
         const safe = userFacingStepFailure(errorClass);
@@ -359,7 +345,7 @@ export async function runSandboxStepBody(input, deps) {
         // envelope, and surface each tool call as live step activity.
         await safeEmit({ type: "data-loop-event", data: { stepId: input.stepId, event } });
         if (event.type === "tool-started") {
-            await emitActivity("executing", activityForTool(event.name, event.input, resolveDetail));
+            await emitActivity("executing", activityForTool(event.name, event.input, resolveDetail), event.toolUseId);
         }
     };
     const initial = [{ role: "user", content: input.prompt }];
@@ -368,39 +354,38 @@ export async function runSandboxStepBody(input, deps) {
     // is enforced at DBOS checkpoint (step) boundaries, not cooperatively in-loop.
     const neverAbort = new AbortController().signal;
     let transcript;
+    let steps;
     let finishReason;
     // `false` until the loop reports otherwise: a loop that throws never reached its cap.
     let hitMaxSteps = false;
     let stepUsage;
     try {
-        const agentResult = await runAgent(agent, initial, session, {
+        const agentResult = await runLoop(agent, initial, session, {
             provider: deps.provider,
             signal: neverAbort,
             emit,
-            runStep: durableStep,
             usageRecorder: deps.usageRecorder,
             toolOutputStore: deps.toolOutputStore,
-            formatStepName: {
-                llm: (iteration) => `llm:${iteration}`,
-                tool: (toolName, toolUseId) => `tool:${toolName}:${toolUseId}`,
+            // The agent declares the output tool of the file-metadata follow-up
+            // request from its first request, and the task must not use it.
+            policy: {
+                mask: maskExcept(agent.tools.map((tool) => tool.id), [SUBMIT_FILE_METADATA_TOOL_ID]),
             },
-            // The agent declares the output tool of the file-metadata
-            // continuation from its first request, and the task must not use it.
-            toolMask: maskExcept(agent.tools, [SUBMIT_FILE_METADATA_TOOL_ID]),
-            isFatalLoopError: (err) => err instanceof DBOSErrors.DBOSWorkflowCancelledError,
+            // A blocker ends the step: the agent declared that it cannot do the work.
+            stopWhen: (done) => blockerOf(done) !== null,
+            pause: pause.afterFailure,
         });
         transcript = agentResult.messages;
+        steps = agentResult.steps;
         finishReason = agentResult.finish.reason;
         hitMaxSteps = agentResult.finish.cappedOut;
         stepUsage = agentResult.finish.usage;
     }
     catch (err) {
-        const suspension = suspensionOfFailure(err);
-        if (suspension !== undefined)
-            return suspendStep(suspension);
-        // Non-resumable failure — tear down, mark failed (scrubbed), re-raise so
+        // A failure with a cause of a pause waited in the loop, thus this one fails the step: tear down, mark failed (scrubbed), re-raise so
         // the parent's `getResult` sees ERROR and the fail-fast cascade fires.
         // `failStep` always throws; the outer `throw` is for control-flow analysis.
+        // oxlint-disable-next-line typescript/only-throw-error -- `failStep` always throws inside; the outer `throw` only ends the code path, and a wrapper would erase the scrubbed cause the parent reads.
         throw await failStep("agent_loop", err);
     }
     // What the step's loop spent, emitted the moment the loop is done and before
@@ -428,11 +413,12 @@ export async function runSandboxStepBody(input, deps) {
     // Manifest walk, hoisted above the blocked branch so the capped-out
     // predicate can read it. The call is inline (not `DBOS.runStep`-wrapped),
     // so the hoist shifts no function id (see the harness-durable-runtime spec).
+    const noManifest = [];
     const manifest = await safeRunValue(logger, () => walkStepArtifacts({
         writePrefix,
         stepId: input.stepId,
         runId: input.runId,
-    }), "post-step.walk", []);
+    }), "post-step.walk", noManifest);
     // Blocker (see the harness-sandbox-agents spec): the agent declared it cannot fulfil the step. A
     // blocked step has no deliverables — skip the artifact post-step pipeline,
     // mark `blocked` (carrying the reason), emit the blocked part, and return a
@@ -444,9 +430,8 @@ export async function runSandboxStepBody(input, deps) {
     // reason. A capped-out step WITH artifacts stays on the completed path,
     // because partial output is real output.
     //
-    // A replay does not rerun `execute`, so the cell is empty then; the
-    // transcript is the durable record and takes precedence over the cell.
-    const blockerOutcome = recordedBlocker(transcript) ?? blockerHolder.outcome;
+    // The recorded calls give the blocker on the first run and on each replay alike.
+    const blockerOutcome = blockerOf(steps);
     const cappedOutEmpty = hitMaxSteps && manifest.length === 0;
     if (blockerOutcome || cappedOutEmpty) {
         const blockedReason = blockerOutcome?.reason ?? CAPPED_OUT_EMPTY_REASON;
@@ -479,7 +464,7 @@ export async function runSandboxStepBody(input, deps) {
             durationMs,
             finishReason,
             error: blockedReason,
-            ...(stepUsage ? { usage: stepUsage } : {}),
+            usage: stepUsage,
         };
     }
     // (4-8) post-step — the body is the explicit composition: the manifest from
@@ -533,21 +518,29 @@ export async function runSandboxStepBody(input, deps) {
         runId: input.runId,
         stepId: input.stepId,
     }, session));
-    let registered;
-    try {
-        registered = await reconcileAndRegisterStepArtifacts(deps, postCtx, manifest);
-    }
-    catch (attestationErr) {
-        if (attestationErr instanceof DBOSErrors.DBOSWorkflowCancelledError)
-            throw attestationErr;
+    const register = async () => {
+        let registration;
+        try {
+            registration = await reconcileAndRegisterStepArtifacts(deps, postCtx, manifest);
+        }
+        catch (attestationErr) {
+            if (isWorkflowCancellation(attestationErr))
+                throw attestationErr;
+            await syncStepArtifacts();
+            // oxlint-disable-next-line typescript/only-throw-error -- `failStep` always throws inside; the outer `throw` only ends the code path, and a wrapper would erase the scrubbed cause the parent reads.
+            throw await failStep("lineage_attestation", attestationErr);
+        }
         await syncStepArtifacts();
-        throw await failStep("lineage_attestation", attestationErr);
+        return registration;
+    };
+    let registered = await register();
+    // A refusal of the register gate with the suspend flag waits in a pause, and the registration runs again after the resume.
+    while (registered.isErr() && registered.error.kind === "refused" && registered.error.refusal.kind === "suspended") {
+        await pauseAtGate(pause, registered.error.refusal.reason);
+        registered = await register();
     }
-    await syncStepArtifacts();
     if (registered.isErr()) {
-        const refused = registered.error.kind === "refused" ? suspensionOfRefusal(registered.error.refusal) : undefined;
-        if (refused !== undefined)
-            return suspendStep(refused);
+        // oxlint-disable-next-line typescript/only-throw-error -- `failStep` always throws inside; the outer `throw` only ends the code path.
         throw await failStep("lineage_attestation", new Error(describeStepRegistrationFailure(registered.error)));
     }
     const reconciledManifest = registered.value;
@@ -629,7 +622,7 @@ export async function runSandboxStepBody(input, deps) {
         durationMs,
         finishReason,
         error: null,
-        ...(stepUsage ? { usage: stepUsage } : {}),
+        usage: stepUsage,
     };
 }
 /**
@@ -642,7 +635,7 @@ async function safeRun(logger, fn, label) {
         await fn();
     }
     catch (err) {
-        if (err instanceof DBOSErrors.DBOSWorkflowCancelledError)
+        if (isWorkflowCancellation(err))
             throw err;
         // The stage rides as a namespace, not interpolated prose: `label` is what
         // says WHICH post-step stage degraded, and a reader must be able to filter
@@ -660,7 +653,7 @@ async function safeRunValue(logger, fn, label, fallback) {
         return await fn();
     }
     catch (err) {
-        if (err instanceof DBOSErrors.DBOSWorkflowCancelledError)
+        if (isWorkflowCancellation(err))
             throw err;
         // The stage rides as a namespace, not interpolated prose: `label` is what
         // says WHICH post-step stage degraded, and a reader must be able to filter

package/dist/workflows/test/sql-writes.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The SQL write shapes that the workflow tests match on recorded queries. The
+ * templates of the body wrap their SQL across lines, so each shape carries the
+ * flexible whitespace of that wrapping. One matcher per write, named for the
+ * write it finds.
+ */
+export declare const ANALYSIS_STATE_WRITE: RegExp;
+export declare const PAUSE_RECORD_WRITE: RegExp;
+export declare const PAUSE_CLEAR_WRITE: RegExp;
+export declare const PAUSES_OF_WORK_CLEAR_WRITE: RegExp;
+export declare const RUNS_STATUS_WRITE: RegExp;
+export declare const RUNS_STATUS_WRITE_ANY_CASE: RegExp;
+export declare const SYNTHESIS_STATUS_WRITE: RegExp;
+export declare const STEP_SEED_INSERT: RegExp;
+export declare const ON_CONFLICT_DO_NOTHING: RegExp;
+export declare const ON_CONFLICT_DO_UPDATE: RegExp;
+export declare const STEP_STATUS_WRITE_PARAM: RegExp;
+export declare const SKIPPED_SWEEP_WRITE: RegExp;
+export declare const RUN_STATUS_WRITE_PARAM: RegExp;
+export declare const STEP_EXECUTIONS_UPDATE: RegExp;
+export declare const RUNS_PARTS_WRITE: RegExp;

package/dist/workflows/test/sql-writes.js

@@ -0,0 +1,36 @@
+/**
+ * The SQL write shapes that the workflow tests match on recorded queries. The
+ * templates of the body wrap their SQL across lines, so each shape carries the
+ * flexible whitespace of that wrapping. One matcher per write, named for the
+ * write it finds.
+ */
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- any write of the analysis row, across wrapped SQL lines
+export const ANALYSIS_STATE_WRITE = /UPDATE\s+cortex_analysis_state/i;
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- the row that a workflow writes before it waits in a pause, across wrapped SQL lines
+export const PAUSE_RECORD_WRITE = /INSERT INTO cortex_paused_work/i;
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- the delete of the row of one waiting workflow
+export const PAUSE_CLEAR_WRITE = /DELETE FROM cortex_paused_work WHERE workflow_id = \$1/i;
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- the delete of each row of a pause of one work
+export const PAUSES_OF_WORK_CLEAR_WRITE = /DELETE FROM cortex_paused_work WHERE work_id = \$1/i;
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- the run status write, across wrapped SQL lines
+export const RUNS_STATUS_WRITE = /UPDATE cortex_runs\s+SET status/;
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- the run status write in any letter case, across wrapped SQL lines
+export const RUNS_STATUS_WRITE_ANY_CASE = /UPDATE\s+cortex_runs\s+SET\s+status/i;
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- the synthesis status write on the run row, across wrapped SQL lines
+export const SYNTHESIS_STATUS_WRITE = /UPDATE\s+cortex_runs\s+SET\s+synthesis_status/i;
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- the seed insert of the step ledger, across wrapped SQL lines
+export const STEP_SEED_INSERT = /INSERT INTO cortex_step_executions/i;
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- the conflict arm of the seed insert, across wrapped SQL lines
+export const ON_CONFLICT_DO_NOTHING = /DO NOTHING/i;
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- the conflict arm of the mark-running upsert, across wrapped SQL lines
+export const ON_CONFLICT_DO_UPDATE = /DO UPDATE/i;
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- the parameterized terminal status write on the step ledger, across wrapped SQL lines
+export const STEP_STATUS_WRITE_PARAM = /UPDATE cortex_step_executions\s+SET status = \$1/i;
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- the terminal sweep of pending steps to skipped, across wrapped SQL lines
+export const SKIPPED_SWEEP_WRITE = /UPDATE cortex_step_executions\s+SET status = 'skipped'/i;
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- the parameterized run status write, across wrapped SQL lines
+export const RUN_STATUS_WRITE_PARAM = /UPDATE cortex_runs\s+SET status = \$1/i;
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- the step-ledger update that marks a canceled step, across wrapped SQL lines
+export const STEP_EXECUTIONS_UPDATE = /UPDATE\s+cortex_step_executions/i;
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- the parts write on the run row, across wrapped SQL lines
+export const RUNS_PARTS_WRITE = /UPDATE\s+cortex_runs\s+SET\s+parts/i;

package/dist/workspace/filesystem.d.ts

@@ -76,7 +76,7 @@ export type ReadBytesResult = {
 } | {
     readonly kind: "out_of_scope";
 };
-export interface WorkspaceFilesystem {
+export type WorkspaceFilesystem = {
     /**
      * Read a workspace file. `headLines` / `tailLines` (mutually exclusive,
      * enforced by the caller) constrain the read to the first N / last N
@@ -123,22 +123,22 @@ export interface WorkspaceFilesystem {
         readonly path: string;
         readonly workingDir?: string;
     }): ResultAsync<StatResult, FsError>;
-}
+};
 /**
  * Adapter for fetching files that aren't present locally. The managed
  * realization downloads via object-store presigned URLs; the OSS build omits
  * the fallback (files are local) and tests pass a fake.
  */
-export interface PresignedFallback {
+export type PresignedFallback = {
     fetch(args: {
         readonly session: AgentSession;
         readonly relativePath: string;
     }): Promise<Buffer | null>;
-}
-export interface WorkspaceFilesystemDeps {
+};
+export type WorkspaceFilesystemDeps = {
     /** Embedder-supplied workspace-root resolution seam (see workspace/paths.ts). */
     readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
     /** Optional fallback for files not present locally. */
     readonly presignedFallback?: PresignedFallback;
-}
+};
 export declare function createWorkspaceFilesystem(deps: WorkspaceFilesystemDeps): WorkspaceFilesystem;

package/dist/workspace/filesystem.js

@@ -34,7 +34,8 @@ import { createInterface } from "node:readline";
 import { join } from "node:path";
 import { ResultAsync, ok } from "neverthrow";
 import { scopeResource } from "../auth/types.js";
-import { tryFetch, tryFs } from "../lib/fs-result.js";
+import { tryFetch, tryFs, errnoOf } from "../lib/fs-result.js";
+import { splitLines } from "../lib/text.js";
 import { classifyWithinRoot } from "../lib/fs-helpers.js";
 import { resolveWorkspacePath } from "./paths.js";
 // ── Constructor ───────────────────────────────────────────────────────────
@@ -226,7 +227,8 @@ function collectEntries(dir, dirents) {
  * off-tree, re-opening the read-exfiltration hole for the length of the race
  * (CWE-367). `O_NOFOLLOW` makes the leaf open atomic — a symlinked final
  * component fails `ELOOP` in the same syscall that opens it, so there is no
- * check/use gap. `?? 0` keeps the mask valid on a platform that lacks the flag.
+ * check/use gap. On a platform that lacks the flag, the bitwise OR coerces the
+ * absent constant to 0 and the mask stays valid.
  *
  * This refuses EVERY leaf symlink, including an in-tree one the persistent check
  * would allow: pure Node cannot express "follow only if it stays in-tree" (that
@@ -236,7 +238,7 @@ function collectEntries(dir, dirents) {
  * exposes no `openat2`); the upstream realpath check still rejects the
  * persistent case of that.
  */
-const READ_NO_FOLLOW = fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0);
+const READ_NO_FOLLOW = fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW;
 /**
  * Open a workspace file read-only without following a leaf symlink (see
  * {@link READ_NO_FOLLOW}). A symlinked final component surfaces as `out_of_scope`
@@ -251,7 +253,7 @@ function openReadNoFollow(absolute) {
             return { kind: "ok", fh: await fsOpen(absolute, READ_NO_FOLLOW) };
         }
         catch (cause) {
-            if (cause.code === "ELOOP")
+            if (errnoOf(cause) === "ELOOP")
                 return { kind: "out_of_scope" };
             throw cause;
         }
@@ -372,7 +374,7 @@ function readTailLines(absolute, totalSize, tailLines, maxBytes) {
                 if (windowSize > 0) {
                     await fh.read(buf, 0, windowSize, offset);
                 }
-                const allLines = buf.toString("utf8").split(/\r?\n/);
+                const allLines = splitLines(buf.toString("utf8"));
                 // Drop the partial leading line if the window doesn't cover the file start.
                 const candidateLines = offset > 0 ? allLines.slice(1) : allLines;
                 const sliced = candidateLines.length > tailLines ? candidateLines.slice(-tailLines) : candidateLines;
@@ -391,7 +393,7 @@ function readTailLines(absolute, totalSize, tailLines, maxBytes) {
 }
 function sliceHeadLines(content, headLines, maxBytes) {
     const capped = maxBytes !== undefined && content.length > maxBytes ? content.subarray(0, maxBytes) : content;
-    const lines = capped.toString("utf8").split(/\r?\n/);
+    const lines = splitLines(capped.toString("utf8"));
     const slice = lines.slice(0, headLines);
     const out = Buffer.from(slice.join("\n"));
     if (maxBytes !== undefined && content.length > maxBytes && slice.length < headLines) {
@@ -401,12 +403,12 @@ function sliceHeadLines(content, headLines, maxBytes) {
 }
 function sliceTailLines(content, tailLines, maxBytes) {
     if (maxBytes === undefined || content.length <= maxBytes) {
-        const lines = content.toString("utf8").split(/\r?\n/);
+        const lines = splitLines(content.toString("utf8"));
         const slice = lines.length > tailLines ? lines.slice(-tailLines) : lines;
         return { kind: "ok", content: Buffer.from(slice.join("\n")), truncated: false };
     }
     const window = content.subarray(content.length - maxBytes);
-    const lines = window.toString("utf8").split(/\r?\n/).slice(1);
+    const lines = splitLines(window.toString("utf8")).slice(1);
     const slice = lines.length > tailLines ? lines.slice(-tailLines) : lines;
     const out = Buffer.from(slice.join("\n"));
     if (slice.length < tailLines) {

package/dist/workspace/paths.d.ts

@@ -204,7 +204,7 @@ export declare function reportSessionDir(threadId: string): string;
  */
 export declare function reportSessionDerivedDir(threadId: string): string;
 /**
- * True when `value` is a safe single path segment: the `SAFE_ID` charset (word
+ * True when `value` is a safe single path segment: the safe-id charset (word
  * chars, `.`, `-` — no slash, NUL, or shell-hostile char) AND not a pure-dot
  * segment (`.`/`..`), which the charset otherwise admits and which `resolve`/`join`
  * would treat as the current/parent directory and use to climb the tree. The one

package/dist/workspace/paths.js

@@ -179,7 +179,7 @@ export function toAnalysisRootPath(resourceId, path) {
         return joinAnalysisRoot(resourceId, normalizeTail(rooted));
     // A record holds no host path. Thus a leading slash is how a model writes the
     // same root-relative path, and the remainder is the tail.
-    const tail = normalizeTail(trimmed.replace(/^\/+/, ""));
+    const tail = normalizeTail(stripLeadingSlashes(trimmed));
     if (tail === ".." || tail.startsWith("../"))
         return trimmed;
     return joinAnalysisRoot(resourceId, tail);
@@ -239,9 +239,15 @@ function stripAnalysisRoot(path, analysisId) {
         return null;
     return slashIdx === -1 ? "" : withoutLead.slice(slashIdx + 1);
 }
-const SAFE_ID = /^[\w.-]+$/;
+/** The text without its leading slashes. */
+function stripLeadingSlashes(value) {
+    let start = 0;
+    while (start < value.length && value.charAt(start) === "/")
+        start++;
+    return value.slice(start);
+}
 /**
- * True when `value` is a safe single path segment: the `SAFE_ID` charset (word
+ * True when `value` is a safe single path segment: the safe-id charset (word
  * chars, `.`, `-` — no slash, NUL, or shell-hostile char) AND not a pure-dot
  * segment (`.`/`..`), which the charset otherwise admits and which `resolve`/`join`
  * would treat as the current/parent directory and use to climb the tree. The one
@@ -250,7 +256,12 @@ const SAFE_ID = /^[\w.-]+$/;
  * same at plan time and at mount time.
  */
 export function isSafeId(value) {
-    return SAFE_ID.test(value) && value !== "." && value !== "..";
+    return isSafeIdCharset(value) && value !== "." && value !== "..";
+}
+function isSafeIdCharset(value) {
+    if (value.length === 0)
+        return false;
+    return Array.from(value).every((char) => (char >= "a" && char <= "z") || (char >= "A" && char <= "Z") || (char >= "0" && char <= "9") || char === "_" || char === "." || char === "-");
 }
 /**
  * Throwing form of {@link isSafeId} for the mount/host-path builders. Ids are

package/dist/workspace/search-config.d.ts

@@ -5,7 +5,7 @@
  * read-time workspaces (chat, workflow agents) so they share the
  * same persistent per-analysis pgvector index.
  */
-import type { Pool } from "pg";
+import type { Querier } from "../state/db.js";
 /** Derive the vector index name for an analysis. */
 export declare function searchIndexName(resourceId: string): string;
 /**
@@ -20,4 +20,4 @@ export declare function searchIndexName(resourceId: string): string;
  * upsert. Per-analysis dimension tracking / re-embedding on a provider switch
  * is a deliberate non-feature for now.
  */
-export declare function ensureSearchIndex(pool: Pool, resourceId: string, dimensions: number): Promise<void>;
+export declare function ensureSearchIndex(pool: Querier, resourceId: string, dimensions: number): Promise<void>;