@schnick371/devsteps-shared 1.1.0-next.3 → 2.0.0-next.1

package/dist/runtime/workflow-v2-types.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Run protocol of compiled workflows (schema_version "2.0").
+ * Receipts, human responses, step outputs, verdict severity, and the side-effect order.
+ */
+import { z } from 'zod';
+import { WorkflowErrorCode, type WorkflowRouteVerdict, WorkflowSideEffect } from '../schemas/workflow-v2-vocabulary.js';
+/** The parties are schema vocabulary, because a step names its intended party in `who`. */
+export { WorkflowParty } from '../schemas/workflow-v2-vocabulary.js';
+/** Who works a v2 run: the person alone, the person with the agent, or the agent alone. */
+export declare const WorkflowRunMode: z.ZodEnum<{
+    agent: "agent";
+    operator: "operator";
+    together: "together";
+}>;
+export type WorkflowRunMode = z.infer<typeof WorkflowRunMode>;
+/** Cursor state once a verdict is routed and no cleanup step is pending. */
+export declare const AWAITING_FINALIZE = "AWAITING_FINALIZE";
+export type WorkflowRunV2ErrorCode = WorkflowErrorCode | 'IDEMPOTENCY_CONFLICT' | 'CLEANUP_PENDING' | 'RUN_TERMINAL' | 'MISSING_TEMPLATE' | 'HOST_PROFILE_MISMATCH';
+export declare class WorkflowRunV2Error extends Error {
+    readonly code: WorkflowRunV2ErrorCode;
+    readonly details?: Readonly<Record<string, unknown>>;
+    /** The reply rules of the dispatched step, on a refusal of its report (TASK-968). */
+    hint?: string;
+    constructor(code: WorkflowRunV2ErrorCode, message: string, details?: Readonly<Record<string, unknown>>);
+}
+export declare const WorkflowStepReceipt: z.ZodObject<{
+    step_id: z.ZodString;
+    dispatch_digest: z.ZodString;
+    host_tool_name: z.ZodString;
+    arguments: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    status: z.ZodEnum<{
+        blocked: "blocked";
+        failed: "failed";
+        inconclusive: "inconclusive";
+        succeeded: "succeeded";
+    }>;
+    exit_code: z.ZodOptional<z.ZodNumber>;
+    error_code: z.ZodOptional<z.ZodEnum<{
+        ARTIFACT_INVALID: "ARTIFACT_INVALID";
+        ASSERTION_FAILED: "ASSERTION_FAILED";
+        AUTHORING_INVALID: "AUTHORING_INVALID";
+        BINDING_SCHEMA_DRIFT: "BINDING_SCHEMA_DRIFT";
+        BINDING_UNAVAILABLE: "BINDING_UNAVAILABLE";
+        CANCELLED: "CANCELLED";
+        EXECUTION_FAILED: "EXECUTION_FAILED";
+        HUMAN_DECLINED: "HUMAN_DECLINED";
+        INPUT_INVALID: "INPUT_INVALID";
+        INTERNAL_ERROR: "INTERNAL_ERROR";
+        MANIFEST_INTEGRITY: "MANIFEST_INTEGRITY";
+        PARAMETER_MUTATION: "PARAMETER_MUTATION";
+        PERSISTENCE_CONFLICT: "PERSISTENCE_CONFLICT";
+        POLICY_DENIED: "POLICY_DENIED";
+        PROTOCOL_ERROR: "PROTOCOL_ERROR";
+        SEMANTIC_INCONCLUSIVE: "SEMANTIC_INCONCLUSIVE";
+        TEMPLATE_ERROR: "TEMPLATE_ERROR";
+        TIMEOUT: "TIMEOUT";
+        TRANSPORT_ERROR: "TRANSPORT_ERROR";
+        UNCERTAIN_OUTCOME: "UNCERTAIN_OUTCOME";
+    }>>;
+    captures: z.ZodDefault<z.ZodObject<{
+        stdout: z.ZodOptional<z.ZodString>;
+        stderr: z.ZodOptional<z.ZodString>;
+        response: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>>;
+    artifacts: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        path: z.ZodString;
+        digest: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    idempotency_key: z.ZodOptional<z.ZodString>;
+    judgment: z.ZodOptional<z.ZodObject<{
+        verdict: z.ZodEnum<{
+            BLOCKED: "BLOCKED";
+            CANCELLED: "CANCELLED";
+            FAIL: "FAIL";
+            INCONCLUSIVE: "INCONCLUSIVE";
+            NOT_RECORDED: "NOT_RECORDED";
+            PASS: "PASS";
+        }>;
+        confidence: z.ZodNumber;
+        rationale: z.ZodString;
+    }, z.core.$strip>>;
+    started_at: z.ZodOptional<z.ZodString>;
+    finished_at: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type WorkflowStepReceipt = z.infer<typeof WorkflowStepReceipt>;
+/**
+ * A step discharged by a report of what was observed instead of a captured tool result. Used when
+ * the executor carried the step out themselves: a person in the walkthrough panel, or an agent
+ * stating what it saw and holds no tool receipt for. Deliberately a separate shape from
+ * `WorkflowStepReceipt`, so no reader can mistake a report for a tool run.
+ */
+export declare const WorkflowStepObservation: z.ZodObject<{
+    step_id: z.ZodString;
+    dispatch_digest: z.ZodString;
+    observation: z.ZodString;
+    status: z.ZodEnum<{
+        blocked: "blocked";
+        failed: "failed";
+        inconclusive: "inconclusive";
+        succeeded: "succeeded";
+    }>;
+    error_text: z.ZodOptional<z.ZodString>;
+    error_code: z.ZodOptional<z.ZodEnum<{
+        ARTIFACT_INVALID: "ARTIFACT_INVALID";
+        ASSERTION_FAILED: "ASSERTION_FAILED";
+        AUTHORING_INVALID: "AUTHORING_INVALID";
+        BINDING_SCHEMA_DRIFT: "BINDING_SCHEMA_DRIFT";
+        BINDING_UNAVAILABLE: "BINDING_UNAVAILABLE";
+        CANCELLED: "CANCELLED";
+        EXECUTION_FAILED: "EXECUTION_FAILED";
+        HUMAN_DECLINED: "HUMAN_DECLINED";
+        INPUT_INVALID: "INPUT_INVALID";
+        INTERNAL_ERROR: "INTERNAL_ERROR";
+        MANIFEST_INTEGRITY: "MANIFEST_INTEGRITY";
+        PARAMETER_MUTATION: "PARAMETER_MUTATION";
+        PERSISTENCE_CONFLICT: "PERSISTENCE_CONFLICT";
+        POLICY_DENIED: "POLICY_DENIED";
+        PROTOCOL_ERROR: "PROTOCOL_ERROR";
+        SEMANTIC_INCONCLUSIVE: "SEMANTIC_INCONCLUSIVE";
+        TEMPLATE_ERROR: "TEMPLATE_ERROR";
+        TIMEOUT: "TIMEOUT";
+        TRANSPORT_ERROR: "TRANSPORT_ERROR";
+        UNCERTAIN_OUTCOME: "UNCERTAIN_OUTCOME";
+    }>>;
+    artifacts: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        path: z.ZodString;
+        digest: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    idempotency_key: z.ZodOptional<z.ZodString>;
+    fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+}, z.core.$strip>;
+export type WorkflowStepObservation = z.infer<typeof WorkflowStepObservation>;
+export declare const WorkflowHumanResponse: z.ZodObject<{
+    step_id: z.ZodString;
+    dispatch_digest: z.ZodString;
+    option: z.ZodOptional<z.ZodString>;
+    freeform: z.ZodOptional<z.ZodString>;
+    observation: z.ZodDefault<z.ZodString>;
+    evidence: z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        type: z.ZodString;
+        path: z.ZodString;
+        digest: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>]>>>;
+    fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+}, z.core.$strip>;
+export type WorkflowHumanResponse = z.infer<typeof WorkflowHumanResponse>;
+/**
+ * A host's decision not to carry out the dispatched step — the fourth way a step is discharged,
+ * next to a receipt, an observation and a human response. Only an optional step may be skipped.
+ * It routes through `on.pass` and leaves the verdict alone, because an optional step is not part
+ * of the run's claim; the required reason lets the report say who skipped the step and why.
+ * @see BUG-144
+ */
+export declare const WorkflowStepSkip: z.ZodObject<{
+    step_id: z.ZodString;
+    dispatch_digest: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$strip>;
+export type WorkflowStepSkip = z.infer<typeof WorkflowStepSkip>;
+export declare const WorkflowRunPolicy: z.ZodObject<{
+    max_side_effect: z.ZodOptional<z.ZodEnum<{
+        credentialed: "credentialed";
+        irreversible: "irreversible";
+        "local-destructive": "local-destructive";
+        "local-reversible": "local-reversible";
+        "read-only": "read-only";
+        "remote-mutating": "remote-mutating";
+        "remote-reversible": "remote-reversible";
+    }>>;
+}, z.core.$strip>;
+export type WorkflowRunPolicy = z.infer<typeof WorkflowRunPolicy>;
+/** What a step leaves behind for templates and predicates of later steps. */
+export type WorkflowStepOutput = {
+    attempt: number;
+    /** `skipped` when the host skipped an optional step; the step then ran nothing (BUG-144). */
+    status: WorkflowStepReceipt['status'] | 'skipped';
+    exit_code?: number;
+    error_code?: string;
+    stdout?: string;
+    stderr?: string;
+    response?: unknown;
+    json?: unknown;
+    /** The values the script's `extract` read from stdout, by name (BUG-216). */
+    values?: Record<string, string>;
+    /** What the executor reported; set instead of the capture fields on an observed step. */
+    observation?: string;
+    /** Error text the executor read verbatim, kept apart from the observation. */
+    error_text?: string;
+    artifacts?: WorkflowStepReceipt['artifacts'];
+    option?: string;
+    freeform?: string;
+    verdict?: string;
+    slot?: 'pass' | 'fail' | 'error';
+    /** Values of the step's declared fields, by field id (STORY-450). */
+    fields?: Record<string, string | number | boolean>;
+};
+/** The more severe of two verdicts; a cleanup route can degrade a pending verdict, never improve it. */
+export declare function worseVerdict(current: WorkflowRouteVerdict | null | undefined, next: WorkflowRouteVerdict): WorkflowRouteVerdict;
+/** Side-effect classes ordered by blast radius, used by `policy.max_side_effect`. */
+export declare const SIDE_EFFECT_RANK: Readonly<Record<WorkflowSideEffect, number>>;
+/** Classes that need a positive `approval` human step among the step's dependencies. */
+export declare const APPROVAL_REQUIRED_SIDE_EFFECTS: ReadonlySet<WorkflowSideEffect>;
+//# sourceMappingURL=workflow-v2-types.d.ts.map

package/dist/runtime/workflow-v2-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-v2-types.d.ts","sourceRoot":"","sources":["../../src/runtime/workflow-v2-types.ts"],"names":[],"mappings":"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"}

package/dist/runtime/workflow-v2-types.js

@@ -0,0 +1,140 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Run protocol of compiled workflows (schema_version "2.0").
+ * Receipts, human responses, step outputs, verdict severity, and the side-effect order.
+ */
+import { z } from 'zod';
+import { WorkflowErrorCode, WorkflowSideEffect, WorkflowVerdict, } from '../schemas/workflow-v2-vocabulary.js';
+/** The parties are schema vocabulary, because a step names its intended party in `who`. */
+export { WorkflowParty } from '../schemas/workflow-v2-vocabulary.js';
+/** Who works a v2 run: the person alone, the person with the agent, or the agent alone. */
+export const WorkflowRunMode = z.enum(['operator', 'together', 'agent']);
+/** Cursor state once a verdict is routed and no cleanup step is pending. */
+export const AWAITING_FINALIZE = 'AWAITING_FINALIZE';
+export class WorkflowRunV2Error extends Error {
+    code;
+    details;
+    /** The reply rules of the dispatched step, on a refusal of its report (TASK-968). */
+    hint;
+    constructor(code, message, details) {
+        super(`${code}: ${message}`);
+        this.name = 'WorkflowRunV2Error';
+        this.code = code;
+        this.details = details;
+    }
+}
+/** Kept here, not in workflow-v2-fields.ts, so the submission shapes have no import cycle. */
+const FieldValues = z.record(z.string().min(1).max(60), z.union([z.string().max(20_000), z.number(), z.boolean()]));
+const Artifact = z.object({
+    type: z.string().min(1).max(50),
+    path: z.string().min(1).max(500),
+    digest: z.string().min(1).max(200).optional(),
+});
+export const WorkflowStepReceipt = z.object({
+    step_id: z.string().min(1).max(100),
+    dispatch_digest: z.string().min(1).max(200),
+    host_tool_name: z.string().min(1).max(200),
+    arguments: z.record(z.string(), z.unknown()).default({}),
+    status: z.enum(['succeeded', 'failed', 'blocked', 'inconclusive']),
+    exit_code: z.number().int().optional(),
+    error_code: WorkflowErrorCode.optional(),
+    captures: z
+        .object({
+        stdout: z.string().max(1_000_000).optional(),
+        stderr: z.string().max(1_000_000).optional(),
+        response: z.unknown().optional(),
+    })
+        .default({}),
+    artifacts: z.array(Artifact).max(100).default([]),
+    idempotency_key: z.string().min(1).max(500).optional(),
+    judgment: z
+        .object({
+        verdict: WorkflowVerdict,
+        confidence: z.number().min(0).max(1),
+        rationale: z.string().max(4000),
+    })
+        .optional(),
+    started_at: z.string().datetime().optional(),
+    finished_at: z.string().datetime().optional(),
+});
+/**
+ * A step discharged by a report of what was observed instead of a captured tool result. Used when
+ * the executor carried the step out themselves: a person in the walkthrough panel, or an agent
+ * stating what it saw and holds no tool receipt for. Deliberately a separate shape from
+ * `WorkflowStepReceipt`, so no reader can mistake a report for a tool run.
+ */
+export const WorkflowStepObservation = z.object({
+    step_id: z.string().min(1).max(100),
+    dispatch_digest: z.string().min(1).max(200),
+    /** What the executor saw. Required: an observation with nothing observed is not evidence. */
+    observation: z.string().min(1).max(100_000),
+    status: z.enum(['succeeded', 'failed', 'blocked', 'inconclusive']),
+    /** Verbatim error text the executor read, kept apart from the observation itself. */
+    error_text: z.string().max(100_000).optional(),
+    error_code: WorkflowErrorCode.optional(),
+    artifacts: z.array(Artifact).max(100).default([]),
+    idempotency_key: z.string().min(1).max(500).optional(),
+    /** Values of the step's declared fields (STORY-450). */
+    fields: FieldValues.optional(),
+});
+export const WorkflowHumanResponse = z.object({
+    step_id: z.string().min(1).max(100),
+    dispatch_digest: z.string().min(1).max(200),
+    option: z.string().min(1).max(200).optional(),
+    freeform: z.string().min(1).max(2000).optional(),
+    observation: z.string().max(2000).default(''),
+    evidence: z
+        .array(z.union([z.string().max(500), Artifact]))
+        .max(50)
+        .default([]),
+    /** Values of the step's declared fields (STORY-450). */
+    fields: FieldValues.optional(),
+});
+/**
+ * A host's decision not to carry out the dispatched step — the fourth way a step is discharged,
+ * next to a receipt, an observation and a human response. Only an optional step may be skipped.
+ * It routes through `on.pass` and leaves the verdict alone, because an optional step is not part
+ * of the run's claim; the required reason lets the report say who skipped the step and why.
+ * @see BUG-144
+ */
+export const WorkflowStepSkip = z.object({
+    step_id: z.string().min(1).max(100),
+    dispatch_digest: z.string().min(1).max(200),
+    reason: z.string().trim().min(1).max(500),
+});
+export const WorkflowRunPolicy = z.object({
+    max_side_effect: WorkflowSideEffect.optional(),
+});
+const VERDICT_SEVERITY = {
+    PASS: 0,
+    INCONCLUSIVE: 1,
+    BLOCKED: 2,
+    CANCELLED: 3,
+    FAIL: 4,
+};
+/** The more severe of two verdicts; a cleanup route can degrade a pending verdict, never improve it. */
+export function worseVerdict(current, next) {
+    if (!current)
+        return next;
+    return VERDICT_SEVERITY[next] > VERDICT_SEVERITY[current] ? next : current;
+}
+/** Side-effect classes ordered by blast radius, used by `policy.max_side_effect`. */
+export const SIDE_EFFECT_RANK = {
+    'read-only': 0,
+    'local-reversible': 1,
+    'remote-reversible': 2,
+    'local-destructive': 3,
+    'remote-mutating': 4,
+    credentialed: 5,
+    irreversible: 6,
+};
+/** Classes that need a positive `approval` human step among the step's dependencies. */
+export const APPROVAL_REQUIRED_SIDE_EFFECTS = new Set([
+    'local-destructive',
+    'remote-mutating',
+    'credentialed',
+    'irreversible',
+]);
+//# sourceMappingURL=workflow-v2-types.js.map

package/dist/runtime/workflow-v2-types.js.map

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

package/dist/runtime/workflow-v2-variables.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Run variables of compiled workflows.
+ * Validates supplied values against the declared variables and stores secrets as references.
+ */
+import type { WorkflowDefinitionV2 } from '../schemas/workflow-definition-v2.js';
+/** Validate supplied run variables; unknown names and missing required values are rejected. */
+export declare function validateWorkflowVariables(definition: WorkflowDefinitionV2, supplied?: Readonly<Record<string, unknown>>): Record<string, unknown>;
+//# sourceMappingURL=workflow-v2-variables.d.ts.map

package/dist/runtime/workflow-v2-variables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-v2-variables.d.ts","sourceRoot":"","sources":["../../src/runtime/workflow-v2-variables.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AAgDjF,+FAA+F;AAC/F,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,oBAAoB,EAChC,QAAQ,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAM,GAC/C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAwBzB"}

package/dist/runtime/workflow-v2-variables.js

@@ -0,0 +1,63 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Run variables of compiled workflows.
+ * Validates supplied values against the declared variables and stores secrets as references.
+ */
+import { isSecretReference } from './redaction.js';
+import { WorkflowRunV2Error } from './workflow-v2-types.js';
+/** `env:NAME`, `vault:path/to/secret`, `keyring:service/account` — a pointer, never a value. */
+const SECRET_REFERENCE = /^[a-z][a-z0-9+.-]*:[^\s]{1,400}$/i;
+function typeMismatch(name, expected, value) {
+    return new WorkflowRunV2Error('INPUT_INVALID', `Variable ${name} must be ${expected}, received ${JSON.stringify(value)?.slice(0, 80) ?? typeof value}`);
+}
+function normalizeVariable(declared, value) {
+    switch (declared.type) {
+        case 'string':
+        case 'path':
+            if (typeof value !== 'string' || value.includes('\0')) {
+                throw typeMismatch(declared.name, `a ${declared.type} string`, value);
+            }
+            return value;
+        case 'number':
+            if (typeof value !== 'number' || !Number.isFinite(value)) {
+                throw typeMismatch(declared.name, 'a finite number', value);
+            }
+            return value;
+        case 'boolean':
+            if (typeof value !== 'boolean')
+                throw typeMismatch(declared.name, 'a boolean', value);
+            return value;
+        case 'json':
+            return value;
+        case 'secret-reference': {
+            const reference = isSecretReference(value) ? value.$secret : value;
+            if (typeof reference !== 'string' || !SECRET_REFERENCE.test(reference)) {
+                throw new WorkflowRunV2Error('INPUT_INVALID', `Variable ${declared.name} is a secret-reference: pass a reference such as "env:NAME" or "vault:path" (or { "$secret": "env:NAME" }), never the secret value; the host resolves it`);
+            }
+            return { $secret: reference };
+        }
+    }
+}
+/** Validate supplied run variables; unknown names and missing required values are rejected. */
+export function validateWorkflowVariables(definition, supplied = {}) {
+    const declared = new Map(definition.variables.map((variable) => [variable.name, variable]));
+    const unknown = Object.keys(supplied).filter((name) => !declared.has(name));
+    if (unknown.length > 0) {
+        throw new WorkflowRunV2Error('INPUT_INVALID', `Undeclared variables: ${unknown.join(', ')}; declared: ${[...declared.keys()].join(', ') || 'none'}`);
+    }
+    const variables = {};
+    for (const variable of definition.variables) {
+        const value = supplied[variable.name];
+        if (value === undefined || value === null) {
+            if (variable.required) {
+                throw new WorkflowRunV2Error('INPUT_INVALID', `Missing required variable ${variable.name} (${variable.type})`);
+            }
+            continue;
+        }
+        variables[variable.name] = normalizeVariable(variable, value);
+    }
+    return variables;
+}
+//# sourceMappingURL=workflow-v2-variables.js.map

package/dist/runtime/workflow-v2-variables.js.map

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

package/dist/runtime/workflow-v2-wait.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * The agent's wait for the operator as one tool call (BUG-210): it returns as soon as an event
+ * addressed to the agent follows the version the agent last saw and its writer is done, or once
+ * the time is up. It reads the event log only, never run.json, because on Windows an open reader
+ * can make the writer's rename fail (DEC-022). A host that runs a long call in the background,
+ * as Claude Code does, wakes the agent when the call returns.
+ * @see STORY-463
+ */
+import type { ProcessEvent } from './index.js';
+import type { RunStore } from './run-store.js';
+/** The longest wait one call may ask for: below the 30-minute idle limit of a stdio tool call. */
+export declare const AGENT_WAIT_MAX_SECONDS = 1500;
+/** How often the wait looks at the event log. */
+export declare const AGENT_WAIT_INTERVAL_MS = 1000;
+export type WorkflowV2AgentWait = Readonly<{
+    /** True when an event addressed to the agent ended the wait, false when the time ran out. */
+    woke: boolean;
+    /** The events addressed to the agent from `afterVersion` on, in sequence. */
+    events: readonly ProcessEvent[];
+}>;
+/**
+ * The events the agent has to hear about from a run at `afterVersion` on, before `beforeVersion`
+ * when given: addressed to the agent and written by someone else.
+ */
+export declare function agentEventsSince(events: readonly ProcessEvent[], afterVersion: number, beforeVersion?: number): ProcessEvent[];
+/**
+ * Wait until an event addressed to the agent has a sequence of `afterVersion` or later — the
+ * first event after a run at that version — and no writer is busy, or until `seconds` pass.
+ */
+export declare function waitForAgentEvents(store: RunStore, runId: string, afterVersion: number, seconds: number, intervalMs?: number): Promise<WorkflowV2AgentWait>;
+//# sourceMappingURL=workflow-v2-wait.d.ts.map

package/dist/runtime/workflow-v2-wait.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-v2-wait.d.ts","sourceRoot":"","sources":["../../src/runtime/workflow-v2-wait.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C,kGAAkG;AAClG,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAE3C,iDAAiD;AACjD,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAE3C,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IACzC,6FAA6F;IAC7F,IAAI,EAAE,OAAO,CAAC;IACd,6EAA6E;IAC7E,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;CACjC,CAAC,CAAC;AAiBH;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,SAAS,YAAY,EAAE,EAC/B,YAAY,EAAE,MAAM,EACpB,aAAa,SAA2B,GACvC,YAAY,EAAE,CAQhB;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,QAAQ,EACf,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,EACf,UAAU,SAAyB,GAClC,OAAO,CAAC,mBAAmB,CAAC,CAS9B"}

package/dist/runtime/workflow-v2-wait.js

@@ -0,0 +1,53 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * The agent's wait for the operator as one tool call (BUG-210): it returns as soon as an event
+ * addressed to the agent follows the version the agent last saw and its writer is done, or once
+ * the time is up. It reads the event log only, never run.json, because on Windows an open reader
+ * can make the writer's rename fail (DEC-022). A host that runs a long call in the background,
+ * as Claude Code does, wakes the agent when the call returns.
+ * @see STORY-463
+ */
+import { access } from 'node:fs/promises';
+import { join } from 'node:path';
+/** The longest wait one call may ask for: below the 30-minute idle limit of a stdio tool call. */
+export const AGENT_WAIT_MAX_SECONDS = 1500;
+/** How often the wait looks at the event log. */
+export const AGENT_WAIT_INTERVAL_MS = 1000;
+const exists = (path) => access(path).then(() => true, () => false);
+/** A transition is being written while the run lock or the pending transition exists. */
+async function writerBusy(store, runId) {
+    const busy = await Promise.all([
+        exists(join(store.runPath(runId), 'run.lock')),
+        exists(store.transactionPath(runId)),
+    ]);
+    return busy.some(Boolean);
+}
+/**
+ * The events the agent has to hear about from a run at `afterVersion` on, before `beforeVersion`
+ * when given: addressed to the agent and written by someone else.
+ */
+export function agentEventsSince(events, afterVersion, beforeVersion = Number.POSITIVE_INFINITY) {
+    return events.filter((event) => event.sequence >= afterVersion &&
+        event.sequence < beforeVersion &&
+        event.notify === 'agent' &&
+        event.actor !== 'agent');
+}
+/**
+ * Wait until an event addressed to the agent has a sequence of `afterVersion` or later — the
+ * first event after a run at that version — and no writer is busy, or until `seconds` pass.
+ */
+export async function waitForAgentEvents(store, runId, afterVersion, seconds, intervalMs = AGENT_WAIT_INTERVAL_MS) {
+    const deadline = Date.now() + Math.min(seconds, AGENT_WAIT_MAX_SECONDS) * 1000;
+    for (;;) {
+        const events = agentEventsSince(await store.readEvents(runId), afterVersion);
+        if (events.length > 0 && !(await writerBusy(store, runId)))
+            return { woke: true, events };
+        const left = deadline - Date.now();
+        if (left <= 0)
+            return { woke: false, events: [] };
+        await new Promise((resolve) => setTimeout(resolve, Math.min(intervalMs, left)));
+    }
+}
+//# sourceMappingURL=workflow-v2-wait.js.map

package/dist/runtime/workflow-v2-wait.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-v2-wait.js","sourceRoot":"","sources":["../../src/runtime/workflow-v2-wait.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAIjC,kGAAkG;AAClG,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,CAAC;AAE3C,iDAAiD;AACjD,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,CAAC;AAS3C,MAAM,MAAM,GAAG,CAAC,IAAY,EAAE,EAAE,CAC9B,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CACf,GAAG,EAAE,CAAC,IAAI,EACV,GAAG,EAAE,CAAC,KAAK,CACZ,CAAC;AAEJ,yFAAyF;AACzF,KAAK,UAAU,UAAU,CAAC,KAAe,EAAE,KAAa;IACtD,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAC7B,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,CAAC;QAC9C,MAAM,CAAC,KAAK,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;KACrC,CAAC,CAAC;IACH,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AAC5B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAA+B,EAC/B,YAAoB,EACpB,aAAa,GAAG,MAAM,CAAC,iBAAiB;IAExC,OAAO,MAAM,CAAC,MAAM,CAClB,CAAC,KAAK,EAAE,EAAE,CACR,KAAK,CAAC,QAAQ,IAAI,YAAY;QAC9B,KAAK,CAAC,QAAQ,GAAG,aAAa;QAC9B,KAAK,CAAC,MAAM,KAAK,OAAO;QACxB,KAAK,CAAC,KAAK,KAAK,OAAO,CAC1B,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,KAAe,EACf,KAAa,EACb,YAAoB,EACpB,OAAe,EACf,UAAU,GAAG,sBAAsB;IAEnC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,sBAAsB,CAAC,GAAG,IAAI,CAAC;IAC/E,SAAS,CAAC;QACR,MAAM,MAAM,GAAG,gBAAgB,CAAC,MAAM,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC,CAAC;QAC7E,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC,MAAM,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;YAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QAC1F,MAAM,IAAI,GAAG,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACnC,IAAI,IAAI,IAAI,CAAC;YAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;QAClD,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IAClF,CAAC;AACH,CAAC"}

package/dist/runtime/workspace-fingerprint.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Workspace fingerprints of workflow runs: the same workspace is one fingerprint whether VS Code
+ * wrote it (`c:\proj`, from `fsPath`) or an agent did (`C:\proj\`, `C:/proj`). Runs store the
+ * normalised form, and every comparison normalises both sides, so runs stored before this rule
+ * compare correctly too.
+ * @see BUG-159
+ */
+/** Unify separators, drop a trailing separator, and upper-case a drive letter. */
+export declare function normalizeWorkspaceFingerprint(value: string): string;
+/** Whether two fingerprints name the same workspace. */
+export declare function sameWorkspaceFingerprint(left: string, right: string): boolean;
+//# sourceMappingURL=workspace-fingerprint.d.ts.map

package/dist/runtime/workspace-fingerprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-fingerprint.d.ts","sourceRoot":"","sources":["../../src/runtime/workspace-fingerprint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,kFAAkF;AAClF,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CASnE;AAOD,wDAAwD;AACxD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAK7E"}

package/dist/runtime/workspace-fingerprint.js

@@ -0,0 +1,36 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Workspace fingerprints of workflow runs: the same workspace is one fingerprint whether VS Code
+ * wrote it (`c:\proj`, from `fsPath`) or an agent did (`C:\proj\`, `C:/proj`). Runs store the
+ * normalised form, and every comparison normalises both sides, so runs stored before this rule
+ * compare correctly too.
+ * @see BUG-159
+ */
+const DRIVE = /^[A-Za-z]:/;
+/** Unify separators, drop a trailing separator, and upper-case a drive letter. */
+export function normalizeWorkspaceFingerprint(value) {
+    let text = value.trim().replace(/\\/g, '/');
+    if (DRIVE.test(text))
+        text = `${text.charAt(0).toUpperCase()}${text.slice(1)}`;
+    // Keep a bare root (`/`, `C:/`) whole; it names a workspace too.
+    while (text.endsWith('/') && text.length > 1 && !/^[A-Z]:\/$/.test(text)) {
+        text = text.slice(0, -1);
+    }
+    // A blank fingerprint stays as given: an empty one would no longer satisfy the run schema.
+    return text || value;
+}
+/** A Windows path, by drive letter or UNC share: its file system ignores case. */
+function isWindowsPath(normalized) {
+    return DRIVE.test(normalized) || normalized.startsWith('//');
+}
+/** Whether two fingerprints name the same workspace. */
+export function sameWorkspaceFingerprint(left, right) {
+    const a = normalizeWorkspaceFingerprint(left);
+    const b = normalizeWorkspaceFingerprint(right);
+    if (isWindowsPath(a) && isWindowsPath(b))
+        return a.toLowerCase() === b.toLowerCase();
+    return a === b;
+}
+//# sourceMappingURL=workspace-fingerprint.js.map

package/dist/runtime/workspace-fingerprint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-fingerprint.js","sourceRoot":"","sources":["../../src/runtime/workspace-fingerprint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,KAAK,GAAG,YAAY,CAAC;AAE3B,kFAAkF;AAClF,MAAM,UAAU,6BAA6B,CAAC,KAAa;IACzD,IAAI,IAAI,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAC5C,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,IAAI,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IAC/E,iEAAiE;IACjE,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACzE,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC3B,CAAC;IACD,2FAA2F;IAC3F,OAAO,IAAI,IAAI,KAAK,CAAC;AACvB,CAAC;AAED,kFAAkF;AAClF,SAAS,aAAa,CAAC,UAAkB;IACvC,OAAO,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,UAAU,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AAC/D,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,wBAAwB,CAAC,IAAY,EAAE,KAAa;IAClE,MAAM,CAAC,GAAG,6BAA6B,CAAC,IAAI,CAAC,CAAC;IAC9C,MAAM,CAAC,GAAG,6BAA6B,CAAC,KAAK,CAAC,CAAC;IAC/C,IAAI,aAAa,CAAC,CAAC,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;IACrF,OAAO,CAAC,KAAK,CAAC,CAAC;AACjB,CAAC"}