@cat-factory/orchestration 0.13.0 → 0.14.0

package/dist/modules/execution/HumanTestController.d.ts

@@ -0,0 +1,147 @@
+import type { AgentExecutor, Block, BlockRepository, BranchUpdater, EnvironmentHandle, ExecutionInstance, ExecutionRepository, PipelineStep, WorkRunner } from '@cat-factory/kernel';
+import type { NotificationService } from '../notifications/NotificationService.js';
+import type { AdvanceResult } from './advance.js';
+import type { AgentContextBuilder } from './AgentContextBuilder.js';
+/**
+ * The engine collaborators the human-testing gate drives (kept on the engine, injected here).
+ * The environment + branch-update seams are optional — absent ones put the gate into its
+ * degraded "manual" mode rather than failing.
+ */
+export interface HumanTestControllerDeps {
+    blockRepository: BlockRepository;
+    executionRepository: ExecutionRepository;
+    workRunner: WorkRunner;
+    agentExecutor: AgentExecutor;
+    contextBuilder: AgentContextBuilder;
+    notificationService?: NotificationService;
+    /** Provision a fresh ephemeral env for the block (wraps the env provisioning service). */
+    provisionEnvironment?: (workspaceId: string, block: Block, executionId: string) => Promise<EnvironmentHandle>;
+    /** Re-poll an env's status (wraps the env provisioning service). */
+    refreshEnvironment?: (workspaceId: string, environmentId: string) => Promise<EnvironmentHandle>;
+    /** Tear an env down (wraps the env teardown service). Best-effort. */
+    teardownEnvironment?: (workspaceId: string, environmentId: string) => Promise<void>;
+    /** Merge the repo default branch into the block's PR branch (server-side). */
+    branchUpdater?: BranchUpdater;
+    /** The task's helper attempt budget (from the resolved merge preset). */
+    resolveMergePreset: (workspaceId: string, block: Block) => Promise<{
+        ciMaxAttempts: number;
+    }>;
+    parkStepOnDecision: (workspaceId: string, instance: ExecutionInstance, step: PipelineStep, proposal?: string) => Promise<AdvanceResult>;
+    finishStep: (step: PipelineStep) => void;
+    startStep: (step: PipelineStep) => void;
+    updateBlockProgress: (workspaceId: string, instance: ExecutionInstance, status: 'in_progress' | 'blocked') => Promise<void>;
+    finalizeBlock: (workspaceId: string, instance: ExecutionInstance, confidence: number | undefined) => Promise<void>;
+    stopRunContainer: (workspaceId: string, instance: ExecutionInstance) => Promise<void>;
+    persistInstance: (workspaceId: string, instance: ExecutionInstance) => Promise<void>;
+    emitInstance: (workspaceId: string, instance: ExecutionInstance) => Promise<void>;
+    clockNow: () => number;
+}
+/** The settle outcome of a helper (fixer / conflict-resolver) job, as seen by the gate. */
+type HelperUpdate = {
+    state: 'done';
+} | {
+    state: 'failed';
+};
+/**
+ * Drives the `human-test` gate: a non-LLM engine step where a HUMAN is the verdict. When the
+ * step is reached it spins up an ephemeral environment and PARKS, surfacing the live URL; a
+ * person validates the change and then drives one of a handful of actions — confirm (tear the
+ * env down + advance), request a fix from findings (dispatch the Tester's `fixer`, rebuild the
+ * env, re-park), pull main into the branch + redeploy (a clean merge rebuilds the env; a
+ * conflict dispatches the `conflict-resolver`), recreate, or destroy the env. Modelled like the
+ * iterative review gates: the slow/awaiting work runs in the durable driver (the human actions
+ * just record intent + signal), so the HTTP request the user is no longer waiting on never
+ * blocks. Extracted out of `ExecutionService`; the shared step-graph primitives stay on the
+ * engine and are injected via {@link HumanTestControllerDeps}.
+ */
+export declare class HumanTestController {
+    private readonly deps;
+    constructor(deps: HumanTestControllerDeps);
+    /**
+     * Run the gate from `stepInstance`. On FRESH entry (no state yet) it provisions an
+     * environment and parks (or degrades to manual mode when no provider is wired). On RE-ENTRY
+     * after a human action (a `pendingAction` is set on the parked step) it consumes that action.
+     * Otherwise (a replay with no pending action) it re-derives from the current phase.
+     */
+    evaluate(workspaceId: string, instance: ExecutionInstance, step: PipelineStep, block: Block, isFinalStep: boolean): Promise<AdvanceResult>;
+    /**
+     * Re-poll the in-flight environment provisioning from the durable driver's `awaiting_gate`
+     * loop (delegated from `pollGate` when the current step is a human-test gate still
+     * provisioning). Ready → park for the human; still provisioning → keep polling; failed →
+     * degrade to manual mode and park so the human can recreate or test by hand.
+     */
+    pollEnvironment(workspaceId: string, instance: ExecutionInstance): Promise<AdvanceResult>;
+    /**
+     * The provisioning poll budget was spent while still provisioning (delegated from
+     * `resolveGatePollExhaustion`). Don't fail the run — park in degraded mode so the human can
+     * wait, recreate, or test by hand. The env record keeps provisioning in the background.
+     */
+    onProvisionTimeout(workspaceId: string, instance: ExecutionInstance): Promise<AdvanceResult>;
+    /**
+     * A helper job (fixer / conflict-resolver) the gate dispatched has settled (delegated from
+     * `pollAgentJob`). Record the round's outcome and rebuild the environment against the
+     * (now-updated) branch, then re-park the human. We never fail the whole run here — the human
+     * is in control and can request another fix.
+     */
+    onHelperComplete(workspaceId: string, instance: ExecutionInstance, step: PipelineStep, update: HelperUpdate): Promise<AdvanceResult>;
+    /** The human confirmed the change works: tear the env down and advance the run. */
+    confirm(workspaceId: string, blockId: string): Promise<ExecutionInstance>;
+    /** The human wrote findings and asked for a fix: dispatch the Tester's `fixer`. */
+    requestFix(workspaceId: string, blockId: string, findings: string): Promise<ExecutionInstance>;
+    /** Pull the repo default branch into the PR branch + redeploy (conflict → conflict-resolver). */
+    pullMain(workspaceId: string, blockId: string): Promise<ExecutionInstance>;
+    /** Rebuild the ephemeral environment on demand. */
+    recreateEnvironment(workspaceId: string, blockId: string): Promise<ExecutionInstance>;
+    /**
+     * Destroy the ephemeral environment on demand WITHOUT advancing — the run stays parked so the
+     * human can recreate it (or confirm/test manually) later. Synchronous: no durable driver
+     * involvement, since nothing about the run's position changes.
+     */
+    destroyEnvironment(workspaceId: string, blockId: string): Promise<ExecutionInstance>;
+    /** Fresh entry: stand up an environment (or degrade) and park for the human. */
+    private begin;
+    /** Consume a human-requested action on re-entry. */
+    private handleAction;
+    /** Pull main into the PR branch; clean → rebuild env; conflict → conflict-resolver. */
+    private pullMainInDriver;
+    /**
+     * Dispatch a helper container — the Tester's `fixer` (from findings) or the
+     * `conflict-resolver` (after a conflicting pull-main) — and park on its job. The gate's
+     * phase tracks which helper is in flight; `onHelperComplete` rebuilds the env on its settle.
+     */
+    private dispatchHelper;
+    /** Tear down the current env (best-effort) and provision a fresh one, then re-park. */
+    private recreateAndContinue;
+    /** Park in degraded (manual) mode: no live env, but the human can still test + confirm. */
+    private degrade;
+    /** Flip to awaiting-human, summon the human (idempotent notification), and park. */
+    private toAwaitingHuman;
+    /** Finish the gate step and advance to the next step (or finish the run). No re-signal. */
+    private completeStep;
+    /**
+     * Record the human's action on the parked gate step and wake the durable driver, which
+     * re-enters {@link evaluate} and acts on it (the analogue of `incorporateRequirements`).
+     * Re-arms the run to `running` first so the woken driver advances instead of no-oping.
+     */
+    private signalAction;
+    /** Locate the run + gate step a block's human-test gate is parked on (or null). */
+    private findParked;
+    /**
+     * Locate the run + gate step for a block's ACTIVE human-test gate — parked for the human OR
+     * still provisioning an env (the two phases a human can destroy from). Unlike {@link
+     * findParked} it does not require a pending approval, so a provisioning env can be cancelled.
+     */
+    private findActive;
+    private requireParked;
+    /** Tear down the env tracked on the step (best-effort) and forget it locally. */
+    private teardownCurrent;
+    /** Project an environment handle onto the compact view carried on the step. */
+    private toEnvView;
+    private proposal;
+    /** Summon the human to test (idempotent per block+type). Best-effort. */
+    private raiseReadyNotification;
+    /** Dismiss the "ready for testing" card once the gate passes. Best-effort. */
+    private clearReadyNotification;
+}
+export {};
+//# sourceMappingURL=HumanTestController.d.ts.map

