@lsctech/polaris 0.1.0

package/dist/loop/abort.js

@@ -0,0 +1,188 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runLoopAbort = runLoopAbort;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_crypto_1 = require("node:crypto");
+const checkpoint_js_1 = require("./checkpoint.js");
+const ledger_js_1 = require("./ledger.js");
+function normalizeRunType(sessionType) {
+    return sessionType === "analyze" ? "analyze" : "implement";
+}
+function ledgerLastCommit(state) {
+    return state.last_commit && state.last_commit.length > 0 ? state.last_commit : null;
+}
+function appendBlockedLedgerEvent(repoRoot, state, childId, reason) {
+    new ledger_js_1.LedgerWriter((0, node_path_1.join)(repoRoot, ledger_js_1.DEFAULT_LEDGER_PATH)).append({
+        schema_version: 1,
+        event_id: (0, node_crypto_1.randomUUID)(),
+        event: "run-blocked",
+        run_id: state.run_id,
+        run_type: normalizeRunType(state.session_type),
+        cluster_id: state.cluster_id,
+        issue_id: childId || null,
+        branch: state.branch ?? "unknown",
+        status: "blocked",
+        completed_children: state.completed_children,
+        open_children: state.open_children,
+        next_child: state.next_open_child,
+        last_commit: ledgerLastCommit(state),
+        pr_url: null,
+        timestamp: new Date().toISOString(),
+        blocker: {
+            summary: reason,
+            unblock_condition: `Resolve blocker then run: npm run polaris -- loop run ${state.cluster_id}`,
+        },
+    });
+}
+/**
+ * Detect whether the current state has a stuck dispatch with no worker activity.
+ *
+ * Intentionally does NOT call getMachineState(). When a prior `loop abort` set
+ * state.status to "blocked" but failed to clear active_child (the pre-fix
+ * behavior), getMachineState() would short-circuit to "blocked" before reaching
+ * the dispatch-boundary epoch logic, making re-abort appear non-stale.  Instead
+ * we inspect the raw dispatch signals directly.
+ *
+ * A dispatch is eligible for stale reset when ALL of the following are true:
+ *   • active_child is set
+ *   • dispatch evidence exists (step_cursor is "dispatch", dispatch_boundary
+ *     records the child, or the dispatch_record is still "dispatched")
+ *   • the dispatch_record has not already reached a terminal state (failed/completed)
+ *   • no heartbeat exists (worker never acknowledged)
+ *   • the expected result file is absent (worker never wrote output)
+ */
+function detectStaleDispatch(state, repoRoot) {
+    if (!state.active_child || state.active_child === "") {
+        return { isStale: false, hasHeartbeat: false, hasResultFile: false };
+    }
+    const activeChild = state.active_child;
+    const dr = state.open_children_meta?.[activeChild]?.dispatch_record;
+    // A dispatch record that already reached a terminal state has been handled.
+    if (dr && (dr.status === "failed" || dr.status === "completed")) {
+        return { isStale: false, hasHeartbeat: false, hasResultFile: false };
+    }
+    // Require at least one dispatch signal for this child.
+    const hasDispatchEvidence = state.step_cursor === "dispatch" ||
+        state.dispatch_boundary?.last_dispatched_child === activeChild ||
+        dr?.status === "dispatched";
+    if (!hasDispatchEvidence) {
+        return { isStale: false, hasHeartbeat: false, hasResultFile: false };
+    }
+    const hasHeartbeat = !!(dr?.last_heartbeat_at);
+    let hasResultFile = false;
+    if (dr?.expected_result_path) {
+        const resultPath = (0, node_path_1.isAbsolute)(dr.expected_result_path)
+            ? dr.expected_result_path
+            : (0, node_path_1.join)(repoRoot, dr.expected_result_path);
+        hasResultFile = (0, node_fs_1.existsSync)(resultPath);
+    }
+    // Only treat as stale when the worker left no evidence at all.
+    // If a heartbeat exists the worker may still be running; if a result file
+    // exists the worker completed and must be checkpointed before clearing.
+    return {
+        isStale: !hasHeartbeat && !hasResultFile,
+        hasHeartbeat,
+        hasResultFile,
+        abortedDispatchId: dr?.dispatch_id,
+    };
+}
+function runLoopAbort(options) {
+    const { reason, repoRoot } = options;
+    const stateFile = options.stateFile ?? (0, node_path_1.join)(repoRoot, ".polaris", "runs", "current-state.json");
+    let state;
+    try {
+        const raw = (0, checkpoint_js_1.readState)(stateFile);
+        const errors = (0, checkpoint_js_1.validateState)(raw);
+        if (errors.length > 0) {
+            process.stderr.write(`current-state.json invalid:\n${errors.join("\n")}\n`);
+            process.exit(1);
+        }
+        state = raw;
+    }
+    catch (err) {
+        process.stderr.write(`Error: cannot read state file ${stateFile}: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(1);
+    }
+    const timestamp = new Date().toISOString();
+    const staleInfo = detectStaleDispatch(state, repoRoot);
+    let updatedState;
+    let effectiveChildId;
+    if (staleInfo.isStale) {
+        // Stale dispatch: clear active_child, balance dispatch_boundary epochs, and
+        // mark the old dispatch record as failed so fresh dispatch can proceed after
+        // the operator runs `polaris loop resume` to exit the blocked state.
+        const stuckChildId = state.active_child;
+        effectiveChildId = options.childId ?? stuckChildId ?? "";
+        const existingMeta = state.open_children_meta ?? {};
+        const childMeta = existingMeta[stuckChildId] ?? {};
+        const oldDr = childMeta.dispatch_record;
+        updatedState = {
+            ...state,
+            active_child: "",
+            step_cursor: state.step_cursor === "dispatch" ? null : state.step_cursor,
+            dispatch_boundary: state.dispatch_boundary
+                ? {
+                    ...state.dispatch_boundary,
+                    // Balance epochs so the machine returns to checkpointed/idle,
+                    // allowing a fresh dispatch once the blocked status is cleared.
+                    continue_epoch: state.dispatch_boundary.dispatch_epoch,
+                }
+                : state.dispatch_boundary,
+            status: "blocked",
+            blocker: {
+                reason,
+                child_id: effectiveChildId,
+                timestamp,
+                resolved: false,
+            },
+            open_children_meta: {
+                ...existingMeta,
+                [stuckChildId]: {
+                    ...childMeta,
+                    ...(oldDr
+                        ? { dispatch_record: { ...oldDr, status: "failed", runtime_state: "failed" } }
+                        : {}),
+                },
+            },
+        };
+    }
+    else {
+        effectiveChildId = options.childId ?? state.active_child ?? "";
+        updatedState = {
+            ...state,
+            status: "blocked",
+            blocker: {
+                reason,
+                child_id: effectiveChildId,
+                timestamp,
+                resolved: false,
+            },
+        };
+    }
+    (0, checkpoint_js_1.writeStateAtomic)(stateFile, updatedState);
+    appendBlockedLedgerEvent(repoRoot, updatedState, effectiveChildId, reason);
+    const artifactDir = state.artifact_dir ?? (0, node_path_1.join)(repoRoot, ".taskchain_artifacts", "polaris-run");
+    const telemetryFile = (0, node_path_1.join)(artifactDir, "runs", state.run_id, "telemetry.jsonl");
+    if (staleInfo.isStale) {
+        (0, checkpoint_js_1.appendStaleDispatchAbortedEvent)(telemetryFile, {
+            event: "stale-dispatch-aborted",
+            run_id: state.run_id,
+            child_id: state.active_child,
+            reason,
+            aborted_dispatch_id: staleInfo.abortedDispatchId,
+            had_heartbeat: staleInfo.hasHeartbeat,
+            had_result_file: staleInfo.hasResultFile,
+            timestamp,
+        });
+    }
+    (0, checkpoint_js_1.appendAbortEvent)(telemetryFile, {
+        event: "loop-aborted",
+        run_id: state.run_id,
+        child_id: effectiveChildId,
+        reason,
+        timestamp,
+    });
+    process.stderr.write(`Loop aborted. Reason: ${reason}. Resolve blocker then run: npm run polaris -- loop run ${updatedState.cluster_id}\n`);
+    process.exit(0);
+}

package/dist/loop/abort.test.js

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+const node_child_process_1 = require("node:child_process");
+const abort_js_1 = require("./abort.js");
+function makeTestDir() {
+    const dir = (0, node_path_1.join)((0, node_os_1.tmpdir)(), `polaris-abort-test-${Date.now()}`);
+    (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    (0, node_child_process_1.execFileSync)("git", ["init"], { cwd: dir });
+    (0, node_child_process_1.execFileSync)("git", ["config", "user.email", "test@test.com"], { cwd: dir });
+    (0, node_child_process_1.execFileSync)("git", ["config", "user.name", "Test"], { cwd: dir });
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(dir, "README.md"), "test\n");
+    (0, node_child_process_1.execFileSync)("git", ["add", "."], { cwd: dir });
+    (0, node_child_process_1.execFileSync)("git", ["commit", "-m", "init"], { cwd: dir });
+    return dir;
+}
+function writeState(dir, state) {
+    const stateFile = (0, node_path_1.join)(dir, ".polaris", "runs", "current-state.json");
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(dir, ".polaris", "runs"), { recursive: true });
+    (0, node_fs_1.writeFileSync)(stateFile, JSON.stringify(state, null, 2));
+    return stateFile;
+}
+const baseState = {
+    schema_version: "1.0",
+    run_id: "pol-5-session-1",
+    cluster_id: "POL-5",
+    session_type: "implement",
+    active_child: "POL-26",
+    completed_children: ["POL-23"],
+    open_children: ["POL-26", "POL-27"],
+    step_cursor: "implement-child",
+    context_budget: { children_completed: 1, max_children_per_session: 3 },
+    status: "running",
+    next_open_child: "POL-26",
+};
+(0, vitest_1.describe)("runLoopAbort", () => {
+    let testDir;
+    (0, vitest_1.beforeEach)(() => {
+        testDir = makeTestDir();
+    });
+    (0, vitest_1.afterEach)(() => {
+        (0, node_fs_1.rmSync)(testDir, { recursive: true, force: true });
+    });
+    (0, vitest_1.it)("writes blocked status and blocker record to current-state.json", () => {
+        const stateFile = writeState(testDir, baseState);
+        const exitSpy = vitest_1.vi.spyOn(process, "exit").mockImplementation(() => {
+            throw new Error("process.exit called");
+        });
+        vitest_1.vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+        try {
+            (0, vitest_1.expect)(() => (0, abort_js_1.runLoopAbort)({ reason: "test blocker", repoRoot: testDir, stateFile })).toThrow("process.exit called");
+        }
+        finally {
+            exitSpy.mockRestore();
+            vitest_1.vi.restoreAllMocks();
+        }
+        const saved = JSON.parse((0, node_fs_1.readFileSync)(stateFile, "utf-8"));
+        (0, vitest_1.expect)(saved.status).toBe("blocked");
+        (0, vitest_1.expect)(saved.blocker.reason).toBe("test blocker");
+        (0, vitest_1.expect)(saved.blocker.child_id).toBe("POL-26");
+        (0, vitest_1.expect)(saved.blocker.resolved).toBe(false);
+        (0, vitest_1.expect)(saved.blocker.timestamp).toBeTruthy();
+    });
+    (0, vitest_1.it)("uses --child override for blocker child_id", () => {
+        const stateFile = writeState(testDir, baseState);
+        const exitSpy = vitest_1.vi.spyOn(process, "exit").mockImplementation(() => {
+            throw new Error("process.exit called");
+        });
+        vitest_1.vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+        try {
+            (0, vitest_1.expect)(() => (0, abort_js_1.runLoopAbort)({
+                reason: "dependency not done",
+                childId: "POL-27",
+                repoRoot: testDir,
+                stateFile,
+            })).toThrow("process.exit called");
+        }
+        finally {
+            exitSpy.mockRestore();
+            vitest_1.vi.restoreAllMocks();
+        }
+        const saved = JSON.parse((0, node_fs_1.readFileSync)(stateFile, "utf-8"));
+        (0, vitest_1.expect)(saved.blocker.child_id).toBe("POL-27");
+    });
+    (0, vitest_1.it)("appends loop-aborted JSONL event to telemetry file", () => {
+        const artifactDir = (0, node_path_1.join)(testDir, ".taskchain_artifacts", "bootstrap-run");
+        const telemetryFile = (0, node_path_1.join)(artifactDir, "runs", "pol-5-session-1", "telemetry.jsonl");
+        const stateFile = writeState(testDir, baseState);
+        const exitSpy = vitest_1.vi.spyOn(process, "exit").mockImplementation(() => {
+            throw new Error("process.exit called");
+        });
+        vitest_1.vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+        try {
+            (0, vitest_1.expect)(() => (0, abort_js_1.runLoopAbort)({ reason: "test blocker", repoRoot: testDir, stateFile })).toThrow("process.exit called");
+        }
+        finally {
+            exitSpy.mockRestore();
+            vitest_1.vi.restoreAllMocks();
+        }
+        const lines = (0, node_fs_1.readFileSync)(telemetryFile, "utf-8").trim().split("\n");
+        const event = JSON.parse(lines[lines.length - 1]);
+        (0, vitest_1.expect)(event.event).toBe("loop-aborted");
+        (0, vitest_1.expect)(event.run_id).toBe("pol-5-session-1");
+        (0, vitest_1.expect)(event.reason).toBe("test blocker");
+    });
+    (0, vitest_1.it)("prints abort message to stderr and exits 1", () => {
+        const stateFile = writeState(testDir, baseState);
+        const stderrMessages = [];
+        const exitSpy = vitest_1.vi.spyOn(process, "exit").mockImplementation(() => {
+            throw new Error("process.exit called");
+        });
+        const stderrSpy = vitest_1.vi
+            .spyOn(process.stderr, "write")
+            .mockImplementation((msg) => {
+            stderrMessages.push(String(msg));
+            return true;
+        });
+        try {
+            (0, vitest_1.expect)(() => (0, abort_js_1.runLoopAbort)({ reason: "blocked by missing dep", repoRoot: testDir, stateFile })).toThrow("process.exit called");
+            (0, vitest_1.expect)(exitSpy).toHaveBeenCalledWith(1);
+            (0, vitest_1.expect)(stderrMessages.some((m) => m.includes("Loop aborted"))).toBe(true);
+            (0, vitest_1.expect)(stderrMessages.some((m) => m.includes("blocked by missing dep"))).toBe(true);
+            (0, vitest_1.expect)(stderrMessages.some((m) => m.includes("polaris loop resume"))).toBe(true);
+        }
+        finally {
+            exitSpy.mockRestore();
+            stderrSpy.mockRestore();
+        }
+    });
+    (0, vitest_1.it)("exits with error when state file is missing", () => {
+        const exitSpy = vitest_1.vi.spyOn(process, "exit").mockImplementation(() => {
+            throw new Error("process.exit called");
+        });
+        const stderrSpy = vitest_1.vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+        try {
+            (0, vitest_1.expect)(() => (0, abort_js_1.runLoopAbort)({
+                reason: "test",
+                repoRoot: testDir,
+                stateFile: (0, node_path_1.join)(testDir, "nonexistent.json"),
+            })).toThrow("process.exit called");
+            (0, vitest_1.expect)(stderrSpy).toHaveBeenCalledWith(vitest_1.expect.stringContaining("cannot read state file"));
+        }
+        finally {
+            exitSpy.mockRestore();
+            stderrSpy.mockRestore();
+        }
+    });
+});

package/dist/loop/adapters/__tests__/terminal-cli.test.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const terminal_cli_js_1 = require("../terminal-cli.js");
+const registry_js_1 = require("../registry.js");
+const MOCK_PACKET = {
+    schema_version: "1.0",
+    run_id: "run-test-0001",
+    cluster_id: "POL-5",
+    active_child: "POL-14",
+    state_file: "/tmp/polaris-test/current-state.json",
+    telemetry_file: "/tmp/polaris-test/telemetry.jsonl",
+};
+(0, vitest_1.describe)("TerminalCliAdapter", () => {
+    (0, vitest_1.describe)("provider resolution", () => {
+        (0, vitest_1.it)("throws for unknown provider with list of available ones", async () => {
+            const adapter = new terminal_cli_js_1.TerminalCliAdapter({
+                adapter: "terminal-cli",
+                providers: {
+                    codex: { command: "codex" },
+                    gemini: { command: "gemini" },
+                },
+            });
+            await (0, vitest_1.expect)(adapter.dispatch(MOCK_PACKET, { provider: "windsurf", dryRun: true })).rejects.toThrow(/Unknown provider "windsurf".*codex.*gemini/);
+        });
+        (0, vitest_1.it)("includes helpful message when no providers are configured", async () => {
+            const adapter = new terminal_cli_js_1.TerminalCliAdapter({
+                adapter: "terminal-cli",
+                providers: {},
+            });
+            await (0, vitest_1.expect)(adapter.dispatch(MOCK_PACKET, { provider: "codex", dryRun: true })).rejects.toThrow(/No providers configured/);
+        });
+    });
+    (0, vitest_1.describe)("command expansion", () => {
+        (0, vitest_1.it)("expands $ENV_VAR references in command", async () => {
+            process.env.POLARIS_AGENT = "/usr/local/bin/myagent";
+            const adapter = new terminal_cli_js_1.TerminalCliAdapter({
+                adapter: "terminal-cli",
+                providers: { custom: { command: "$POLARIS_AGENT", args: ["{{active_child}}"] } },
+            });
+            const result = await adapter.dispatch(MOCK_PACKET, { provider: "custom", dryRun: true });
+            (0, vitest_1.expect)(result.command_run).toContain("/usr/local/bin/myagent");
+            (0, vitest_1.expect)(result.command_run).toContain("POL-14");
+            delete process.env.POLARIS_AGENT;
+        });
+        (0, vitest_1.it)("throws when command expands to an unset $VAR", async () => {
+            delete process.env.POLARIS_MISSING_VAR;
+            const adapter = new terminal_cli_js_1.TerminalCliAdapter({
+                adapter: "terminal-cli",
+                providers: { custom: { command: "$POLARIS_MISSING_VAR" } },
+            });
+            await (0, vitest_1.expect)(adapter.dispatch(MOCK_PACKET, { provider: "custom", dryRun: true })).rejects.toThrow(/unset environment variable|empty string/);
+        });
+        (0, vitest_1.it)("substitutes {{template}} variables in args", async () => {
+            const adapter = new terminal_cli_js_1.TerminalCliAdapter({
+                adapter: "terminal-cli",
+                providers: {
+                    codex: {
+                        command: "echo",
+                        args: ["child={{active_child}}", "run={{run_id}}"],
+                    },
+                },
+            });
+            const result = await adapter.dispatch(MOCK_PACKET, { provider: "codex", dryRun: true });
+            (0, vitest_1.expect)(result.command_run).toContain("child=POL-14");
+            (0, vitest_1.expect)(result.command_run).toContain("run=run-test-0001");
+        });
+    });
+    (0, vitest_1.describe)("dry-run", () => {
+        (0, vitest_1.it)("returns exit_code 0 and summary [dry-run] without spawning a process", async () => {
+            const adapter = new terminal_cli_js_1.TerminalCliAdapter({
+                adapter: "terminal-cli",
+                providers: {
+                    codex: { command: "does-not-exist-binary", args: ["--child", "{{active_child}}"] },
+                },
+            });
+            const result = await adapter.dispatch(MOCK_PACKET, { provider: "codex", dryRun: true });
+            (0, vitest_1.expect)(result.exit_code).toBe(0);
+            (0, vitest_1.expect)(result.summary).toBe("[dry-run]");
+            (0, vitest_1.expect)(result.provider_used).toBe("codex");
+        });
+    });
+});
+(0, vitest_1.describe)("registry", () => {
+    (0, vitest_1.it)("createAdapter returns TerminalCliAdapter for terminal-cli", () => {
+        const adapter = (0, registry_js_1.createAdapter)("terminal-cli", { adapter: "terminal-cli", providers: {} });
+        (0, vitest_1.expect)(adapter.name).toBe("terminal-cli");
+    });
+    (0, vitest_1.it)("createAdapter throws for unknown adapter", () => {
+        (0, vitest_1.expect)(() => (0, registry_js_1.createAdapter)("agent-subtask", { adapter: "agent-subtask", providers: {} })).toThrow(/Unknown adapter/);
+    });
+});

package/dist/loop/adapters/agent-subtask.js

@@ -0,0 +1,137 @@
+"use strict";
+/**
+ * Agent-subtask adapter — dispatches a worker as a native agent subtask.
+ *
+ * When the packet is a compiled WorkerPacket (schema_version === '2.0') the
+ * adapter uses pre-compiled instructions from `packet.instructions` rather
+ * than generating generic instructions from packet metadata. This eliminates
+ * per-dispatch skill re-ingestion and reduces worker token burn.
+ *
+ * The adapter also includes the lifecycle teardown contract in every prompt so
+ * the worker session terminates immediately after returning compact JSON.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentSubtaskAdapter = void 0;
+const worker_packet_js_1 = require("../worker-packet.js");
+const worker_instructions_js_1 = require("./worker-instructions.js");
+function defaultDispatcher() {
+    const host = globalThis;
+    return host.__POLARIS_AGENT_SUBTASK_DISPATCH__;
+}
+function normalizeSummary(value) {
+    return typeof value === "string" ? value : JSON.stringify(value);
+}
+function validateSummary(summary, packet) {
+    try {
+        const parsed = JSON.parse(summary);
+        // For finalize/preflight workers active_child is "" — skip child_id check.
+        if (packet.active_child) {
+            const returnedChild = parsed.child_id ?? parsed.active_child;
+            if (returnedChild !== packet.active_child) {
+                return `Native subtask returned mismatched child_id: expected ${packet.active_child}, got ${String(returnedChild)}`;
+            }
+        }
+        if (!["done", "blocked", "error", "success", "failure"].includes(String(parsed.status))) {
+            return `Native subtask returned invalid status: ${String(parsed.status)}`;
+        }
+        return null;
+    }
+    catch {
+        return "Native subtask returned malformed compact JSON";
+    }
+}
+class AgentSubtaskAdapter {
+    dispatcher;
+    name = 'agent-subtask';
+    constructor(dispatcher = defaultDispatcher()) {
+        this.dispatcher = dispatcher;
+    }
+    async dispatch(packet, options) {
+        const label = packet.active_child || ((0, worker_packet_js_1.isWorkerPacket)(packet) ? packet.worker_role : 'worker');
+        const commandRun = `agent-subtask:${label}`;
+        const provider = options.provider || "agent-subtask";
+        if (!this.dispatcher) {
+            const error = "Native ephemeral agent subtask dispatch is unavailable in this host environment. " +
+                "Use manual handoff or a configured terminal-cli adapter.";
+            return {
+                exit_code: 1,
+                pre_dispatch_failure: true,
+                provider_used: provider,
+                command_run: commandRun,
+                summary: error,
+                stderr: error,
+            };
+        }
+        if ((0, worker_packet_js_1.isWorkerPacket)(packet) && packet.worker_role === 'impl') {
+            const allowed = Array.isArray(packet.instructions?.allowed_scope) ? packet.instructions.allowed_scope : [];
+            if (allowed.length === 0) {
+                const blockedMsg = `Worker blocked: impl packet for ${packet.active_child} has empty allowed_scope. Foreman must provide scope or approve override.`;
+                return {
+                    exit_code: 1,
+                    provider_used: provider,
+                    command_run: commandRun,
+                    summary: JSON.stringify({
+                        child_id: packet.active_child,
+                        status: "blocked",
+                        validation_summary: blockedMsg,
+                        next_action: "escalate",
+                        warnings: ["empty-allowed-scope"],
+                    }),
+                    stderr: blockedMsg,
+                };
+            }
+        }
+        if (options.dryRun) {
+            const childId = packet.active_child || 'no-child';
+            return {
+                exit_code: 0,
+                provider_used: provider,
+                command_run: commandRun,
+                summary: JSON.stringify({
+                    child_id: childId,
+                    status: "done",
+                    validation_summary: "dry-run: native ephemeral agent subtask dispatch not executed",
+                    next_action: "resume-parent",
+                    warnings: ["dry-run"],
+                }),
+            };
+        }
+        const instructions = (0, worker_instructions_js_1.buildWorkerInstructions)(packet);
+        const returnContract = (0, worker_instructions_js_1.returnContractFor)(packet);
+        try {
+            const rawSummary = await this.dispatcher({
+                packet,
+                instructions,
+                returnContract,
+            });
+            const summary = normalizeSummary(rawSummary);
+            const validationError = validateSummary(summary, packet);
+            if (validationError) {
+                return {
+                    exit_code: 1,
+                    provider_used: provider,
+                    command_run: commandRun,
+                    summary: validationError,
+                    stderr: validationError,
+                };
+            }
+            return {
+                exit_code: 0,
+                provider_used: provider,
+                command_run: commandRun,
+                summary,
+            };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+                exit_code: 1,
+                provider_used: provider,
+                command_run: commandRun,
+                summary: `Native ephemeral agent subtask dispatch failed: ${msg}`,
+                stderr: msg,
+            };
+        }
+    }
+}
+exports.AgentSubtaskAdapter = AgentSubtaskAdapter;