create-principles-disciple 1.79.0 → 1.81.0

package/core/dist/runtime-v2/runner/base-peer-runner.d.ts

@@ -0,0 +1,122 @@
+/**
+ * BasePeerRunner — Abstract base class for all peer runners (PRI-302).
+ *
+ * Extracts the shared lease → buildContext → invoke → poll → fetch →
+ * validate → succeed/fail pipeline from 8 duplicated runner implementations.
+ *
+ * Subclasses implement:
+ *   - permanentErrorCategories (abstract getter)
+ *   - buildContext() — runner-specific context assembly
+ *   - invokeRuntime() — runner-specific LLM invocation
+ *   - validateOutput() — runner-specific output validation
+ *   - succeedTask() — runner-specific artifact commit + task success
+ *
+ * Optional hooks:
+ *   - emitSuccessTelemetry() — runner-specific success telemetry (default: no-op)
+ *   - checkLineageIntegrity() — lineage strip contract check (default: no-op)
+ *
+ * @see docs/adr/0003-peer-agent-state-machine-orchestration.md
+ * @see Linear PRI-302
+ */
+import type { RuntimeStateManager } from '../store/runtime-state-manager.js';
+import type { PDRuntimeAdapter, RunHandle } from '../runtime-protocol.js';
+import type { StoreEventEmitter } from '../store/event-emitter.js';
+import type { PIArtifactStore } from '../internalization/pi-artifact.js';
+import type { TaskRecord } from '../task-status.js';
+import { type PDErrorCategory } from '../error-categories.js';
+import { RunnerPhase } from './runner-phase.js';
+import type { PeerRunnerOptions, ResolvedPeerRunnerOptions, PeerRunnerDeps, PeerRunnerConfig, PeerRunnerResult, PeerRunnerValidationResult, FailureContext } from './peer-runner-types.js';
+/**
+ * Abstract base class for peer runners.
+ *
+ * TContext — the type returned by buildContext(). Must include contextHash.
+ * TOutput — the type of the validated LLM output.
+ */
+export declare abstract class BasePeerRunner<TContext extends {
+    contextHash: string;
+}, TOutput> {
+    protected readonly stateManager: RuntimeStateManager;
+    protected readonly runtimeAdapter: PDRuntimeAdapter;
+    protected readonly eventEmitter: StoreEventEmitter;
+    protected readonly artifactStore: PIArtifactStore;
+    protected readonly resolvedOptions: ResolvedPeerRunnerOptions;
+    protected readonly config: PeerRunnerConfig;
+    private phase;
+    constructor(deps: PeerRunnerDeps, options: PeerRunnerOptions, config: PeerRunnerConfig);
+    /** Current internal phase. For testing/observability only. */
+    get currentPhase(): RunnerPhase;
+    /** Permanent error categories — runner's inherent property. */
+    abstract get permanentErrorCategories(): ReadonlySet<PDErrorCategory>;
+    /** Build runner-specific context from task and predecessor outputs. */
+    abstract buildContext(taskId: string): Promise<TContext>;
+    /** Invoke the runtime with runner-specific prompt builder. */
+    abstract invokeRuntime(taskId: string, context: TContext): Promise<RunHandle>;
+    /** Validate the LLM output. Receives untrusted data — must perform runtime validation. */
+    abstract validateOutput(output: unknown, taskId: string, context: TContext): Promise<PeerRunnerValidationResult>;
+    /** Commit artifact + mark task succeeded. Runner-specific commit strategy. */
+    abstract succeedTask(taskId: string, runId: string, output: TOutput, task: TaskRecord, contextHash: string, context: TContext): Promise<PeerRunnerResult<TOutput>>;
+    /** Emit runner-specific success telemetry. Called after validation passes. */
+    protected emitSuccessTelemetry(_taskId: string, _output: TOutput, _context: TContext): void;
+    /**
+     * Check lineage strip contract. Called AFTER validation passes.
+     * Receives validated output — safe to treat as TOutput.
+     */
+    protected checkLineageIntegrity(_taskId: string, _output: TOutput): void;
+    /**
+     * Transform output after fetch, before validation.
+     * Used by runners that need to re-inject lineage fields stripped by the adapter.
+     * Receives untrusted data — must NOT assume TOutput shape.
+     */
+    protected postFetchTransform(_taskId: string, _untrustedOutput: unknown): void;
+    /**
+     * Execute the full peer runner lifecycle for a task.
+     *
+     * Pipeline: lease → resolveRunId → buildContext → invoke → poll →
+     *           fetch → validate → succeedTask (abstract)
+     *
+     * Each invocation is independent — no mutable state between run() calls.
+     */
+    run(taskId: string): Promise<PeerRunnerResult<TOutput>>;
+    /**
+     * Emit a telemetry event with the runner's name prefix.
+     * Event type: `{runnerName}_{eventType}`
+     */
+    protected emitEvent(eventType: string, taskId: string, payload: Record<string, unknown>): void;
+    private pollUntilTerminal;
+    /**
+     * Fetch raw output from the runtime adapter.
+     *
+     * Returns `unknown` — the payload is untrusted LLM/runtime output.
+     * Callers MUST validate before treating as TOutput (ERR-001, ERR-005).
+     */
+    private fetchAndParseOutput;
+    /** Resolve artifact IDs from predecessor tasks for lineage tracking. */
+    protected resolveLineageArtifactIds(taskId: string): Promise<{
+        ids: string[];
+        hasRejected: boolean;
+    }>;
+    private resolveStoreRunId;
+    /** Compute a deterministic hash from context references (observability only). */
+    protected static hashContextRefs(refs: readonly string[]): string;
+    private handleLeaseOrPhaseError;
+    private handlePostLeaseError;
+    private handleRuntimeFailure;
+    protected handleValidationError(ctx: {
+        taskId: string;
+        task: TaskRecord;
+        errors: readonly string[];
+        errorCategory?: PDErrorCategory;
+    }): Promise<PeerRunnerResult<TOutput>>;
+    /**
+     * Core retry-or-fail decision.
+     *
+     * Uses try/catch around markTaskFailed/markTaskRetryWait for robustness.
+     * If state manager operations fail, returns storage_unavailable instead of
+     * propagating the exception (ERR-002: graceful degradation with reason).
+     */
+    protected retryOrFail(ctx: FailureContext): Promise<PeerRunnerResult<TOutput>>;
+    private classifyError;
+    private mapRunStatusToErrorCategory;
+    protected sleep(ms: number): Promise<void>;
+}
+//# sourceMappingURL=base-peer-runner.d.ts.map

