@archmax-ai/harness 0.8.0 → 1.0.0

package/dist/workflow/checkpointer.d.ts

@@ -49,4 +49,11 @@ export declare class BackendCheckpointSaver extends MemorySaver {
      * removal is the session store's job. Named `deleteThread` because LangGraph owns the word.
      */
     deleteThread(sessionId: string): Promise<void>;
+    /**
+     * Drop a session and every child session under it from memory, leaving their
+     * record files in the store: unlike {@link deleteThread} nothing is marked, so
+     * the next access replays them as after a restart. Synchronous, because
+     * `dispose` is.
+     */
+    evict(sessionId: string): void;
 }

package/dist/workflow/checkpointer.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { MemorySaver, WRITES_IDX_MAP, } from "@langchain/langgraph-checkpoint";
 import { isReservedRootName } from "../core/zones.js";
+import { isChildSessionOf } from "../sessions/scope.js";
 import { sessionPaths } from "./paths.js";
 const enc = (bytes) => Buffer.from(bytes).toString("base64");
 const dec = (b64) => new Uint8Array(Buffer.from(b64, "base64"));
@@ -124,6 +125,14 @@ export class BackendCheckpointSaver extends MemorySaver {
         const sessionId = config.configurable?.thread_id;
         if (sessionId !== undefined)
             await this.ensureLoaded(sessionId);
+        // `MemorySaver.put` creates the namespace before it stores the checkpoint, across an
+        // await; read in that window, the parent takes the newest of no checkpoints and throws.
+        if (sessionId !== undefined && config.configurable?.checkpoint_id === undefined) {
+            const ns = config.configurable?.checkpoint_ns ?? "";
+            const held = this.storage[sessionId]?.[ns];
+            if (held !== undefined && Object.keys(held).length === 0)
+                return undefined;
+        }
         return super.getTuple(config);
     }
     async *list(config, options) {
@@ -196,5 +205,24 @@ export class BackendCheckpointSaver extends MemorySaver {
         // Marked as replayed (with nothing to replay) so a later access does not resurrect the files.
         this.loading.set(sessionId, Promise.resolve());
     }
+    /**
+     * Drop a session and every child session under it from memory, leaving their
+     * record files in the store: unlike {@link deleteThread} nothing is marked, so
+     * the next access replays them as after a restart. Synchronous, because
+     * `dispose` is.
+     */
+    evict(sessionId) {
+        const covered = (id) => id === sessionId || isChildSessionOf(id, sessionId);
+        for (const id of Object.keys(this.storage))
+            if (covered(id))
+                delete this.storage[id];
+        for (const key of Object.keys(this.writes)) {
+            if (covered(String(JSON.parse(key)[0])))
+                delete this.writes[key];
+        }
+        for (const id of [...this.loading.keys()])
+            if (covered(id))
+                this.loading.delete(id);
+    }
 }
 //# sourceMappingURL=checkpointer.js.map

package/dist/workflow/checkpointer.js.map

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

package/dist/workflow/code-state.d.ts

