@longtable/cli 0.1.54 → 0.1.56

package/dist/panel-runtime.js

@@ -0,0 +1,525 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+function nowIso() {
+    return new Date().toISOString();
+}
+function createId(prefix) {
+    return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+function commandAvailable(command) {
+    try {
+        execFileSync("sh", ["-lc", `command -v ${command}`], { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+function appendDiagnostic(existing, diagnostic) {
+    return existing.includes(diagnostic) ? existing : [...existing, diagnostic];
+}
+function panelRunsDirectory(workingDirectory) {
+    return join(workingDirectory, ".longtable", "panel-runs");
+}
+export function panelWorkerRunDirectory(workingDirectory, runId) {
+    return join(panelRunsDirectory(workingDirectory), runId);
+}
+export function panelWorkerRunPath(workingDirectory, runId) {
+    return join(panelWorkerRunDirectory(workingDirectory, runId), "run.json");
+}
+async function writeJsonAtomic(path, value) {
+    await mkdir(dirname(path), { recursive: true });
+    const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+    await writeFile(tempPath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+    await rename(tempPath, path);
+}
+function workerTaskPrompt(fallback, worker) {
+    return [
+        "LongTable native panel worker",
+        "",
+        `Role: ${worker.label} (${worker.role})`,
+        `Invocation: ${fallback.invocationRecord.id}`,
+        `Panel plan: ${fallback.plan.id}`,
+        "",
+        "Instructions:",
+        "- Work read-only unless the researcher explicitly asked for drafting.",
+        "- Do not expose or persist hidden reasoning, private tool traces, or chain-of-thought.",
+        "- Persist only the structured final role output to the result path below.",
+        "- Return JSON matching this shape:",
+        "  {\"role\":\"...\",\"label\":\"...\",\"status\":\"completed\",\"summary\":\"...\",\"claims\":[],\"objections\":[],\"openQuestions\":[],\"evidenceRefs\":[],\"error\":\"\"}",
+        "",
+        `Result path: ${worker.resultPath}`,
+        `Log path: ${worker.logPath}`,
+        "",
+        "Research object:",
+        fallback.plan.prompt
+    ].join("\n");
+}
+const PANEL_WORKER_OUTPUT_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: ["role", "label", "status", "summary", "claims", "objections", "openQuestions", "evidenceRefs", "error"],
+    properties: {
+        role: { type: "string" },
+        label: { type: "string" },
+        status: { enum: ["completed", "blocked", "error"] },
+        summary: { type: "string" },
+        claims: { type: "array", items: { type: "string" } },
+        objections: { type: "array", items: { type: "string" } },
+        openQuestions: { type: "array", items: { type: "string" } },
+        evidenceRefs: { type: "array", items: { type: "string" } },
+        error: { type: "string" }
+    }
+};
+function launcherScript(run, worker) {
+    const role = shellQuote(worker.role);
+    const label = shellQuote(worker.label);
+    const stdoutPath = `${worker.resultPath}.stdout`;
+    return [
+        "#!/usr/bin/env bash",
+        "set +e",
+        `printf 'started_at=%s\\n' "$(date -u +'%Y-%m-%dT%H:%M:%SZ')" > ${shellQuote(worker.logPath)}`,
+        `if [ -f ${shellQuote(run.stopFilePath)} ]; then`,
+        `  printf 'stop_requested_before_launch\\n' >> ${shellQuote(worker.logPath)}`,
+        "  exit 0",
+        "fi",
+        [
+            "codex exec",
+            "-s read-only",
+            `-C ${shellQuote(run.workingDirectory)}`,
+            "--skip-git-repo-check",
+            `--output-schema ${shellQuote(run.outputSchemaPath)}`,
+            "-",
+            `< ${shellQuote(worker.taskPath)}`,
+            `> ${shellQuote(stdoutPath)} 2>/dev/null`
+        ].join(" "),
+        "code=$?",
+        `if [ -s ${shellQuote(stdoutPath)} ]; then`,
+        `  node -e 'const fs=require("fs"); const [stdoutPath,resultPath]=process.argv.slice(1); const parsed=JSON.parse(fs.readFileSync(stdoutPath,"utf8").trim()); fs.writeFileSync(resultPath, JSON.stringify(parsed, null, 2)+"\\n");' ${shellQuote(stdoutPath)} ${shellQuote(worker.resultPath)}`,
+        "  parse_code=$?",
+        `  rm -f ${shellQuote(stdoutPath)}`,
+        `  if [ "$parse_code" -ne 0 ]; then code=1; fi`,
+        "fi",
+        `printf '{"exitCode":%s,"completedAt":"%s"}\\n' "$code" "$(date -u +'%Y-%m-%dT%H:%M:%SZ')" > ${shellQuote(worker.exitCodePath ?? `${worker.resultPath}.exit.json`)}`,
+        `printf 'exit_code=%s\\n' "$code" >> ${shellQuote(worker.logPath)}`,
+        `if [ "$code" -ne 0 ] && [ ! -s ${shellQuote(worker.resultPath)} ]; then`,
+        `  node -e 'const fs=require("fs"); const [path,role,label,code]=process.argv.slice(1); fs.writeFileSync(path, JSON.stringify({role,label,status:"error",summary:"",claims:[],objections:[],openQuestions:[],evidenceRefs:[],error:\`codex exec exited ${"${code}"}\`}, null, 2)+"\\n");' ${shellQuote(worker.resultPath)} ${role} ${label} "$code"`,
+        "fi",
+        "exit $code",
+        ""
+    ].join("\n");
+}
+function plannedWorkerStatus(runStatus) {
+    return runStatus === "planned" ? "pending" : "running";
+}
+export async function createPanelWorkerRun(options) {
+    const createdAt = nowIso();
+    const runId = createId("panel_run");
+    const runDirectory = panelWorkerRunDirectory(options.workingDirectory, runId);
+    const taskDirectory = join(runDirectory, "tasks");
+    const resultDirectory = join(runDirectory, "results");
+    const logDirectory = join(runDirectory, "logs");
+    const launcherDirectory = join(runDirectory, "launchers");
+    await mkdir(taskDirectory, { recursive: true });
+    await mkdir(resultDirectory, { recursive: true });
+    await mkdir(logDirectory, { recursive: true });
+    await mkdir(launcherDirectory, { recursive: true });
+    const runStatus = options.initialStatus ?? "planned";
+    const workers = options.fallback.plan.members.map((member, index) => {
+        const workerId = `worker-${index + 1}-${member.role}`;
+        return {
+            id: workerId,
+            role: member.role,
+            label: member.label,
+            required: member.required,
+            status: plannedWorkerStatus(runStatus),
+            taskPath: join(taskDirectory, `${workerId}.md`),
+            resultPath: join(resultDirectory, `${workerId}.json`),
+            logPath: join(logDirectory, `${workerId}.log`),
+            launcherPath: join(launcherDirectory, `${workerId}.sh`),
+            exitCodePath: join(resultDirectory, `${workerId}.exit.json`),
+            updatedAt: createdAt,
+            diagnostics: []
+        };
+    });
+    const run = {
+        schemaVersion: 1,
+        id: runId,
+        createdAt,
+        updatedAt: createdAt,
+        invocationId: options.fallback.invocationRecord.id,
+        planId: options.fallback.plan.id,
+        provider: options.fallback.invocationRecord.provider,
+        prompt: options.fallback.plan.prompt,
+        mode: options.fallback.plan.mode,
+        visibility: options.fallback.plan.visibility,
+        requestedSurface: "native_workers",
+        fallbackSurface: "sequential_fallback",
+        status: runStatus,
+        workingDirectory: options.workingDirectory,
+        runDirectory,
+        taskDirectory,
+        resultDirectory,
+        logDirectory,
+        launcherDirectory,
+        outputSchemaPath: join(runDirectory, "panel-worker-output.schema.json"),
+        stopFilePath: join(runDirectory, "stop-requested"),
+        aggregateResultPath: join(runDirectory, "panel-result.json"),
+        workers,
+        diagnostics: options.diagnostics ?? []
+    };
+    await writeJsonAtomic(join(runDirectory, "schema.json"), {
+        schemaVersion: 1,
+        kind: "longtable.panelWorkerRun",
+        note: "Durable worker state stores task/status/result metadata, not hidden reasoning or raw tool traces."
+    });
+    await writeJsonAtomic(run.outputSchemaPath, PANEL_WORKER_OUTPUT_SCHEMA);
+    await Promise.all(workers.map((worker) => writeFile(worker.taskPath, workerTaskPrompt(options.fallback, worker), "utf8")));
+    await writePanelWorkerRun(run);
+    return run;
+}
+export async function readPanelWorkerRun(workingDirectory, runId) {
+    return normalizePanelWorkerRun(JSON.parse(await readFile(panelWorkerRunPath(workingDirectory, runId), "utf8")));
+}
+function normalizePanelWorkerRun(run) {
+    const launcherDirectory = run.launcherDirectory ?? join(run.runDirectory, "launchers");
+    const resultDirectory = run.resultDirectory ?? join(run.runDirectory, "results");
+    return {
+        ...run,
+        launcherDirectory,
+        outputSchemaPath: run.outputSchemaPath ?? join(run.runDirectory, "panel-worker-output.schema.json"),
+        stopFilePath: run.stopFilePath ?? join(run.runDirectory, "stop-requested"),
+        workers: run.workers.map((worker) => ({
+            ...worker,
+            launcherPath: worker.launcherPath ?? join(launcherDirectory, `${worker.id}.sh`),
+            exitCodePath: worker.exitCodePath ?? join(resultDirectory, `${worker.id}.exit.json`),
+            diagnostics: worker.diagnostics ?? []
+        }))
+    };
+}
+export async function writePanelWorkerRun(run) {
+    await writeJsonAtomic(join(run.runDirectory, "run.json"), {
+        ...run,
+        updatedAt: nowIso()
+    });
+}
+function parseWorkerResult(worker) {
+    if (!existsSync(worker.resultPath)) {
+        return null;
+    }
+    const parsed = JSON.parse(readFileSyncUtf8(worker.resultPath));
+    const roleMismatch = typeof parsed.role === "string" && parsed.role !== worker.role;
+    const labelMismatch = typeof parsed.label === "string" && parsed.label !== worker.label;
+    const identityError = [
+        roleMismatch ? `role mismatch: expected ${worker.role}, received ${parsed.role}` : "",
+        labelMismatch ? `label mismatch: expected ${worker.label}, received ${parsed.label}` : ""
+    ].filter(Boolean).join("; ");
+    return {
+        role: worker.role,
+        label: worker.label,
+        status: identityError ? "error" : parsed.status ?? "completed",
+        summary: parsed.summary,
+        claims: parsed.claims,
+        objections: parsed.objections,
+        openQuestions: parsed.openQuestions,
+        evidenceRefs: parsed.evidenceRefs,
+        error: identityError || parsed.error
+    };
+}
+function readFileSyncUtf8(path) {
+    return readFileSync(path, "utf8");
+}
+function statusFromWorkers(workers) {
+    if (workers.every((worker) => worker.status === "completed")) {
+        return "completed";
+    }
+    if (workers.some((worker) => worker.status === "running")) {
+        return "running";
+    }
+    if (workers.some((worker) => worker.status === "failed")) {
+        return "resumable";
+    }
+    if (workers.some((worker) => worker.status === "blocked")) {
+        return "blocked";
+    }
+    if (workers.some((worker) => worker.status === "stop_requested")) {
+        return "stop_requested";
+    }
+    if (workers.every((worker) => worker.status === "stopped" || worker.status === "completed")) {
+        return "stopped";
+    }
+    return "running";
+}
+function tmuxPaneAlive(paneId) {
+    if (!commandAvailable("tmux")) {
+        return false;
+    }
+    try {
+        execFileSync("tmux", ["display-message", "-p", "-t", paneId, "#{pane_id}"], { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function terminalStatus(status) {
+    return status === "completed" || status === "blocked" || status === "stopped" || status === "degraded";
+}
+function launchWorkerPane(run, worker) {
+    const command = `bash ${shellQuote(worker.launcherPath)}`;
+    try {
+        return execFileSync("tmux", [
+            "new-window",
+            "-d",
+            "-P",
+            "-F",
+            "#{pane_id}",
+            "-n",
+            `lt-${worker.id.slice(0, 12)}`,
+            command
+        ], { encoding: "utf8" }).trim();
+    }
+    catch {
+        const sessionName = `longtable-${run.id}-${worker.id}`.replace(/[^A-Za-z0-9_-]/g, "-").slice(0, 80);
+        return execFileSync("tmux", [
+            "new-session",
+            "-d",
+            "-P",
+            "-F",
+            "#{pane_id}",
+            "-s",
+            sessionName,
+            command
+        ], { encoding: "utf8" }).trim();
+    }
+}
+async function writeWorkerLauncher(run, worker) {
+    if (!worker.launcherPath) {
+        return;
+    }
+    await writeFile(worker.launcherPath, launcherScript(run, worker), "utf8");
+    await chmod(worker.launcherPath, 0o755);
+}
+export async function launchPanelWorkerRun(run) {
+    if (terminalStatus(run.status) || run.status === "stop_requested") {
+        return run;
+    }
+    const tmuxAvailable = commandAvailable("tmux");
+    const codexAvailable = commandAvailable("codex");
+    if (!tmuxAvailable || !codexAvailable) {
+        const unavailable = [
+            tmuxAvailable ? null : "tmux:unavailable",
+            codexAvailable ? null : "codex:unavailable"
+        ].filter((entry) => Boolean(entry));
+        const nextRun = {
+            ...run,
+            status: "degraded",
+            updatedAt: nowIso(),
+            diagnostics: [...run.diagnostics, ...unavailable, "Native worker launch degraded; use sequential_fallback or resume when local runtime is available."],
+            workers: run.workers.map((worker) => worker.status === "completed"
+                ? worker
+                : {
+                    ...worker,
+                    status: "pending",
+                    updatedAt: nowIso(),
+                    diagnostics: appendDiagnostic(worker.diagnostics, "Launch skipped because tmux or codex is unavailable.")
+                })
+        };
+        await writePanelWorkerRun(nextRun);
+        return nextRun;
+    }
+    const launchedAt = nowIso();
+    const workers = await Promise.all(run.workers.map(async (worker) => {
+        if (worker.status !== "pending" && worker.status !== "stopped" && worker.status !== "failed") {
+            return worker;
+        }
+        const launchable = {
+            ...worker,
+            launcherPath: worker.launcherPath ?? join(run.launcherDirectory, `${worker.id}.sh`),
+            exitCodePath: worker.exitCodePath ?? join(run.resultDirectory, `${worker.id}.exit.json`)
+        };
+        await writeWorkerLauncher(run, launchable);
+        try {
+            const paneId = launchWorkerPane(run, launchable);
+            return {
+                ...launchable,
+                status: "running",
+                paneId: paneId || launchable.paneId,
+                startedAt: launchedAt,
+                updatedAt: launchedAt,
+                diagnostics: appendDiagnostic(launchable.diagnostics, "Launched with tmux/codex read-only native worker command; launcher persists the structured final output file.")
+            };
+        }
+        catch (error) {
+            return {
+                ...launchable,
+                status: "failed",
+                updatedAt: nowIso(),
+                error: error instanceof Error ? error.message : String(error),
+                diagnostics: appendDiagnostic(launchable.diagnostics, "tmux launch failed before worker result was created.")
+            };
+        }
+    }));
+    const nextRun = {
+        ...run,
+        workers,
+        status: statusFromWorkers(workers),
+        updatedAt: nowIso()
+    };
+    await writePanelWorkerRun(nextRun);
+    return nextRun;
+}
+export async function refreshPanelWorkerRun(run) {
+    const updatedAt = nowIso();
+    const memberResults = [];
+    const workers = run.workers.map((worker) => {
+        try {
+            const result = parseWorkerResult(worker);
+            if (!result) {
+                if (worker.status === "stop_requested") {
+                    const stopped = !worker.paneId || !tmuxPaneAlive(worker.paneId);
+                    return stopped
+                        ? {
+                            ...worker,
+                            status: "stopped",
+                            updatedAt,
+                            diagnostics: appendDiagnostic(worker.diagnostics, "Stop-requested worker reconciled after pane exit.")
+                        }
+                        : worker;
+                }
+                if (worker.status === "running" && worker.paneId && !tmuxPaneAlive(worker.paneId)) {
+                    return {
+                        ...worker,
+                        status: "failed",
+                        updatedAt,
+                        error: "Worker pane is no longer active and no result file was produced.",
+                        diagnostics: appendDiagnostic(worker.diagnostics, "Stale tmux pane detected without a structured result file.")
+                    };
+                }
+                return worker;
+            }
+            memberResults.push(result);
+            const nextStatus = result.status === "error" ? "failed" : result.status === "blocked" ? "blocked" : "completed";
+            return {
+                ...worker,
+                status: nextStatus,
+                completedAt: nextStatus === "failed" ? worker.completedAt : updatedAt,
+                updatedAt,
+                error: result.error
+            };
+        }
+        catch (error) {
+            return {
+                ...worker,
+                status: "failed",
+                updatedAt,
+                error: error instanceof Error ? error.message : String(error),
+                diagnostics: [...worker.diagnostics, "Worker result file could not be parsed."]
+            };
+        }
+    });
+    const nextRun = {
+        ...run,
+        workers,
+        status: statusFromWorkers(workers),
+        updatedAt
+    };
+    if (nextRun.status === "completed" || nextRun.status === "blocked") {
+        const aggregate = {
+            id: createId("panel_result"),
+            planId: run.planId,
+            createdAt: updatedAt,
+            updatedAt,
+            provider: run.provider,
+            surface: "native_workers",
+            status: nextRun.status,
+            interactionDepth: "independent",
+            memberResults,
+            linkedQuestionRecordIds: [],
+            linkedDecisionRecordIds: []
+        };
+        await writeJsonAtomic(nextRun.aggregateResultPath, aggregate);
+    }
+    await writePanelWorkerRun(nextRun);
+    return { run: nextRun, memberResults };
+}
+export async function requestPanelWorkerStop(run) {
+    if (run.status === "completed") {
+        return run;
+    }
+    const updatedAt = nowIso();
+    await writeFile(run.stopFilePath, `${updatedAt}\n`, "utf8");
+    const nextRun = {
+        ...run,
+        status: "stop_requested",
+        updatedAt,
+        workers: run.workers.map((worker) => {
+            if (worker.status === "completed") {
+                return worker;
+            }
+            let stopped = !worker.paneId;
+            if (worker.paneId && commandAvailable("tmux")) {
+                try {
+                    execFileSync("tmux", ["kill-pane", "-t", worker.paneId], { stdio: "ignore" });
+                    stopped = true;
+                }
+                catch {
+                    stopped = true;
+                }
+            }
+            return {
+                ...worker,
+                status: stopped ? "stopped" : "stop_requested",
+                updatedAt,
+                diagnostics: appendDiagnostic(worker.diagnostics, "Stop requested through LongTable panel runtime.")
+            };
+        })
+    };
+    await writePanelWorkerRun(nextRun);
+    return nextRun;
+}
+export async function resumePanelWorkerRun(run) {
+    const updatedAt = nowIso();
+    await rm(run.stopFilePath, { force: true });
+    const nextRun = {
+        ...run,
+        status: "planned",
+        updatedAt,
+        workers: run.workers.map((worker) => worker.status === "completed"
+            ? worker
+            : {
+                ...worker,
+                status: "pending",
+                paneId: undefined,
+                error: undefined,
+                updatedAt,
+                diagnostics: appendDiagnostic(worker.diagnostics, "Resume requested; worker is ready to be relaunched.")
+            })
+    };
+    await writePanelWorkerRun(nextRun);
+    return nextRun;
+}
+export async function waitForPanelWorkerRun(run, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    let current = run;
+    while (Date.now() <= deadline) {
+        const refreshed = await refreshPanelWorkerRun(current);
+        current = refreshed.run;
+        if (terminalStatus(current.status) || current.status === "resumable") {
+            return current;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+    const timedOut = {
+        ...current,
+        updatedAt: nowIso(),
+        diagnostics: appendDiagnostic(current.diagnostics, `wait-timeout:${timeoutMs}ms`)
+    };
+    await writePanelWorkerRun(timedOut);
+    return timedOut;
+}

package/dist/panel.d.ts

@@ -1,4 +1,4 @@
-import type { CheckpointSensitivity, InteractionMode, InvocationIntent, InvocationRecord, PanelPlan, PanelResult, PanelVisibility, QuestionRecord, ProviderKind, RoleKey } from "@longtable/core";
+import type { CheckpointSensitivity, InteractionMode, InvocationIntent, InvocationRecord, PanelPlan, PanelResult, PanelVisibility, QuestionRecord, ProviderKind, InvocationSurface, RoleKey } from "@longtable/core";
 import { type CanonicalPersona } from "./personas.js";
 export interface BuildPanelPlanOptions {
     prompt: string;
@@ -7,6 +7,8 @@ export interface BuildPanelPlanOptions {
     roles?: CanonicalPersona[];
     provider?: ProviderKind;
     visibility?: PanelVisibility;
+    nativeSubagents?: boolean;
+    nativeWorkers?: boolean;
 }
 export interface PanelFallback {
     intent: InvocationIntent;
@@ -24,6 +26,7 @@ export declare function buildInvocationIntent(options: {
     provider?: ProviderKind;
     visibility?: PanelVisibility;
     checkpointSensitivity?: CheckpointSensitivity;
+    requestedSurface?: InvocationSurface;
     rationale?: string[];
 }): InvocationIntent;
 export declare function createPlannedPanelQuestionRecord(plan: PanelPlan, provider?: ProviderKind): QuestionRecord;

package/dist/panel.js

@@ -67,6 +67,11 @@ export function buildPanelPlan(options) {
     const routedRoles = routePersonas(options.prompt).consultedRoles;
     const roles = resolvePanelRoles(options);
     const createdAt = nowIso();
+    const preferredSurface = options.nativeWorkers && options.provider === "codex"
+        ? "native_workers"
+        : options.nativeSubagents && options.provider === "codex"
+            ? "native_subagents"
+            : "sequential_fallback";
     return {
         id: createId("panel_plan"),
         createdAt,
@@ -74,12 +79,17 @@ export function buildPanelPlan(options) {
         prompt: options.prompt,
         members: roles.map((role) => memberForRole(role, explicitRoles, routedRoles)),
         visibility: options.visibility ?? "always_visible",
-        preferredSurface: "sequential_fallback",
+        preferredSurface,
         fallbackSurface: "sequential_fallback",
         checkpointSensitivity: highestSensitivity(roles),
         rationale: [
             "Option A uses provider-neutral panel semantics before native provider orchestration.",
-            "Sequential fallback is the stable execution path for both Claude Code and Codex.",
+            preferredSurface === "native_workers"
+                ? "LongTable-native workers may execute role passes through durable worker state; outputs must normalize back to this PanelResult."
+                : preferredSurface === "native_subagents"
+                    ? "Codex native subagents may execute the role passes when the current provider session exposes them; outputs must normalize back to this PanelResult."
+                    : "Sequential fallback is the stable execution path for both Claude Code and Codex.",
+            "Sequential fallback remains the required degradation path.",
             roles.length === explicitRoles.length && explicitRoles.length > 0
                 ? "The panel is constrained by explicitly requested roles."
                 : "The panel combines default research-review roles with prompt-triggered roles."
@@ -94,7 +104,7 @@ export function buildInvocationIntent(options) {
         prompt: options.prompt,
         roles: options.roles,
         provider: options.provider,
-        requestedSurface: "sequential_fallback",
+        requestedSurface: options.requestedSurface ?? "sequential_fallback",
         visibility: options.visibility ?? "always_visible",
         checkpointSensitivity: options.checkpointSensitivity ?? "medium",
         rationale: options.rationale ?? ["Panel invocation requested."]
@@ -158,7 +168,7 @@ export function createPlannedPanelResult(plan, provider, linkedQuestionRecordIds
         createdAt,
         updatedAt: createdAt,
         provider,
-        surface: "sequential_fallback",
+        surface: plan.preferredSurface,
         status: "planned",
         interactionDepth: "independent",
         memberResults: plan.members.map((member) => ({
@@ -179,11 +189,15 @@ export function createPlannedInvocationRecord(options) {
         intent: options.intent,
         status: "planned",
         provider: options.provider,
-        surface: "sequential_fallback",
+        surface: options.plan.preferredSurface,
         interactionDepth: "independent",
         panelPlan: options.plan,
         panelResult: options.result,
-        degradationReason: "Sequential fallback is the stable LongTable panel surface."
+        degradationReason: options.plan.preferredSurface === "native_workers"
+            ? "LongTable-native panel workers are optional; sequential_fallback is the required degradation path when local worker execution is unavailable."
+            : options.plan.preferredSurface === "native_subagents"
+                ? "Codex native subagent execution is session-dependent; sequential_fallback is the required LongTable degradation path."
+                : "Sequential fallback is the stable LongTable panel surface."
     };
 }
 function roleInstruction(member) {
@@ -203,9 +217,20 @@ function languageNote(language) {
 }
 export function renderSequentialFallbackPrompt(plan) {
     const language = detectOutputLanguage(plan.prompt);
+    const nativeSubagentNote = plan.preferredSurface === "native_subagents"
+        ? [
+            "Preferred execution surface: native_subagents when the current Codex session exposes provider-native subagents.",
+            "Fallback: if native subagents are unavailable, run the same role passes sequentially and disclose the fallback in the technical record."
+        ]
+        : plan.preferredSurface === "native_workers"
+            ? [
+                "Preferred execution surface: LongTable-native panel workers when the local runtime supports them.",
+                "Fallback: if native workers are unavailable or stopped, run the same role passes sequentially and disclose the fallback in the technical record."
+            ]
+            : ["Execution surface: sequential_fallback"];
     return [
         "LongTable mode: Panel",
-        "Execution surface: sequential_fallback",
+        ...nativeSubagentNote,
         "",
         "Run this as a structured panel review. Treat each role as an independent pass, then synthesize.",
         "Do not expose hidden reasoning, private tool traces, or provider chain-of-thought.",
@@ -221,6 +246,7 @@ export function renderSequentialFallbackPrompt(plan) {
         "3. Conflict summary",
         "4. Decision prompt for the researcher",
         "5. Technical record: roles consulted, execution surface, fallback/native mode, and source/file references used",
+        "6. Persistence hint: if this is a real panel result, record structured outputs with `longtable panel record --invocation <id> --result-file <json>` before generating `longtable handoff`.",
         "",
         "Research object:",
         plan.prompt
@@ -235,6 +261,7 @@ export function buildPanelFallback(options) {
         provider: options.provider,
         visibility: plan.visibility,
         checkpointSensitivity: plan.checkpointSensitivity,
+        requestedSurface: plan.preferredSurface,
         rationale: plan.rationale
     });
     const questionRecord = createPlannedPanelQuestionRecord(plan, options.provider);