package/core/dist/runtime-v2/runner/base-peer-runner.d.ts.map

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

package/core/dist/runtime-v2/runner/base-peer-runner.js

@@ -0,0 +1,528 @@
+/**
+ * BasePeerRunner — Abstract base class for all peer runners (PRI-302).
+ *
+ * Extracts the shared lease → buildContext → invoke → poll → fetch →
+ * validate → succeed/fail pipeline from 8 duplicated runner implementations.
+ *
+ * Subclasses implement:
+ *   - permanentErrorCategories (abstract getter)
+ *   - buildContext() — runner-specific context assembly
+ *   - invokeRuntime() — runner-specific LLM invocation
+ *   - validateOutput() — runner-specific output validation
+ *   - succeedTask() — runner-specific artifact commit + task success
+ *
+ * Optional hooks:
+ *   - emitSuccessTelemetry() — runner-specific success telemetry (default: no-op)
+ *   - checkLineageIntegrity() — lineage strip contract check (default: no-op)
+ *
+ * @see docs/adr/0003-peer-agent-state-machine-orchestration.md
+ * @see Linear PRI-302
+ */
+import { PDRuntimeError } from '../error-categories.js';
+import { RunnerPhase } from './runner-phase.js';
+// ── Defaults ─────────────────────────────────────────────────────────────────
+const DEFAULT_PEER_RUNNER_OPTIONS = {
+    pollIntervalMs: 5_000,
+    timeoutMs: 300_000,
+    defaultMaxAttempts: 3,
+    agentId: 'peer-runner',
+};
+function resolvePeerRunnerOptions(options, defaultAgentId) {
+    return {
+        pollIntervalMs: options.pollIntervalMs ?? DEFAULT_PEER_RUNNER_OPTIONS.pollIntervalMs,
+        timeoutMs: options.timeoutMs ?? DEFAULT_PEER_RUNNER_OPTIONS.timeoutMs,
+        defaultMaxAttempts: options.defaultMaxAttempts ?? DEFAULT_PEER_RUNNER_OPTIONS.defaultMaxAttempts,
+        owner: options.owner,
+        runtimeKind: options.runtimeKind,
+        agentId: options.agentId ?? defaultAgentId,
+    };
+}
+// ── BasePeerRunner ───────────────────────────────────────────────────────────
+/**
+ * Abstract base class for peer runners.
+ *
+ * TContext — the type returned by buildContext(). Must include contextHash.
+ * TOutput — the type of the validated LLM output.
+ */
+export class BasePeerRunner {
+    // ── Shared dependencies (protected for subclass access) ──
+    stateManager;
+    runtimeAdapter;
+    eventEmitter;
+    artifactStore;
+    resolvedOptions;
+    config;
+    phase = RunnerPhase.Idle;
+    constructor(deps, options, config) {
+        this.stateManager = deps.stateManager;
+        this.runtimeAdapter = deps.runtimeAdapter;
+        this.eventEmitter = deps.eventEmitter;
+        this.artifactStore = deps.artifactStore;
+        this.config = config;
+        this.resolvedOptions = resolvePeerRunnerOptions(options, config.defaultAgentId);
+    }
+    // ── Observability ──────────────────────────────────────────────────────────
+    /** Current internal phase. For testing/observability only. */
+    get currentPhase() {
+        return this.phase;
+    }
+    // ── Optional hooks (default no-op) ─────────────────────────────────────────
+    /** Emit runner-specific success telemetry. Called after validation passes. */
+    // eslint-disable-next-line @typescript-eslint/class-methods-use-this
+    emitSuccessTelemetry(_taskId, _output, _context) {
+        // default no-op
+    }
+    /**
+     * Check lineage strip contract. Called AFTER validation passes.
+     * Receives validated output — safe to treat as TOutput.
+     */
+    // eslint-disable-next-line @typescript-eslint/class-methods-use-this
+    checkLineageIntegrity(_taskId, _output) {
+        // default no-op
+    }
+    /**
+     * Transform output after fetch, before validation.
+     * Used by runners that need to re-inject lineage fields stripped by the adapter.
+     * Receives untrusted data — must NOT assume TOutput shape.
+     */
+    // eslint-disable-next-line @typescript-eslint/class-methods-use-this
+    postFetchTransform(_taskId, _untrustedOutput) {
+        // default no-op
+    }
+    // ── Template method: full pipeline ─────────────────────────────────────────
+    /**
+     * Execute the full peer runner lifecycle for a task.
+     *
+     * Pipeline: lease → resolveRunId → buildContext → invoke → poll →
+     *           fetch → validate → succeedTask (abstract)
+     *
+     * Each invocation is independent — no mutable state between run() calls.
+     */
+    async run(taskId) {
+        this.phase = RunnerPhase.Idle;
+        // 1. Acquire lease — isolated try/catch so lease_conflict never uses synthetic TaskRecord
+        let leasedTask;
+        try {
+            leasedTask = await this.stateManager.acquireLease({
+                taskId,
+                owner: this.resolvedOptions.owner,
+                runtimeKind: this.resolvedOptions.runtimeKind,
+            });
+        }
+        catch (error) {
+            return await this.handleLeaseOrPhaseError(taskId, error);
+        }
+        // 1b. Validate task kind
+        if (leasedTask.taskKind !== this.config.expectedTaskKind) {
+            this.emitEvent('wrong_task_kind', taskId, {
+                expectedKind: this.config.expectedTaskKind,
+                actualKind: leasedTask.taskKind,
+            });
+            await this.stateManager.markTaskFailed(taskId, 'input_invalid');
+            return {
+                status: 'failed',
+                taskId,
+                errorCategory: 'input_invalid',
+                failureReason: `Task kind must be '${this.config.expectedTaskKind}', got '${leasedTask.taskKind}'`,
+                attemptCount: leasedTask.attemptCount,
+            };
+        }
+        this.emitEvent('task_leased', taskId, {
+            taskKind: this.config.expectedTaskKind,
+            attemptCount: leasedTask.attemptCount,
+        });
+        // All subsequent errors use the real leasedTask — no synthetic TaskRecord allowed
+        try {
+            // 2. Resolve store runId
+            const storeRunId = await this.resolveStoreRunId(taskId);
+            // 3. Build context
+            this.phase = RunnerPhase.BuildingContext;
+            const context = await this.buildContext(taskId);
+            this.emitEvent('context_built', taskId, { contextHash: context.contextHash });
+            // 4. Invoke runtime
+            this.phase = RunnerPhase.Invoking;
+            const runHandle = await this.invokeRuntime(taskId, context);
+            this.emitEvent('run_started', taskId, {
+                runtimeKind: this.resolvedOptions.runtimeKind,
+            });
+            // 5. Poll until terminal
+            this.phase = RunnerPhase.Polling;
+            const finalStatus = await this.pollUntilTerminal(runHandle);
+            // 6. Handle non-success terminal states
+            if (finalStatus.status !== 'succeeded') {
+                return await this.handleRuntimeFailure(taskId, leasedTask, finalStatus);
+            }
+            // 7. Fetch output (returns unknown — untrusted LLM/runtime payload)
+            this.phase = RunnerPhase.FetchingOutput;
+            const untrustedOutput = await this.fetchAndParseOutput(runHandle.runId, taskId);
+            // 7b. Post-fetch transform on untrusted data (e.g., re-inject lineage fields).
+            // Operates on `unknown` — must NOT assume TOutput shape (ERR-001).
+            this.postFetchTransform(taskId, untrustedOutput);
+            // 8. Validate — the trust boundary. Only validated output becomes TOutput.
+            this.phase = RunnerPhase.Validating;
+            const validationResult = await this.validateOutput(untrustedOutput, taskId, context);
+            if (!validationResult.valid) {
+                return await this.handleValidationError({
+                    taskId,
+                    task: leasedTask,
+                    errors: validationResult.errors,
+                    errorCategory: validationResult.errorCategory,
+                });
+            }
+            // Validation passed — safe to treat as TOutput.
+            const output = untrustedOutput;
+            this.emitEvent('output_validated', taskId, {});
+            // 8b. Check lineage integrity (receives validated output)
+            this.checkLineageIntegrity(taskId, output);
+            // 8c. Emit success telemetry (receives validated output)
+            this.emitSuccessTelemetry(taskId, output, context);
+            // 9. Succeed task (abstract — subclass implements commit strategy)
+            const result = await this.succeedTask(taskId, storeRunId, output, leasedTask, context.contextHash, context);
+            if (result.status === 'succeeded') {
+                this.phase = RunnerPhase.Completed;
+            }
+            return result;
+        }
+        catch (error) {
+            // Post-lease errors use retryOrFail with the real leasedTask
+            return await this.handlePostLeaseError(taskId, leasedTask, error);
+        }
+    }
+    // ── Telemetry ──────────────────────────────────────────────────────────────
+    /**
+     * Emit a telemetry event with the runner's name prefix.
+     * Event type: `{runnerName}_{eventType}`
+     */
+    emitEvent(eventType, taskId, payload) {
+        this.eventEmitter.emitTelemetry({
+            eventType: `${this.config.runnerName}_${eventType}`,
+            traceId: taskId,
+            timestamp: new Date().toISOString(),
+            sessionId: this.resolvedOptions.owner,
+            agentId: this.resolvedOptions.agentId,
+            payload,
+        });
+    }
+    // ── Polling ────────────────────────────────────────────────────────────────
+    async pollUntilTerminal(runHandle) {
+        const deadline = Date.now() + this.resolvedOptions.timeoutMs;
+        const terminalStatuses = ['succeeded', 'failed', 'timed_out', 'cancelled'];
+        while (Date.now() < deadline) {
+            const status = await this.runtimeAdapter.pollRun(runHandle.runId);
+            if (terminalStatuses.includes(status.status)) {
+                return status;
+            }
+            await this.sleep(this.resolvedOptions.pollIntervalMs);
+        }
+        // Deadline reached — one final poll before cancelling
+        try {
+            const finalPoll = await this.runtimeAdapter.pollRun(runHandle.runId);
+            if (terminalStatuses.includes(finalPoll.status)) {
+                return finalPoll;
+            }
+        }
+        catch { /* fall through to cancel/timeout */ }
+        // Timeout — cancel gracefully
+        let cancelFailed = false;
+        try {
+            await this.runtimeAdapter.cancelRun(runHandle.runId);
+        }
+        catch (cancelErr) {
+            cancelFailed = true;
+            this.emitEvent('cancel_run_failed', runHandle.runId, {
+                runId: runHandle.runId,
+                errorMessage: cancelErr instanceof Error ? cancelErr.message : String(cancelErr),
+            });
+        }
+        const cancelNote = cancelFailed ? ' (cancelRun also failed)' : '';
+        throw new PDRuntimeError('timeout', `Run ${runHandle.runId} timed out after ${this.resolvedOptions.timeoutMs}ms${cancelNote}`);
+    }
+    // ── Output fetching ────────────────────────────────────────────────────────
+    /**
+     * Fetch raw output from the runtime adapter.
+     *
+     * Returns `unknown` — the payload is untrusted LLM/runtime output.
+     * Callers MUST validate before treating as TOutput (ERR-001, ERR-005).
+     */
+    async fetchAndParseOutput(runId, taskId) {
+        let result;
+        try {
+            result = await this.runtimeAdapter.fetchOutput(runId);
+        }
+        catch (fetchErr) {
+            this.emitEvent('output_extraction_failed', taskId, {
+                runId,
+                stage: 'fetchOutput',
+                errorMessage: fetchErr instanceof Error ? fetchErr.message : String(fetchErr),
+            });
+            throw fetchErr;
+        }
+        if (!result || !result.payload) {
+            this.emitEvent('output_extraction_failed', taskId, {
+                runId,
+                stage: 'payload_missing',
+                errorMessage: `No output available for run ${runId}`,
+            });
+            throw new PDRuntimeError('output_invalid', `No output available for run ${runId}`);
+        }
+        // Structural check: payload must be a non-null object.
+        // This is NOT a type assertion — we still return `unknown`.
+        const { payload } = result;
+        if (typeof payload !== 'object' || payload === null) {
+            this.emitEvent('output_extraction_failed', taskId, {
+                runId,
+                stage: 'payload_not_object',
+                errorMessage: `Output payload is not an object for run ${runId}`,
+            });
+            throw new PDRuntimeError('output_invalid', `Output payload is not an object for run ${runId}`);
+        }
+        return payload;
+    }
+    // ── Lineage resolution ─────────────────────────────────────────────────────
+    /** Resolve artifact IDs from predecessor tasks for lineage tracking. */
+    async resolveLineageArtifactIds(taskId) {
+        const { hydratePITaskRecord } = await import('../internalization/pitask-metadata.js');
+        const task = await this.stateManager.getTask(taskId);
+        if (!task)
+            return { ids: [], hasRejected: false };
+        const piTask = hydratePITaskRecord(task);
+        const deps = piTask?.dependencyTaskIds ?? [];
+        if (deps.length === 0)
+            return { ids: [], hasRejected: false };
+        const lineageIds = [];
+        let hasRejected = false;
+        const results = await Promise.allSettled(deps.map((depId) => this.artifactStore.listBySourceTaskId(depId)));
+        for (const result of results) {
+            if (result.status === 'fulfilled') {
+                for (const artifact of result.value) {
+                    lineageIds.push(artifact.artifactId);
+                }
+            }
+            else {
+                hasRejected = true;
+            }
+        }
+        return { ids: lineageIds, hasRejected };
+    }
+    // ── Store helpers ──────────────────────────────────────────────────────────
+    async resolveStoreRunId(taskId) {
+        const runs = await this.stateManager.getRunsByTask(taskId);
+        const latestRun = runs[runs.length - 1];
+        if (!latestRun) {
+            throw new PDRuntimeError('execution_failed', `No run records found for task ${taskId} after lease acquisition`);
+        }
+        return latestRun.runId;
+    }
+    /** Compute a deterministic hash from context references (observability only). */
+    static hashContextRefs(refs) {
+        if (refs.length === 0)
+            return 'empty';
+        const str = refs.join('|');
+        let hash = 0;
+        for (let i = 0; i < str.length; i++) {
+            hash = (Math.imul(31, hash) + str.charCodeAt(i)) | 0;
+        }
+        return `ctx-${Math.abs(hash).toString(16)}`;
+    }
+    // ── Error handling ─────────────────────────────────────────────────────────
+    async handleLeaseOrPhaseError(taskId, error) {
+        const classified = this.classifyError(error);
+        // lease_conflict is concurrent-access conflict, not a state change.
+        // No mutation methods (markTaskFailed/markTaskRetryWait) are called.
+        if (classified.category === 'lease_conflict') {
+            this.emitEvent('run_failed', taskId, {
+                errorCategory: 'lease_conflict',
+                errorMessage: classified.message,
+            });
+            return {
+                status: 'failed',
+                taskId,
+                errorCategory: 'lease_conflict',
+                failureReason: classified.message,
+                attemptCount: 1,
+            };
+        }
+        // Non-lease errors (e.g., storage_unavailable before lease) must not
+        // use synthetic TaskRecord. Build one with real defaults from options.
+        this.emitEvent('run_failed', taskId, {
+            errorCategory: classified.category,
+            errorMessage: classified.message,
+        });
+        const task = {
+            taskId,
+            taskKind: this.config.expectedTaskKind,
+            status: 'leased',
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+            attemptCount: 1,
+            maxAttempts: this.resolvedOptions.defaultMaxAttempts,
+        };
+        return this.retryOrFail({ taskId, task, errorCategory: classified.category, failureReason: classified.message });
+    }
+    async handlePostLeaseError(taskId, task, error) {
+        const classified = this.classifyError(error);
+        this.emitEvent('run_failed', taskId, {
+            errorCategory: classified.category,
+            errorMessage: classified.message,
+        });
+        return this.retryOrFail({ taskId, task, errorCategory: classified.category, failureReason: classified.message });
+    }
+    async handleRuntimeFailure(taskId, task, runStatus) {
+        const errorCategory = this.mapRunStatusToErrorCategory(runStatus.status, runStatus.reason);
+        this.emitEvent('run_failed', taskId, {
+            runStatus: runStatus.status,
+            errorCategory,
+        });
+        return this.retryOrFail({
+            taskId,
+            task,
+            errorCategory,
+            failureReason: `Runtime execution ended with status: ${runStatus.status}`,
+        });
+    }
+    async handleValidationError(ctx) {
+        const category = ctx.errorCategory ?? 'output_invalid';
+        this.emitEvent('output_invalid', ctx.taskId, {
+            errorCount: ctx.errors.length,
+            errorCategory: category,
+        });
+        return this.retryOrFail({
+            taskId: ctx.taskId,
+            task: ctx.task,
+            errorCategory: category,
+            failureReason: `Validation failed: ${ctx.errors.join('; ')}`,
+        });
+    }
+    // ── Retry/fail state machine ───────────────────────────────────────────────
+    /**
+     * Core retry-or-fail decision.
+     *
+     * Uses try/catch around markTaskFailed/markTaskRetryWait for robustness.
+     * If state manager operations fail, returns storage_unavailable instead of
+     * propagating the exception (ERR-002: graceful degradation with reason).
+     */
+    async retryOrFail(ctx) {
+        // Permanent errors — never retry
+        if (this.permanentErrorCategories.has(ctx.errorCategory)) {
+            try {
+                await this.stateManager.markTaskFailed(ctx.taskId, ctx.errorCategory);
+            }
+            catch (stateErr) {
+                this.emitEvent('mark_failed_error', ctx.taskId, {
+                    errorCategory: 'storage_unavailable',
+                    attemptCount: ctx.task.attemptCount,
+                    errorMessage: stateErr instanceof Error ? stateErr.message : String(stateErr),
+                });
+                return {
+                    status: 'failed',
+                    taskId: ctx.taskId,
+                    errorCategory: 'storage_unavailable',
+                    failureReason: `State manager error: ${ctx.failureReason}`,
+                    attemptCount: ctx.task.attemptCount,
+                };
+            }
+            this.emitEvent('task_failed', ctx.taskId, {
+                errorCategory: ctx.errorCategory,
+                attemptCount: ctx.task.attemptCount,
+                failureReason: ctx.failureReason,
+            });
+            this.phase = RunnerPhase.Failed;
+            return {
+                status: 'failed',
+                taskId: ctx.taskId,
+                errorCategory: ctx.errorCategory,
+                failureReason: ctx.failureReason,
+                attemptCount: ctx.task.attemptCount,
+            };
+        }
+        // Retry policy check
+        const shouldRetry = this.stateManager.getRetryPolicy().shouldRetry(ctx.task);
+        if (shouldRetry) {
+            try {
+                await this.stateManager.markTaskRetryWait(ctx.taskId, ctx.errorCategory);
+            }
+            catch (stateErr) {
+                this.emitEvent('mark_retry_error', ctx.taskId, {
+                    errorCategory: 'storage_unavailable',
+                    attemptCount: ctx.task.attemptCount,
+                    errorMessage: stateErr instanceof Error ? stateErr.message : String(stateErr),
+                });
+                return {
+                    status: 'failed',
+                    taskId: ctx.taskId,
+                    errorCategory: 'storage_unavailable',
+                    failureReason: `State manager error: ${ctx.failureReason}`,
+                    attemptCount: ctx.task.attemptCount,
+                };
+            }
+            this.emitEvent('task_retried', ctx.taskId, {
+                errorCategory: ctx.errorCategory,
+                attemptCount: ctx.task.attemptCount,
+            });
+            this.phase = RunnerPhase.RetryWaiting;
+            return {
+                status: 'retried',
+                taskId: ctx.taskId,
+                errorCategory: ctx.errorCategory,
+                failureReason: ctx.failureReason,
+                attemptCount: ctx.task.attemptCount,
+            };
+        }
+        // Max attempts exceeded
+        try {
+            await this.stateManager.markTaskFailed(ctx.taskId, 'max_attempts_exceeded');
+        }
+        catch (stateErr) {
+            this.emitEvent('mark_failed_error', ctx.taskId, {
+                errorCategory: 'storage_unavailable',
+                attemptCount: ctx.task.attemptCount,
+                errorMessage: stateErr instanceof Error ? stateErr.message : String(stateErr),
+            });
+            return {
+                status: 'failed',
+                taskId: ctx.taskId,
+                errorCategory: 'storage_unavailable',
+                failureReason: `State manager error: ${ctx.failureReason}`,
+                attemptCount: ctx.task.attemptCount,
+            };
+        }
+        this.emitEvent('task_failed', ctx.taskId, {
+            errorCategory: 'max_attempts_exceeded',
+            attemptCount: ctx.task.attemptCount,
+            failureReason: `Max attempts exceeded: ${ctx.failureReason}`,
+        });
+        this.phase = RunnerPhase.Failed;
+        return {
+            status: 'failed',
+            taskId: ctx.taskId,
+            errorCategory: 'max_attempts_exceeded',
+            failureReason: `Max attempts exceeded: ${ctx.failureReason}`,
+            attemptCount: ctx.task.attemptCount,
+        };
+    }
+    // ── Error classification ──────────────────────────────────────────────────
+    // eslint-disable-next-line @typescript-eslint/class-methods-use-this
+    classifyError(error) {
+        if (error instanceof PDRuntimeError) {
+            return { category: error.category, message: error.message };
+        }
+        if (error instanceof Error) {
+            return { category: 'execution_failed', message: error.message };
+        }
+        return { category: 'execution_failed', message: String(error) };
+    }
+    // eslint-disable-next-line @typescript-eslint/class-methods-use-this
+    mapRunStatusToErrorCategory(status, _reason) {
+        switch (status) {
+            case 'failed': return 'execution_failed';
+            case 'timed_out': return 'timeout';
+            case 'cancelled': return 'cancelled';
+            default: return 'execution_failed';
+        }
+    }
+    // eslint-disable-next-line @typescript-eslint/class-methods-use-this
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+//# sourceMappingURL=base-peer-runner.js.map