@@ -0,0 +1,46 @@
+/**
+ * A code state's run: its `script`, read from the authoring backend, evaluated
+ * in the sandbox with its state's input and its state's tools — nothing else.
+ *
+ * The run decides nothing here: the script moves the session through
+ * `tools.archmax_advance` or ends it through `tools.archmax_raise`, which the
+ * step recorder holds, and the orchestrator (`automated.ts`) reads the outcome
+ * from that record and from whether the script finished cleanly.
+ */
+import type { StructuredTool } from "@langchain/core/tools";
+import type { WorkflowEventEmitter } from "../core/events.js";
+import type { ScriptExecutor } from "../sandbox/executor.js";
+/** Resolves a code state's declared `script` to its authoring-backend path, or refuses it with a reason. */
+export type CodeScriptResolver = (declared: string) => {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface CodeStateRun {
+    emit: WorkflowEventEmitter;
+    /** The executor reading sources from the authoring backend. */
+    executor: ScriptExecutor;
+    resolveScript: CodeScriptResolver;
+    sessionId: string;
+    state: string;
+    /** The state's declared `script`. */
+    script: string;
+    /** The script's input: `{ state, trigger?, variables }`. */
+    input: Record<string, unknown>;
+    /** The code state's tools, governed. */
+    tools: StructuredTool[];
+    /** The names those tools are listed and reached by. */
+    surface: readonly string[];
+    signal?: AbortSignal;
+}
+/**
+ * Run a code state's script. Settles with the error that stopped it, if one did
+ * — a script that cannot be placed or read, a foreign import, a throw, a
+ * timeout, a cancelled turn — and with nothing when it ran to its end. Each
+ * console line is reported as it was logged.
+ */
+export declare function runCodeState(run: CodeStateRun): Promise<{
+    error?: string;
+}>;

package/dist/workflow/code-state.js

@@ -0,0 +1,26 @@
+/**
+ * Run a code state's script. Settles with the error that stopped it, if one did
+ * — a script that cannot be placed or read, a foreign import, a throw, a
+ * timeout, a cancelled turn — and with nothing when it ran to its end. Each
+ * console line is reported as it was logged.
+ */
+export async function runCodeState(run) {
+    const resolved = run.resolveScript(run.script);
+    if (!resolved.ok)
+        return { error: resolved.reason };
+    const outcome = await run.executor.runCodeState(resolved.path, {
+        sessionId: run.sessionId,
+        args: run.input,
+        tools: run.tools,
+        surface: run.surface,
+        ...(run.signal ? { signal: run.signal } : {}),
+    });
+    for (const line of outcome.logs) {
+        if (line.trim())
+            run.emit({ type: "code-output", state: run.state, line: line.trimEnd() });
+    }
+    if (outcome.ok)
+        return {};
+    return { error: outcome.error?.message ?? "the script failed" };
+}
+//# sourceMappingURL=code-state.js.map

package/dist/workflow/code-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-state.js","sourceRoot":"","sources":["../../src/workflow/code-state.ts"],"names":[],"mappings":"AAkCA;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,GAAiB;IAClD,MAAM,QAAQ,GAAG,GAAG,CAAC,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC/C,IAAI,CAAC,QAAQ,CAAC,EAAE;QAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC;IACpD,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,QAAQ,CAAC,YAAY,CAAC,QAAQ,CAAC,IAAI,EAAE;QAC7D,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,IAAI,EAAE,GAAG,CAAC,KAAK;QACf,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC9C,CAAC,CAAC;IACH,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QAChC,IAAI,IAAI,CAAC,IAAI,EAAE;YAAE,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAC7F,CAAC;IACD,IAAI,OAAO,CAAC,EAAE;QAAE,OAAO,EAAE,CAAC;IAC1B,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,OAAO,IAAI,mBAAmB,EAAE,CAAC;AAClE,CAAC"}

package/dist/workflow/control-tools.d.ts

@@ -1,23 +1,25 @@
 /**
  * The control tools: `archmax_advance`, `archmax_wait`, `archmax_reset`,
- * `archmax_raise`, `archmax_get_variables`, `archmax_set_variables`.
+ * `archmax_raise`, `archmax_get_variables`, `archmax_set_variables` — and
+ * `archmax_get_history`, which only a grader state is offered.
  *
  * Each is a declaration whose body never runs in a wired assembly: governance
- * intercepts the call in `wrapToolCall`, where checkpointed state is in hand, and
- * services it with the handler here. A handler returns the tool message the
- * model reads and, when the call changed the run, the `Command` committing it.
+ * intercepts the session's agent's call in `wrapToolCall`, where checkpointed
+ * state is in hand, and services it with the handler here. A handler returns the
+ * tool message the model reads and, when the call changed the run, the `Command`
+ * committing it. An automated state's controls (`automated-controls.ts`) reuse
+ * the same schemas, handlers and {@link transitionUpdate}.
  */
 import { ToolMessage } from "@langchain/core/messages";
 import type { StructuredTool } from "@langchain/core/tools";
 import { Command } from "@langchain/langgraph";
 import { z } from "zod";
 import { type MountPrefixes } from "../core/zones.js";
-import type { LifecycleContext, LifecycleRunner } from "../lifecycle/runner.js";
 import type { WorkflowMachine } from "../machine/machine.js";
 import { ADVANCE_TOOL, GET_VARIABLES_TOOL, RAISE_TOOL, RESET_TOOL, SET_VARIABLES_TOOL, WAIT_TOOL } from "../machine/tool-names.js";
 import { type UnresolvedGlob, type VariableStore } from "../machine/variables.js";
 import { type FileValueCheck } from "./signature-checks.js";
-import { type PendingDecision, type PendingInput, type RaiseRecord, type WorkflowStateFields } from "./state.js";
+import { type MoveKind, type PendingDecision, type PendingInput, type RaiseRecord, type WorkflowStateFields, type WorkflowUpdate } from "./state.js";
 export { ADVANCE_TOOL, GET_VARIABLES_TOOL, RAISE_TOOL, RESET_TOOL, SET_VARIABLES_TOOL, WAIT_TOOL };
 /** The one refusal shape: an error-status tool message, so the model self-corrects and a view classifies it. */
 export declare function refusal(name: string, toolCallId: string, text: string): ToolMessage;
@@ -71,36 +73,66 @@ export declare const setVariablesSchema: z.ZodObject<{
 export declare function createControlTools(opts?: {
     child?: boolean;
 }): StructuredTool[];
+/** One move along a declared edge, as a trail step and a park will record it. */
+export interface Move {
+    to: string;
+    /** Who moved the session: its agent, a grader state or a code state. */
+    kind: MoveKind;
+    reason: string;
+    /** Attached evidence paths, already validated; only into a human state. */
+    evidence?: readonly string[];
+}
+/**
+ * The update a move commits — the target position, the trail step, a cleared
+ * rejection marker and a fresh turn budget — plus, into a human state, the park
+ * record opened in its closing phase. The one derivation every mover shares: the
+ * session's agent through {@link handleAdvance}, and an automated state's run.
+ * Messages are the caller's (a tool reply, a runtime note).
+ */
+export declare function transitionUpdate(machine: WorkflowMachine, state: unknown, move: Move): {
+    update: WorkflowUpdate;
+    park?: PendingDecision;
+};
+/**
+ * Why `from` may not be left for `to` right now, or `undefined` when it may: the
+ * kernel's transition verdict — the state's `requires` against `variables`, then
+ * the declared edge. Every refusal is recoverable: the mover sets what is owed,
+ * or picks a valid target.
+ */
+export declare function transitionRefusal(machine: WorkflowMachine, from: string, to: string, variables: VariableStore): string | undefined;
+/**
+ * Evidence an advance attaches, validated for the target: accepted only into a
+ * human state, and only paths the session itself could read.
+ */
+export declare function advanceEvidence(machine: WorkflowMachine, to: string, attached: readonly string[], mounts?: MountPrefixes): EvidenceValidation;
 export interface AdvanceRequest {
     /** Tool call id, echoed on the resulting ToolMessage. */
     toolCallId: string;
-    /** The id this call is reported under on the event stream (the provider's, else the generated fallback). */
-    callId?: string;
     args: Record<string, unknown>;
     /** Checkpointed agent state at the time of the call. */
     state: unknown;
-    /** Lifecycle context; its `iterations` are seeded from state and committed back. */
-    ctx: LifecycleContext;
 }
 export interface AdvanceOutcome {
     message: Command | ToolMessage;
     moved?: {
         from: string;
         to: string;
+        reason: string;
         /** The decision record committed when `to` is a human state. */
         park?: PendingDecision;
     };
 }
 /**
- * Attempt a transition and commit the outcome: `workflowState` and the `agent`
- * trail step on success, `iterations` always, and — into a human state —
- * the pending-decision record with the park opened in its closing phase.
+ * Service the session's agent's `archmax_advance`: validate the arguments, the
+ * evidence and the transition, then commit {@link transitionUpdate} with the
+ * reply the agent reads. A refusal leaves the session exactly where it was — no
+ * trail step — and replies without erroring the message, so the agent corrects
+ * the call rather than reading a failed run.
  */
 export declare function handleAdvance(opts: {
     machine: WorkflowMachine;
-    lifecycle: LifecycleRunner;
     mountPrefixes?: MountPrefixes;
-}, request: AdvanceRequest): Promise<AdvanceOutcome>;
+}, request: AdvanceRequest): AdvanceOutcome;
 /** The accepted `until` forms, quoted verbatim in every rejection. */
 export declare const WAIT_UNTIL_FORMS: string;
 export type WaitUntilResult = {
@@ -150,9 +182,9 @@ export interface ResetOutcome {
     };
 }
 /**
- * Service a reset: move back to the entry state and clear what gates progress
- * (correction budgets, `beforeDone`). Evidence — messages, files, variables, the
- * trail — is left alone: a reset moves the machine, not the history.
+ * Service a reset: move back to the entry state. Evidence — messages, files,
+ * variables, the trail — is left alone: a reset moves the machine, not the
+ * history.
  */
 export declare function handleReset(machine: WorkflowMachine, request: ResetRequest): ResetOutcome;
 export interface RaiseRequest {
@@ -170,9 +202,9 @@ export interface RaiseOutcome {
  * Service a raise: end the session as a failure in the state it was called in.
  * Commits the record and `status: failed`, and drops a pending rejection — the
  * agent's own account of the failure is what the session ends with. The turn
- * ends at the next model hook; nothing routes and no hook runs. Refused, with the
- * session left in place, for invalid arguments or a message making other calls:
- * those run concurrently, so a raise beside them could not mean one thing.
+ * ends at the next model hook; nothing routes and nothing further runs. Refused,
+ * with the session left in place, for invalid arguments or a message making other
+ * calls: those run concurrently, so a raise beside them could not mean one thing.
  */
 export declare function handleRaise(machine: WorkflowMachine, request: RaiseRequest): RaiseOutcome;
 export interface VariableToolRequest {
@@ -209,8 +241,7 @@ fileRefusal?: string): SetVariablesOutcome;
 export declare function fileReturnsRefusal(machine: WorkflowMachine, state: unknown, args: Record<string, unknown>, check: FileValueCheck): Promise<string | undefined>;
 /** Wrap an `archmax_set_variables` outcome as the update that commits its delta. */
 export declare function setVariablesCommand(outcome: SetVariablesOutcome): Command | ToolMessage;
-/** The variables a state still owes before it may be left — its `requires` minus what is set. */
-export declare function unmetRequirements(required: string[], store: VariableStore): string[];
+export { unmetRequirements } from "../kernel/kernel.js";
 /**
  * The wording for a `${{…}}` reference in the agent's own tool arguments that
  * could not be resolved: a correctable refusal carrying the two fixes it might

package/dist/workflow/control-tools.js

@@ -1,11 +1,14 @@
 /**
  * The control tools: `archmax_advance`, `archmax_wait`, `archmax_reset`,
- * `archmax_raise`, `archmax_get_variables`, `archmax_set_variables`.
+ * `archmax_raise`, `archmax_get_variables`, `archmax_set_variables` — and
+ * `archmax_get_history`, which only a grader state is offered.
  *
  * Each is a declaration whose body never runs in a wired assembly: governance
- * intercepts the call in `wrapToolCall`, where checkpointed state is in hand, and
- * services it with the handler here. A handler returns the tool message the
- * model reads and, when the call changed the run, the `Command` committing it.
+ * intercepts the session's agent's call in `wrapToolCall`, where checkpointed
+ * state is in hand, and services it with the handler here. A handler returns the
+ * tool message the model reads and, when the call changed the run, the `Command`
+ * committing it. An automated state's controls (`automated-controls.ts`) reuse
+ * the same schemas, handlers and {@link transitionUpdate}.
  */
 import { ToolMessage } from "@langchain/core/messages";
 import { Command } from "@langchain/langgraph";
@@ -14,6 +17,7 @@ import { z } from "zod";
 import { spokeSinceLastHumanMessage } from "../core/messages.js";
 import { canonicalizeRelPath } from "../core/workspace.js";
 import { classifyWorkspacePath, NO_MOUNTS, } from "../core/zones.js";
+import { decide } from "../kernel/kernel.js";
 import { signatureValueIssues } from "../machine/signature.js";
 import { ADVANCE_TOOL, GET_VARIABLES_TOOL, RAISE_TOOL, RESET_TOOL, SET_VARIABLES_TOOL, WAIT_TOOL, } from "../machine/tool-names.js";
 import { normalizeTitle, resolvePath, TITLE_VARIABLE, titleWriteError, VARIABLE_NAME_PATTERN, } from "../machine/variables.js";
@@ -157,8 +161,7 @@ export function createControlTools(opts = {}) {
     return [
         declaration(ADVANCE_TOOL, "Advance the workflow to the next state. Pick `to` from the current state's " +
             "transitions in the graph section above (a slug, never a title). The runtime " +
-            "validates the edge, runs this state's `after` hook, then unlocks the next " +
-            "state's tools.", advanceSchema),
+            "validates the edge, then unlocks the next state's tools.", advanceSchema),
         declaration(RESET_TOOL, "Start the workflow over from the state the conversation began in, keeping the " +
             "conversation and any work already written. Use it when this state cannot serve " +
             "what was asked: a wrong branch, a path no transition from here reaches, or a " +
@@ -190,77 +193,102 @@ export function createControlTools(opts = {}) {
     ];
 }
 /**
- * Attempt a transition and commit the outcome: `workflowState` and the `agent`
- * trail step on success, `iterations` always, and — into a human state —
- * the pending-decision record with the park opened in its closing phase.
+ * The update a move commits — the target position, the trail step, a cleared
+ * rejection marker and a fresh turn budget — plus, into a human state, the park
+ * record opened in its closing phase. The one derivation every mover shares: the
+ * session's agent through {@link handleAdvance}, and an automated state's run.
+ * Messages are the caller's (a tool reply, a runtime note).
  */
-export async function handleAdvance(opts, request) {
-    const refuse = (text) => ({ message: refusal(ADVANCE_TOOL, request.toolCallId, text) });
-    const parsed = advanceSchema.safeParse(request.args);
-    if (!parsed.success) {
-        return refuse(`${ADVANCE_TOOL} rejected: invalid arguments — ${schemaIssues(parsed.error)}`);
-    }
-    // Evidence is settled before the transition is attempted, so a refused
-    // attachment leaves the run exactly where it was: no hook run, no trail step.
-    const attached = parsed.data.evidence ?? [];
-    let evidence = [];
-    if (attached.length > 0) {
-        if (!opts.machine.isHumanState(parsed.data.to)) {
-            return refuse(`${ADVANCE_TOOL} rejected: evidence can only be attached when advancing into a human ` +
-                `decision state, and '${parsed.data.to}' is not one — nothing would present it. ` +
-                `Call again without 'evidence'.`);
-        }
-        const validated = validateAdvanceEvidence(attached, opts.mountPrefixes);
-        if (!validated.ok)
-            return refuse(`${ADVANCE_TOOL} rejected: ${validated.reason}`);
-        evidence = validated.paths;
-    }
-    const from = currentWorkflowState(request.state, opts.machine.entry);
-    const result = await opts.lifecycle.attemptTransition(from, parsed.data.to, request.ctx, parsed.data.reason, request.callId ? { callId: request.callId } : undefined);
-    if (!result.ok) {
-        // A terminal rejection is committed as `rejected` so the run routes through
-        // `on_error`; a recoverable one keeps the agent in place, replying without
-        // erroring the message so it retries rather than reading a failed run.
-        return {
-            message: commit({
-                iterations: { ...result.corrections },
-                ...(result.terminal ? { rejected: result.reason } : {}),
-                messages: [toolReply(ADVANCE_TOOL, request.toolCallId, `${ADVANCE_TOOL} rejected: ${result.reason}`)],
-            }),
-        };
-    }
-    const fields = readWorkflowState(request.state);
-    const step = { to: result.to, kind: "agent", reason: parsed.data.reason, ts: Date.now() };
-    const moved = {
-        workflowState: result.to,
-        iterations: { ...result.corrections },
-        // The gate ran the target's `before` hook: recorded as done for this visit,
-        // so the target's first model call does not run it a second time.
-        beforeDone: { ...(fields.beforeDone ?? {}), [result.to]: true },
+export function transitionUpdate(machine, state, move) {
+    const fields = readWorkflowState(state);
+    const step = { to: move.to, kind: move.kind, reason: move.reason, ts: Date.now() };
+    const update = {
+        workflowState: move.to,
         // A successful transition clears an earlier rejection marker and starts the target's turn budget afresh.
         ...NO_PENDING_FAILURE,
         stateTurns: null,
         auditTrail: [step],
-        messages: [
-            toolReply(ADVANCE_TOOL, request.toolCallId, `Advanced to state '${result.to}'. You may now use the tools allowed in this state.`),
-        ],
     };
-    if (!opts.machine.isHumanState(result.to)) {
-        return { message: commit(moved), moved: { from, to: result.to } };
-    }
+    if (!machine.isHumanState(move.to))
+        return { update };
     // Into a human state: the park record is committed with the transition, so a
     // process that dies before the closing turn still sees a parked session.
     const seq = (fields.decisionCount ?? 0) + 1;
-    const park = decisionRecordFor(opts.machine, result.to, seq, evidence);
+    const park = decisionRecordFor(machine, move.to, seq, move.evidence ?? []);
     return {
-        message: commit({
-            ...moved,
+        update: {
+            ...update,
             pendingDecision: park,
             decisionCount: seq,
             status: WORKFLOW_STATUSES.awaitingDecision,
             parkPhase: "closing",
+        },
+        park,
+    };
+}
+/**
+ * Why `from` may not be left for `to` right now, or `undefined` when it may: the
+ * kernel's transition verdict — the state's `requires` against `variables`, then
+ * the declared edge. Every refusal is recoverable: the mover sets what is owed,
+ * or picks a valid target.
+ */
+export function transitionRefusal(machine, from, to, variables) {
+    const verdict = decide(machine, { kind: "transition", from, to }, [], undefined, variables);
+    return verdict.decision === "block" ? (verdict.reason ?? `cannot advance from '${from}' to '${to}'.`) : undefined;
+}
+/**
+ * Evidence an advance attaches, validated for the target: accepted only into a
+ * human state, and only paths the session itself could read.
+ */
+export function advanceEvidence(machine, to, attached, mounts = NO_MOUNTS) {
+    if (attached.length === 0)
+        return { ok: true, paths: [] };
+    if (!machine.isHumanState(to)) {
+        return {
+            ok: false,
+            reason: `evidence can only be attached when advancing into a human decision state, and '${to}' ` +
+                `is not one — nothing would present it. Call again without 'evidence'.`,
+        };
+    }
+    return validateAdvanceEvidence(attached, mounts);
+}
+/**
+ * Service the session's agent's `archmax_advance`: validate the arguments, the
+ * evidence and the transition, then commit {@link transitionUpdate} with the
+ * reply the agent reads. A refusal leaves the session exactly where it was — no
+ * trail step — and replies without erroring the message, so the agent corrects
+ * the call rather than reading a failed run.
+ */
+export function handleAdvance(opts, request) {
+    const reply = (text) => toolReply(ADVANCE_TOOL, request.toolCallId, text);
+    const parsed = advanceSchema.safeParse(request.args);
+    if (!parsed.success) {
+        return {
+            message: refusal(ADVANCE_TOOL, request.toolCallId, `${ADVANCE_TOOL} rejected: invalid arguments — ${schemaIssues(parsed.error)}`),
+        };
+    }
+    const { to, reason } = parsed.data;
+    // Evidence is settled before the transition is attempted, so a refused
+    // attachment leaves the run exactly where it was.
+    const evidence = advanceEvidence(opts.machine, to, parsed.data.evidence ?? [], opts.mountPrefixes);
+    if (!evidence.ok)
+        return { message: refusal(ADVANCE_TOOL, request.toolCallId, `${ADVANCE_TOOL} rejected: ${evidence.reason}`) };
+    const from = currentWorkflowState(request.state, opts.machine.entry);
+    const refused = transitionRefusal(opts.machine, from, to, readVariables(request.state));
+    if (refused)
+        return { message: reply(`${ADVANCE_TOOL} rejected: ${refused}`) };
+    const { update, park } = transitionUpdate(opts.machine, request.state, {
+        to,
+        kind: "agent",
+        reason,
+        evidence: evidence.paths,
+    });
+    return {
+        message: commit({
+            ...update,
+            messages: [reply(`Advanced to state '${to}'. You may now use the tools allowed in this state.`)],
         }),
-        moved: { from, to: result.to, park },
+        moved: { from, to, reason, ...(park ? { park } : {}) },
     };
 }
 // --- archmax_wait ----------------------------------------------------------------
@@ -364,9 +392,9 @@ export function entryStateOf(state, machine) {
     return (triggerId ? machine.startStateForTrigger(triggerId) : undefined) ?? machine.entry;
 }
 /**
- * Service a reset: move back to the entry state and clear what gates progress
- * (correction budgets, `beforeDone`). Evidence — messages, files, variables, the
- * trail — is left alone: a reset moves the machine, not the history.
+ * Service a reset: move back to the entry state. Evidence — messages, files,
+ * variables, the trail — is left alone: a reset moves the machine, not the
+ * history.
  */
 export function handleReset(machine, request) {
     const parsed = resetSchema.safeParse(request.args);
@@ -377,17 +405,26 @@ export function handleReset(machine, request) {
     }
     const from = currentWorkflowState(request.state, machine.entry);
     const entry = entryStateOf(readWorkflowState(request.state), machine);
+    // The locks this run set are released, each value kept; the host's stay. A
+    // boundary write is the only one the merge accepts over a lock.
+    const released = Object.entries(readVariables(request.state)).filter(([, held]) => held.locked && held.lockedBy === "agent");
     return {
         message: commit({
             workflowState: entry,
-            iterations: {},
-            beforeDone: {},
             ...NO_PENDING_FAILURE,
             stateTurns: null,
             auditTrail: [{ to: entry, kind: "reset", reason: parsed.data.reason, ts: Date.now() }],
+            ...(released.length > 0
+                ? {
+                    variables: Object.fromEntries(released.map(([name, held]) => [name, { value: held.value, locked: false, reseed: true }])),
+                }
+                : {}),
             messages: [
-                toolReply(RESET_TOOL, request.toolCallId, `Reset to state '${entry}'. Correction budgets are cleared and its entry gate runs ` +
-                    `again; earlier work in the conversation and in scratchpad/ is untouched.`),
+                toolReply(RESET_TOOL, request.toolCallId, `Reset to state '${entry}'. Earlier work in the conversation and in scratchpad/ is ` +
+                    `untouched.` +
+                    (released.length > 0
+                        ? ` The locks you set are released: ${released.map(([name]) => `'${name}'`).join(", ")} can be written again.`
+                        : "")),
             ],
         }),
         moved: { from, to: entry },
@@ -415,9 +452,9 @@ function callsInMessageOf(state, toolCallId) {
  * Service a raise: end the session as a failure in the state it was called in.
  * Commits the record and `status: failed`, and drops a pending rejection — the
  * agent's own account of the failure is what the session ends with. The turn
- * ends at the next model hook; nothing routes and no hook runs. Refused, with the
- * session left in place, for invalid arguments or a message making other calls:
- * those run concurrently, so a raise beside them could not mean one thing.
+ * ends at the next model hook; nothing routes and nothing further runs. Refused,
+ * with the session left in place, for invalid arguments or a message making other
+ * calls: those run concurrently, so a raise beside them could not mean one thing.
  */
 export function handleRaise(machine, request) {
     const refuse = (text) => ({ message: refusal(RAISE_TOOL, request.toolCallId, text) });
@@ -516,6 +553,16 @@ fileRefusal) {
             return refuse(`${SET_VARIABLES_TOOL} rejected: '${name}' is locked and cannot be changed ` +
                 `(current value: ${JSON.stringify(store[name]?.value)}). Nothing was written.`);
         }
+        // An owned variable is decided in its owner alone, and stays changeable there.
+        const owner = machine?.ownerOf(name);
+        if (owner !== undefined && owner !== currentWorkflowState(request.state, machine.entry)) {
+            return refuse(`${SET_VARIABLES_TOOL} rejected: '${name}' belongs to state '${owner}': only '${owner}' can ` +
+                `change it. Go back to '${owner}' to change it. Nothing was written.`);
+        }
+        if (owner !== undefined && lock === true) {
+            return refuse(`${SET_VARIABLES_TOOL} rejected: '${name}' belongs to this state, '${owner}', so it stays ` +
+                `changeable here and cannot be locked. Retry without \`lock\`. Nothing was written.`);
+        }
         if (name === TITLE_VARIABLE) {
             // Refused, not silently dropped: an agent that believes it locked the title must not be lied to.
             if (lock === true) {
@@ -539,7 +586,7 @@ fileRefusal) {
         delta[name] =
             name === TITLE_VARIABLE
                 ? { value: normalizeTitle(value), locked: false }
-                : { value, locked };
+                : { value, locked, ...(locked ? { lockedBy: "agent" } : {}) };
     }
     return {
         message: toolReply(SET_VARIABLES_TOOL, request.toolCallId, `Set ${names.join(", ")}${locked ? " (locked)" : ""}.`),
@@ -592,10 +639,7 @@ export function setVariablesCommand(outcome) {
         return outcome.message;
     return commit({ variables: outcome.delta, messages: [outcome.message] });
 }
-/** The variables a state still owes before it may be left — its `requires` minus what is set. */
-export function unmetRequirements(required, store) {
-    return required.filter((name) => store[name] === undefined);
-}
+export { unmetRequirements } from "../kernel/kernel.js";
 /**
  * The wording for a `${{…}}` reference in the agent's own tool arguments that
  * could not be resolved: a correctable refusal carrying the two fixes it might