package/dist/modules/execution/HumanTestController.d.ts.map

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

package/dist/modules/execution/HumanTestController.js

@@ -0,0 +1,493 @@
+import { ConflictError, getErrorMessage, isAsyncAgentExecutor } from '@cat-factory/kernel';
+import { CONFLICT_RESOLVER_AGENT_KIND, FIXER_AGENT_KIND, HUMAN_TEST_AGENT_KIND, } from './ci.logic.js';
+/** Render the human's findings as the resolved-context block handed to the fixer. */
+function renderFindingsForFixer(findings) {
+    return [
+        'A human tested the change in a live environment and found the issues below.',
+        'Fix them and push to the PR branch; the environment will be rebuilt for re-testing.',
+        '',
+        findings.trim(),
+    ]
+        .join('\n')
+        .trim();
+}
+/**
+ * Drives the `human-test` gate: a non-LLM engine step where a HUMAN is the verdict. When the
+ * step is reached it spins up an ephemeral environment and PARKS, surfacing the live URL; a
+ * person validates the change and then drives one of a handful of actions — confirm (tear the
+ * env down + advance), request a fix from findings (dispatch the Tester's `fixer`, rebuild the
+ * env, re-park), pull main into the branch + redeploy (a clean merge rebuilds the env; a
+ * conflict dispatches the `conflict-resolver`), recreate, or destroy the env. Modelled like the
+ * iterative review gates: the slow/awaiting work runs in the durable driver (the human actions
+ * just record intent + signal), so the HTTP request the user is no longer waiting on never
+ * blocks. Extracted out of `ExecutionService`; the shared step-graph primitives stay on the
+ * engine and are injected via {@link HumanTestControllerDeps}.
+ */
+export class HumanTestController {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    // ---- driver-entry paths --------------------------------------------------
+    /**
+     * Run the gate from `stepInstance`. On FRESH entry (no state yet) it provisions an
+     * environment and parks (or degrades to manual mode when no provider is wired). On RE-ENTRY
+     * after a human action (a `pendingAction` is set on the parked step) it consumes that action.
+     * Otherwise (a replay with no pending action) it re-derives from the current phase.
+     */
+    async evaluate(workspaceId, instance, step, block, isFinalStep) {
+        const ht = step.humanTest;
+        if (ht?.pendingAction) {
+            const action = ht.pendingAction;
+            ht.pendingAction = null;
+            // Checkpoint the consumed action BEFORE doing any slow/side-effecting work (a helper
+            // dispatch is a real container). The driver runs `advance` inside a retriable durable
+            // step: if the slow work succeeds but its later persist throws, the closure retries —
+            // and unless the cleared `pendingAction` is already in storage it would re-consume the
+            // action and dispatch a SECOND helper. Persisting now makes the dispatch at-most-once
+            // (a crash between here and the dispatch merely drops the action; the human re-requests).
+            await this.deps.persistInstance(workspaceId, instance);
+            return this.handleAction(workspaceId, instance, step, block, isFinalStep, action);
+        }
+        if (!ht)
+            return this.begin(workspaceId, instance, step, block);
+        // Replay / re-entry with no pending action: re-derive from the phase.
+        if (ht.phase === 'provisioning') {
+            return { kind: 'awaiting_gate', stepIndex: instance.currentStep };
+        }
+        // A helper (fixer / conflict-resolver) is in flight: the step is `working` with a live
+        // job, NOT parked. Re-attach to its job instead of re-parking, so a re-drive through
+        // `advance` (the stale-run sweeper, or a durable replay that lost the `awaiting_job`
+        // position) keeps polling the job rather than abandoning it.
+        if ((ht.phase === 'fixing' || ht.phase === 'resolving_conflicts') && step.jobId) {
+            return { kind: 'awaiting_job', jobId: step.jobId, stepIndex: instance.currentStep };
+        }
+        return this.deps.parkStepOnDecision(workspaceId, instance, step, this.proposal(ht));
+    }
+    /**
+     * Re-poll the in-flight environment provisioning from the durable driver's `awaiting_gate`
+     * loop (delegated from `pollGate` when the current step is a human-test gate still
+     * provisioning). Ready → park for the human; still provisioning → keep polling; failed →
+     * degrade to manual mode and park so the human can recreate or test by hand.
+     */
+    async pollEnvironment(workspaceId, instance) {
+        const step = instance.steps[instance.currentStep];
+        if (!step || step.agentKind !== HUMAN_TEST_AGENT_KIND || !step.humanTest) {
+            return { kind: 'continue' };
+        }
+        const ht = step.humanTest;
+        if (ht.phase !== 'provisioning')
+            return { kind: 'continue' };
+        const block = await this.deps.blockRepository.get(workspaceId, instance.blockId);
+        if (!block)
+            return { kind: 'noop' };
+        if (!this.deps.refreshEnvironment || !ht.environment) {
+            return this.degrade(workspaceId, instance, step, block, 'Environment is no longer tracked.');
+        }
+        let handle;
+        try {
+            handle = await this.deps.refreshEnvironment(workspaceId, ht.environment.id);
+        }
+        catch (error) {
+            return this.degrade(workspaceId, instance, step, block, `Could not read the environment status (${getErrorMessage(error)}).`);
+        }
+        ht.environment = this.toEnvView(handle);
+        if (handle.status === 'ready') {
+            return this.toAwaitingHuman(workspaceId, instance, step, block);
+        }
+        if (handle.status === 'failed' ||
+            handle.status === 'expired' ||
+            handle.status === 'torn_down') {
+            return this.degrade(workspaceId, instance, step, block, 'Environment provisioning failed; recreate it or test against the PR branch.');
+        }
+        await this.deps.persistInstance(workspaceId, instance);
+        await this.deps.emitInstance(workspaceId, instance);
+        return { kind: 'awaiting_gate', stepIndex: instance.currentStep };
+    }
+    /**
+     * The provisioning poll budget was spent while still provisioning (delegated from
+     * `resolveGatePollExhaustion`). Don't fail the run — park in degraded mode so the human can
+     * wait, recreate, or test by hand. The env record keeps provisioning in the background.
+     */
+    async onProvisionTimeout(workspaceId, instance) {
+        const step = instance.steps[instance.currentStep];
+        if (!step || step.agentKind !== HUMAN_TEST_AGENT_KIND || !step.humanTest) {
+            return { kind: 'continue' };
+        }
+        const block = await this.deps.blockRepository.get(workspaceId, instance.blockId);
+        if (!block)
+            return { kind: 'noop' };
+        return this.degrade(workspaceId, instance, step, block, 'Environment is taking longer than expected to provision; recreate it or test against the PR branch.');
+    }
+    /**
+     * A helper job (fixer / conflict-resolver) the gate dispatched has settled (delegated from
+     * `pollAgentJob`). Record the round's outcome and rebuild the environment against the
+     * (now-updated) branch, then re-park the human. We never fail the whole run here — the human
+     * is in control and can request another fix.
+     */
+    async onHelperComplete(workspaceId, instance, step, update) {
+        const ht = step.humanTest;
+        if (!ht)
+            return { kind: 'continue' };
+        const rounds = ht.rounds ?? [];
+        const last = rounds[rounds.length - 1];
+        if (last && !last.outcome)
+            last.outcome = update.state === 'failed' ? 'failed' : 'completed';
+        step.jobId = undefined;
+        step.subtasks = undefined;
+        // Reclaim the finished helper container before reprovisioning so a fresh env build
+        // doesn't re-attach to the completed job by run id.
+        await this.deps.stopRunContainer(workspaceId, instance);
+        const block = await this.deps.blockRepository.get(workspaceId, instance.blockId);
+        if (!block)
+            return { kind: 'noop' };
+        return this.recreateAndContinue(workspaceId, instance, step, block);
+    }
+    // ---- human actions (called from ExecutionService, driven server-side) ----
+    /** The human confirmed the change works: tear the env down and advance the run. */
+    async confirm(workspaceId, blockId) {
+        return this.signalAction(workspaceId, blockId, { type: 'confirm' });
+    }
+    /** The human wrote findings and asked for a fix: dispatch the Tester's `fixer`. */
+    async requestFix(workspaceId, blockId, findings) {
+        return this.signalAction(workspaceId, blockId, { type: 'request-fix', findings });
+    }
+    /** Pull the repo default branch into the PR branch + redeploy (conflict → conflict-resolver). */
+    async pullMain(workspaceId, blockId) {
+        return this.signalAction(workspaceId, blockId, { type: 'pull-main' });
+    }
+    /** Rebuild the ephemeral environment on demand. */
+    async recreateEnvironment(workspaceId, blockId) {
+        return this.signalAction(workspaceId, blockId, { type: 'recreate' });
+    }
+    /**
+     * Destroy the ephemeral environment on demand WITHOUT advancing — the run stays parked so the
+     * human can recreate it (or confirm/test manually) later. Synchronous: no durable driver
+     * involvement, since nothing about the run's position changes.
+     */
+    async destroyEnvironment(workspaceId, blockId) {
+        // Destroy is allowed both while parked (awaiting_human) AND while an env is still
+        // provisioning — a human must be able to cancel a slow/stuck provision without waiting
+        // for the poll budget to exhaust.
+        const { instance, step } = this.requireParked(await this.findActive(workspaceId, blockId));
+        const ht = step.humanTest;
+        await this.teardownCurrent(workspaceId, ht);
+        if (ht.phase === 'provisioning') {
+            // Cancelled mid-provision: drop the env so the driver's next `pollEnvironment` (which
+            // owns the phase transitions during provisioning) hits its `!ht.environment` guard and
+            // degrades to manual mode, parking the human. We don't flip the phase here ourselves —
+            // the durable poll loop is the single owner of that transition.
+            ht.environment = null;
+        }
+        else if (ht.environment) {
+            ht.environment = { ...ht.environment, status: 'torn_down' };
+        }
+        await this.deps.persistInstance(workspaceId, instance);
+        await this.deps.emitInstance(workspaceId, instance);
+        return instance;
+    }
+    // ---- internals -----------------------------------------------------------
+    /** Fresh entry: stand up an environment (or degrade) and park for the human. */
+    async begin(workspaceId, instance, step, block) {
+        const maxAttempts = (await this.deps.resolveMergePreset(workspaceId, block)).ciMaxAttempts;
+        step.humanTest = {
+            phase: 'provisioning',
+            environment: null,
+            attempts: 0,
+            maxAttempts,
+            rounds: [],
+            ...(block.pullRequest?.branch ? { headSha: null } : {}),
+        };
+        if (!this.deps.provisionEnvironment) {
+            return this.degrade(workspaceId, instance, step, block, 'No ephemeral-environment provider is configured; test against the PR branch and confirm here.');
+        }
+        try {
+            const handle = await this.deps.provisionEnvironment(workspaceId, block, instance.id);
+            step.humanTest.environment = this.toEnvView(handle);
+            if (handle.status === 'ready') {
+                return this.toAwaitingHuman(workspaceId, instance, step, block);
+            }
+            await this.deps.persistInstance(workspaceId, instance);
+            await this.deps.emitInstance(workspaceId, instance);
+            return { kind: 'awaiting_gate', stepIndex: instance.currentStep };
+        }
+        catch (error) {
+            return this.degrade(workspaceId, instance, step, block, `Could not provision an environment (${getErrorMessage(error)}); test against the PR branch and confirm here.`);
+        }
+    }
+    /** Consume a human-requested action on re-entry. */
+    async handleAction(workspaceId, instance, step, block, isFinalStep, action) {
+        const ht = step.humanTest;
+        switch (action.type) {
+            case 'confirm': {
+                await this.teardownCurrent(workspaceId, ht);
+                ht.phase = 'passed';
+                if (ht.environment)
+                    ht.environment = { ...ht.environment, status: 'torn_down' };
+                await this.clearReadyNotification(workspaceId, instance.blockId);
+                return this.completeStep(workspaceId, instance, step, isFinalStep);
+            }
+            case 'request-fix':
+                return this.dispatchHelper(workspaceId, instance, step, block, 'fix', action.findings ?? '');
+            case 'pull-main':
+                return this.pullMainInDriver(workspaceId, instance, step, block);
+            case 'recreate':
+                return this.recreateAndContinue(workspaceId, instance, step, block);
+        }
+    }
+    /** Pull main into the PR branch; clean → rebuild env; conflict → conflict-resolver. */
+    async pullMainInDriver(workspaceId, instance, step, block) {
+        if (!this.deps.branchUpdater) {
+            return this.toAwaitingHuman(workspaceId, instance, step, block);
+        }
+        let outcome;
+        try {
+            outcome = await this.deps.branchUpdater.updateFromBase(workspaceId, block.id);
+        }
+        catch {
+            // The branch update failed (e.g. no PR): leave the human parked to retry/confirm.
+            return this.toAwaitingHuman(workspaceId, instance, step, block);
+        }
+        if (outcome === 'conflict') {
+            return this.dispatchHelper(workspaceId, instance, step, block, 'pull-main', '');
+        }
+        // merged / noop → rebuild the env against the updated branch.
+        return this.recreateAndContinue(workspaceId, instance, step, block);
+    }
+    /**
+     * Dispatch a helper container — the Tester's `fixer` (from findings) or the
+     * `conflict-resolver` (after a conflicting pull-main) — and park on its job. The gate's
+     * phase tracks which helper is in flight; `onHelperComplete` rebuilds the env on its settle.
+     */
+    async dispatchHelper(workspaceId, instance, step, block, roundKind, findings) {
+        const ht = step.humanTest;
+        const executor = this.deps.agentExecutor;
+        if (!isAsyncAgentExecutor(executor)) {
+            return this.toAwaitingHuman(workspaceId, instance, step, block);
+        }
+        // Both helpers push onto the implementation PR branch, so they need one to exist.
+        if (!block.pullRequest?.branch) {
+            return this.toAwaitingHuman(workspaceId, instance, step, block);
+        }
+        const helperKind = roundKind === 'fix' ? FIXER_AGENT_KIND : CONFLICT_RESOLVER_AGENT_KIND;
+        const isFinalStep = instance.currentStep === instance.steps.length - 1;
+        const base = await this.deps.contextBuilder.buildContext(workspaceId, instance, step, isFinalStep, block);
+        const context = roundKind === 'fix'
+            ? {
+                ...base,
+                agentKind: helperKind,
+                priorOutputs: [
+                    ...base.priorOutputs,
+                    { agentKind: HUMAN_TEST_AGENT_KIND, output: renderFindingsForFixer(findings) },
+                ],
+            }
+            : { ...base, agentKind: helperKind };
+        const handle = await executor.startJob(context);
+        step.jobId = handle.jobId;
+        if (handle.model)
+            step.model = handle.model;
+        step.startingContainer = true;
+        step.subtasks = undefined;
+        // Leave the parked decision state: while the helper runs the step is `working` with a
+        // live job (like the Tester→Fixer loop), NOT `waiting_decision` on a stale approval. If
+        // it stayed parked, a re-drive through `advance` (sweeper / replay) would re-park on the
+        // old approval id and silently abandon the in-flight helper. The human re-parks on a
+        // fresh approval once the helper settles (`onHelperComplete` → `toAwaitingHuman`).
+        this.deps.startStep(step);
+        step.approval = null;
+        ht.phase = roundKind === 'fix' ? 'fixing' : 'resolving_conflicts';
+        ht.attempts += 1;
+        ht.rounds = [
+            ...(ht.rounds ?? []),
+            {
+                kind: roundKind,
+                findings: roundKind === 'fix' ? findings : 'Pulled latest main into the branch (conflicts).',
+                helperKind,
+                jobId: handle.jobId,
+                outcome: null,
+                at: this.deps.clockNow(),
+            },
+        ];
+        await this.deps.persistInstance(workspaceId, instance);
+        await this.deps.emitInstance(workspaceId, instance);
+        return { kind: 'awaiting_job', jobId: step.jobId, stepIndex: instance.currentStep };
+    }
+    /** Tear down the current env (best-effort) and provision a fresh one, then re-park. */
+    async recreateAndContinue(workspaceId, instance, step, block) {
+        const ht = step.humanTest;
+        await this.teardownCurrent(workspaceId, ht);
+        // The old env is gone — drop it immediately so that if the re-provision below fails (or
+        // no provider is wired) the gate degrades to a clean manual mode instead of surfacing a
+        // stale "ready" env + live URL pointing at the just-destroyed environment. The success
+        // path overwrites this with the fresh handle.
+        ht.environment = null;
+        if (!this.deps.provisionEnvironment) {
+            return this.degrade(workspaceId, instance, step, block, 'No ephemeral-environment provider is configured; test against the PR branch and confirm here.');
+        }
+        try {
+            const handle = await this.deps.provisionEnvironment(workspaceId, block, instance.id);
+            ht.environment = this.toEnvView(handle);
+            ht.degradedReason = null;
+            if (handle.status === 'ready') {
+                return this.toAwaitingHuman(workspaceId, instance, step, block);
+            }
+            ht.phase = 'provisioning';
+            await this.deps.persistInstance(workspaceId, instance);
+            await this.deps.emitInstance(workspaceId, instance);
+            return { kind: 'awaiting_gate', stepIndex: instance.currentStep };
+        }
+        catch (error) {
+            return this.degrade(workspaceId, instance, step, block, `Could not provision an environment (${getErrorMessage(error)}); test against the PR branch and confirm here.`);
+        }
+    }
+    /** Park in degraded (manual) mode: no live env, but the human can still test + confirm. */
+    async degrade(workspaceId, instance, step, block, reason) {
+        const ht = step.humanTest;
+        ht.degradedReason = reason;
+        return this.toAwaitingHuman(workspaceId, instance, step, block);
+    }
+    /** Flip to awaiting-human, summon the human (idempotent notification), and park. */
+    async toAwaitingHuman(workspaceId, instance, step, block) {
+        const ht = step.humanTest;
+        ht.phase = 'awaiting_human';
+        await this.raiseReadyNotification(workspaceId, instance, block, ht);
+        return this.deps.parkStepOnDecision(workspaceId, instance, step, this.proposal(ht));
+    }
+    /** Finish the gate step and advance to the next step (or finish the run). No re-signal. */
+    async completeStep(workspaceId, instance, step, isFinalStep) {
+        this.deps.finishStep(step);
+        step.progress = 1;
+        step.subtasks = undefined;
+        step.approval = null;
+        if (isFinalStep) {
+            instance.status = 'done';
+            await this.deps.finalizeBlock(workspaceId, instance, undefined);
+            await this.deps.persistInstance(workspaceId, instance);
+            await this.deps.emitInstance(workspaceId, instance);
+            await this.deps.stopRunContainer(workspaceId, instance);
+            return { kind: 'done' };
+        }
+        instance.currentStep += 1;
+        const next = instance.steps[instance.currentStep];
+        if (next)
+            this.deps.startStep(next);
+        await this.deps.updateBlockProgress(workspaceId, instance, 'in_progress');
+        await this.deps.persistInstance(workspaceId, instance);
+        await this.deps.emitInstance(workspaceId, instance);
+        return { kind: 'continue' };
+    }
+    /**
+     * Record the human's action on the parked gate step and wake the durable driver, which
+     * re-enters {@link evaluate} and acts on it (the analogue of `incorporateRequirements`).
+     * Re-arms the run to `running` first so the woken driver advances instead of no-oping.
+     */
+    async signalAction(workspaceId, blockId, action) {
+        const { instance, step } = this.requireParked(await this.findParked(workspaceId, blockId));
+        const ht = step.humanTest;
+        // Honour the resolved fix-attempt ceiling (the sibling Tester gate enforces the same
+        // `ciMaxAttempts`). The human stays in control of the other actions (confirm / pull main /
+        // recreate); only the findings-driven fix loop is capped, so it can't run away.
+        if (action.type === 'request-fix' && ht.attempts >= ht.maxAttempts) {
+            throw new ConflictError(`This task has reached its fix-attempt limit (${ht.maxAttempts}); confirm the change, pull main, or recreate the environment instead.`);
+        }
+        ht.pendingAction = action;
+        if (instance.status === 'blocked')
+            instance.status = 'running';
+        await this.deps.persistInstance(workspaceId, instance);
+        await this.deps.emitInstance(workspaceId, instance);
+        await this.deps.workRunner.signalDecision(workspaceId, instance.id, step.approval.id, 'human-test');
+        return instance;
+    }
+    /** Locate the run + gate step a block's human-test gate is parked on (or null). */
+    async findParked(workspaceId, blockId) {
+        const block = await this.deps.blockRepository.get(workspaceId, blockId);
+        if (!block?.executionId)
+            return null;
+        const instance = await this.deps.executionRepository.get(workspaceId, block.executionId);
+        if (!instance)
+            return null;
+        const step = instance.steps.find((s) => s.agentKind === HUMAN_TEST_AGENT_KIND &&
+            s.state === 'waiting_decision' &&
+            s.approval?.status === 'pending');
+        return step ? { instance, step } : null;
+    }
+    /**
+     * Locate the run + gate step for a block's ACTIVE human-test gate — parked for the human OR
+     * still provisioning an env (the two phases a human can destroy from). Unlike {@link
+     * findParked} it does not require a pending approval, so a provisioning env can be cancelled.
+     */
+    async findActive(workspaceId, blockId) {
+        const block = await this.deps.blockRepository.get(workspaceId, blockId);
+        if (!block?.executionId)
+            return null;
+        const instance = await this.deps.executionRepository.get(workspaceId, block.executionId);
+        if (!instance)
+            return null;
+        const step = instance.steps.find((s) => s.agentKind === HUMAN_TEST_AGENT_KIND &&
+            (s.humanTest?.phase === 'awaiting_human' || s.humanTest?.phase === 'provisioning'));
+        return step ? { instance, step } : null;
+    }
+    requireParked(found) {
+        if (!found)
+            throw new ConflictError('No human-test gate is currently awaiting input');
+        return found;
+    }
+    /** Tear down the env tracked on the step (best-effort) and forget it locally. */
+    async teardownCurrent(workspaceId, ht) {
+        const id = ht.environment?.id;
+        if (!id || !this.deps.teardownEnvironment)
+            return;
+        try {
+            await this.deps.teardownEnvironment(workspaceId, id);
+        }
+        catch {
+            // Best-effort: a failing provider must not wedge the gate. The TTL sweep reclaims it.
+        }
+    }
+    /** Project an environment handle onto the compact view carried on the step. */
+    toEnvView(handle) {
+        return {
+            id: handle.id,
+            url: handle.url,
+            status: handle.status,
+            ...(handle.expiresAt != null ? { expiresAt: handle.expiresAt } : {}),
+        };
+    }
+    proposal(ht) {
+        if (ht.environment?.url)
+            return `Test the change at ${ht.environment.url}, then confirm or request a fix.`;
+        return 'Test the change, then confirm or request a fix.';
+    }
+    /** Summon the human to test (idempotent per block+type). Best-effort. */
+    async raiseReadyNotification(workspaceId, instance, block, ht) {
+        if (!this.deps.notificationService)
+            return;
+        const where = ht.environment?.url
+            ? `Test it at ${ht.environment.url}.`
+            : 'Test it against the PR branch.';
+        await this.deps.notificationService.raise(workspaceId, {
+            type: 'human_test_ready',
+            blockId: block.id,
+            executionId: instance.id,
+            title: `"${block.title}" is ready for human testing`,
+            body: `${where} Confirm it works to continue the pipeline, or request a fix with your findings.`,
+            payload: {
+                ...(block.pullRequest?.url ? { prUrl: block.pullRequest.url } : {}),
+                pipelineName: instance.pipelineName,
+            },
+        });
+    }
+    /** Dismiss the "ready for testing" card once the gate passes. Best-effort. */
+    async clearReadyNotification(workspaceId, blockId) {
+        const svc = this.deps.notificationService;
+        if (!svc)
+            return;
+        const open = await svc.listOpen(workspaceId);
+        for (const n of open) {
+            if (n.type === 'human_test_ready' && n.blockId === blockId) {
+                await svc.resolve(workspaceId, n.id, 'act');
+            }
+        }
+    }
+}
+//# sourceMappingURL=HumanTestController.js.map