firedrill-run 2.2.4 → 3.0.0

package/dist/cli/src/continuous-simulation.js

@@ -0,0 +1,277 @@
+import { APP_ORIGIN } from './http.js';
+import { api, openBrowser } from './auth.js';
+import { CliError } from './http.js';
+import { selectOne, terminalText } from './prompts.js';
+import { selectedWorkspace } from './world-access.js';
+import { identifier } from './world-contracts.js';
+import { ciConfigurationRead, ciConfigurationMatches, ciConfigurationsMatch, ciRevisionPageMatches, ciScenariosMatch } from './ci-configuration-contracts.js';
+import { ciRunRead, ciRunMatches, ciRunsMatch } from './ci-run-contracts.js';
+import { ciAccessRead, ciApprovalsMatch, ciActivationsMatch } from './ci-access-contracts.js';
+import { ciResultRead, ciResultMatches, ciScoresMatch, ciCriteriaMatches } from './ci-result-contracts.js';
+import { ciDeliveryRead, ciDeliveryMatches, ciDeliveriesMatch, ciDeliveryStates } from './ci-delivery-contracts.js';
+import { reviewCISetupProposal } from './ci-setup-proposals.js';
+import { ciCoverage } from './ci-coverage.js';
+function configuredPlan(row) {
+    return row.baseline ? `Baseline: ${terminalText(row.baseline.world_name)} · Saved plan ${row.baseline.plan_revision} · ${row.baseline.scenario_count.toLocaleString()} scenarios · ${row.baseline.planned_trials.toLocaleString()} drills`
+        : 'Saved world unavailable';
+}
+function scenarioPolicy(row) {
+    const policy = row.head?.document.scenario_policy;
+    return policy?.mode === 'change_relevant' ? `PR selection: change-relevant, with ${policy.mandatory_scenario_ids.length.toLocaleString()} additional mandatory cases. Nightly keeps all baseline cases.`
+        : 'PR selection: all planned scenarios.';
+}
+function configuredTriggers(row) {
+    return row.head?.document.triggers.map(value => value === 'pull_request' ? 'Pull requests' : value === 'nightly'
+        ? `Nightly: ${String(row.head.document.nightly_hour_utc).padStart(2, '0')}:00 UTC`
+        : `Branch: ${terminalText(row.head.document.default_branch)}`).join(' · ') || 'No triggers saved';
+}
+const states = new Set(['queued', 'acquiring_source', 'preparing_world', 'configuration_required', 'validating', 'planning', 'running',
+    'report_pending', 'attention_required', 'canceling', 'completed', 'failed', 'canceled', 'superseded']);
+const recordedOutcomes = { met: 'exact checks met', unmet: 'exact checks unmet', incomplete: 'incomplete coverage', report_only: 'report only', no_report: 'no available report' };
+function pageNumber(value) {
+    if (value !== undefined && !/^[1-9][0-9]{0,8}$/.test(value))
+        throw new CliError('page_invalid', 'Use a positive page number.', 2);
+    return value ?? '1';
+}
+function label(value) { return { rerun_review: 'Rerun review', check_run: 'Reviewed rerun', action_required: 'Review required' }[value] ?? value.replaceAll('_', ' '); }
+function link(workspace, path) {
+    const url = new URL(path, APP_ORIGIN);
+    url.searchParams.set('workspace', identifier(workspace));
+    return url.href;
+}
+export async function ciCommand(args, options, output) {
+    const interactive = !options.json && !!process.stdin.isTTY && !!process.stderr.isTTY;
+    const context = await selectedWorkspace({ workspace: options.workspace, interactive, signal: options.signal, openBrowser: options.openBrowser });
+    const prefix = `/api/workspaces/${context.workspace}/ci`;
+    const read = (path) => api(path, { actor: context.owner, signal: options.signal });
+    const configurationRow = async (id) => {
+        const value = await read(`${prefix}/configurations/${identifier(id)}`);
+        return ciConfigurationRead(value, ciConfigurationMatches(value, context.workspace, id));
+    };
+    const configurationRows = async (number, search = '', state = '') => {
+        const value = await read(`${prefix}/configurations?${new URLSearchParams({ page: String(number), q: search, state })}`);
+        return ciConfigurationRead(value, ciConfigurationsMatch(value, context.workspace, search, state, number));
+    };
+    const runRow = async (id) => {
+        const value = await read(`${prefix}/runs/${identifier(id)}`);
+        return ciRunRead(value, ciRunMatches(value, context.workspace, { id }));
+    };
+    const runRows = async (configuration, number, filters = {}) => {
+        const value = await read(`${prefix}/configurations/${configuration}/runs?${new URLSearchParams({ page: String(number),
+            sha: filters.sha ?? '', state: filters.state ?? '', trigger: filters.trigger ?? '', world: filters.world ?? '', reference: filters.reference ?? '', outcome: filters.outcome ?? '' })}`);
+        return ciRunRead(value, ciRunsMatch(value, context.workspace, configuration, filters, number));
+    };
+    // Managed CI setup is retired (FIR-504); retained configurations and run history stay readable.
+    const action = args[0] ?? 'list';
+    const known = ['list', 'show', 'scenarios', 'revisions', 'automatic-history', 'approvals', 'runs', 'run', 'result', 'criteria', 'scores', 'coverage', 'delivery', 'delivery-history', 'configure', 'access', 'inputs', 'open', 'setup-proposal'];
+    if (!known.includes(action))
+        throw new CliError('arguments_invalid', 'Use ci list, show, scenarios, revisions, automatic-history, approvals, runs, run, result, criteria, scores, coverage, delivery, delivery-history, configure, setup-proposal, access, inputs or open.', 2);
+    if (options.search && !['list', 'scenarios', 'criteria', 'scores', 'coverage'].includes(action))
+        throw new CliError('arguments_invalid', 'Use --search to find a CI configuration, scenario, coverage path or criterion by name.', 2);
+    if (action !== 'runs' && (options.world !== undefined && action !== 'setup-proposal' || [options.trigger, options.reference, options.outcome].some(value => value !== undefined)))
+        throw new CliError('arguments_invalid', 'Use --world with ci runs or setup-proposal. Trigger, reference and outcome filters apply to ci runs.', 2);
+    if (options.page && !['list', 'scenarios', 'runs', 'revisions', 'automatic-history', 'approvals', 'criteria', 'scores', 'coverage', 'delivery-history'].includes(action))
+        throw new CliError('arguments_invalid', 'Use --page with CI directories and history.', 2);
+    if (options.status && !['list', 'runs', 'automatic-history', 'approvals', 'criteria', 'coverage', 'delivery-history'].includes(action))
+        throw new CliError('arguments_invalid', 'Use --status with CI directories, coverage and history.', 2);
+    if (args.length > (['scenarios', 'runs', 'revisions', 'automatic-history', 'approvals', 'delivery', 'delivery-history', 'coverage'].includes(action) ? 3 : action === 'list' ? 1 : 2))
+        throw new CliError('arguments_invalid', 'Use one configuration or run ID for this CI action.', 2);
+    const page = pageNumber(options.page);
+    if (action === 'setup-proposal') {
+        // Reviewing a CI setup draft hands off to the retired assistant/CI setup (FIR-504); nothing is read or sent.
+        throw new CliError('legacy_launch_retired', 'Reviewing a CI setup draft is retired with managed CI setup; retained CI configurations and run history stay readable. Nothing was opened.', 2);
+    }
+    async function configuration(value) {
+        if (value)
+            return configurationRow(value);
+        if (!interactive)
+            throw new CliError('configuration_required', 'Choose a configuration ID with firedrill ci list.', 2);
+        let number = 1;
+        while (true) {
+            const rows = await configurationRows(number);
+            const choices = rows.results.map(row => ({ value: row.id, label: row.name, detail: `${row.repository} · ${configuredPlan(row)} · ${label(row.state)}` }));
+            if (number > 1)
+                choices.unshift({ value: 'previous', label: 'Previous page', detail: '' });
+            if (rows.next)
+                choices.push({ value: 'next', label: 'Next page', detail: '' });
+            if (!choices.length)
+                throw new CliError('configuration_required', 'No CI configurations are saved.', 2);
+            const picked = await selectOne('Repository configuration', choices, options.signal);
+            if (picked === 'previous') {
+                number -= 1;
+                continue;
+            }
+            if (picked === 'next') {
+                number += 1;
+                continue;
+            }
+            return configurationRow(picked);
+        }
+    }
+    async function run(value) {
+        if (value)
+            return runRow(value);
+        if (!interactive)
+            throw new CliError('run_required', 'Choose a CI run ID with firedrill ci runs.', 2);
+        const config = await configuration();
+        let number = 1;
+        while (true) {
+            const rows = await runRows(config.id, number);
+            const choices = rows.results.map(row => ({ value: row.id, label: `${row.head_sha.slice(0, 12)}${row.pull_number ? ` · PR #${row.pull_number}` : ''}`,
+                detail: `${label(row.state)} · ${row.reference}` }));
+            if (number > 1)
+                choices.unshift({ value: 'previous', label: 'Previous page', detail: '' });
+            if (rows.next)
+                choices.push({ value: 'next', label: 'Next page', detail: '' });
+            if (!choices.length)
+                throw new CliError('run_required', 'This configuration has no saved CI runs. Open its history in the browser to review setup.', 2);
+            const picked = await selectOne('CI run', choices, options.signal);
+            if (picked === 'previous') {
+                number -= 1;
+                continue;
+            }
+            if (picked === 'next') {
+                number += 1;
+                continue;
+            }
+            return runRow(picked);
+        }
+    }
+    async function browser(path) {
+        const url = link(context.workspace, path);
+        const opened = !options.json && options.openBrowser ? await openBrowser(url) : false;
+        output('browser_handoff', { url, opened, workspace_id: context.workspace, local_execution_started: false }, `${opened ? 'Opened CI in your browser.' : 'Open CI in your browser:'}\n${url}`);
+    }
+    if (action === 'list') {
+        if (options.status && !['draft', 'active', 'disconnected'].includes(options.status))
+            throw new CliError('status_invalid', 'Choose draft, active or disconnected.', 2);
+        if ((options.search?.length ?? 0) > 200)
+            throw new CliError('search_invalid', 'Use a configuration name prefix of 200 characters or fewer.', 2);
+        const rows = await configurationRows(Number(page), options.search ?? '', options.status ?? '');
+        output('ci_configurations', rows, rows.results.map(row => `${row.id}  ${terminalText(row.name)}  ${terminalText(row.repository)}  ${label(row.state)}\n${configuredPlan(row)}\n${configuredTriggers(row)}`).join('\n\n') || 'No CI configurations match.');
+        return;
+    }
+    if (action === 'configure') {
+        throw new CliError('legacy_launch_retired', 'Managed CI setup is retired; retained CI configurations and run history stay readable. Nothing was opened.', 2);
+    }
+    if (action === 'scenarios') {
+        const row = await configuration(args[1]), revision = args[2] ?? String(row.revision);
+        if (!/^[1-9][0-9]{0,18}$/.test(revision) || BigInt(revision) >= 2n ** 63n || (options.search?.length ?? 0) > 200)
+            throw new CliError('selection_invalid', 'Choose a positive configuration revision and a scenario name prefix of 200 characters or fewer.', 2);
+        const value = await read(`${prefix}/configurations/${row.id}/scenarios?${new URLSearchParams({ revision, page, q: options.search ?? '' })}`);
+        ciConfigurationRead(value, ciScenariosMatch(value, context.workspace, row.id, revision, options.search ?? '', Number(page)));
+        output('ci_configured_scenarios', value, [`Configuration ${value.configuration_revision} · ${terminalText(value.world_name)} · Saved plan ${value.plan_revision}`,
+            ...value.results.map(one => one.available ? `${terminalText(one.name ?? '')} · Scenario revision ${one.revision}\n${one.detail_path ? link(context.workspace, one.detail_path) : ''}` : `Saved selection ${one.position + 1}: Scenario unavailable`),
+            ...(!value.count ? ['No saved scenarios match this search.'] : []), `Page ${value.page}; ${value.count.toLocaleString()} scenarios.`,
+            ...(value.next ? [`Continue with --page ${value.page + 1} and the same revision/search.`] : [])].join('\n\n'));
+        return;
+    }
+    if (['revisions', 'automatic-history', 'approvals'].includes(action)) {
+        const row = await configuration(args[1]), revision = args[2] ?? '';
+        if (revision && (!/^[1-9][0-9]{0,18}$/.test(revision) || BigInt(revision) >= 2n ** 63n))
+            throw new CliError('revision_invalid', 'Use a positive configuration revision after its ID.', 2);
+        if (action === 'revisions') {
+            const rows = await read(`${prefix}/configurations/${row.id}/revisions?${new URLSearchParams({ page, revision })}`);
+            ciConfigurationRead(rows, ciRevisionPageMatches(rows, context.workspace, row.id, revision, '', Number(page)));
+            output('ci_configuration_revisions', rows, rows.results.map(one => `Revision ${one.revision}  ${terminalText(one.document.name)}  ${label(one.document.mode)}  ${one.document.baseline_sha.slice(0, 12)}  ${one.created_at}\nPR selection: ${one.document.scenario_policy.mode === 'change_relevant' ? `change-relevant, ${one.document.scenario_policy.mandatory_scenario_ids.length} additional mandatory cases` : 'all planned scenarios'}`).join('\n') || 'No configuration revisions match.');
+            return;
+        }
+        if (action === 'automatic-history') {
+            if (options.status && !['enabled', 'paused'].includes(options.status))
+                throw new CliError('status_invalid', 'Choose enabled or paused.', 2);
+            const rows = await read(`${prefix}/configurations/${row.id}/activations?${new URLSearchParams({ page, revision, state: options.status ?? '' })}`);
+            ciAccessRead(rows, ciActivationsMatch(rows, context.workspace, row.id, revision, options.status ?? '', Number(page)));
+            output('ci_automatic_history', rows, rows.results.map(one => `${one.id}  Revision ${one.revision}  ${label(one.state)}  ${one.created_at}`).join('\n') || 'No automatic-run settings match.');
+            return;
+        }
+        if (options.status && !['recorded', 'revoked'].includes(options.status))
+            throw new CliError('status_invalid', 'Choose recorded or revoked.', 2);
+        const rows = await read(`${prefix}/configurations/${row.id}/input-approvals?${new URLSearchParams({ page, revision, state: options.status ?? '' })}`);
+        ciAccessRead(rows, ciApprovalsMatch(rows, context.workspace, row.id, { revision, state: options.status ?? '' }, Number(page)));
+        output('ci_approval_history', rows, rows.results.map(one => `${one.id}  Revision ${one.revision}  ${label(one.scope)}${one.head_sha ? ` ${one.head_sha.slice(0, 12)}` : ''}  ${label(one.state)}  ${one.created_at}`).join('\n') || 'No input approvals match.');
+        return;
+    }
+    if (action === 'show' || action === 'access' || action === 'runs') {
+        const row = await configuration(args[1]);
+        if (action === 'access') {
+            await browser(`/ci/configurations/${row.id}/access`);
+            return;
+        }
+        if (action === 'show') {
+            output('ci_configuration', { ...row, url: link(context.workspace, `/ci/configurations/${row.id}`) }, `${terminalText(row.name)}\n${terminalText(row.repository)}\n${configuredPlan(row)}\n${configuredTriggers(row)}\n${scenarioPolicy(row)}\n${label(row.state)} · revision ${row.revision}\n${link(context.workspace, `/ci/configurations/${row.id}`)}`);
+            return;
+        }
+        if (options.status && !states.has(options.status))
+            throw new CliError('status_invalid', 'Choose a retained CI run state.', 2);
+        if (args[2] && !/^[0-9a-f]{40}$/i.test(args[2]))
+            throw new CliError('commit_invalid', 'Use the full commit SHA after the configuration ID.', 2);
+        if (options.trigger !== undefined && !['pull_request', 'push', 'scheduled', 'check_run'].includes(options.trigger))
+            throw new CliError('trigger_invalid', 'Choose pull_request, push, scheduled or check_run (reviewed reruns).', 2);
+        if (options.outcome !== undefined && !Object.hasOwn(recordedOutcomes, options.outcome))
+            throw new CliError('outcome_invalid', 'Choose met, unmet, incomplete, report_only or no_report.', 2);
+        if (options.reference !== undefined && (options.reference.length > 1024 || /[\u0000-\u001f\u007f]/.test(options.reference)))
+            throw new CliError('reference_invalid', 'Use a case-sensitive Git reference prefix of 1024 characters or fewer.', 2);
+        const rows = await runRows(row.id, Number(page), { state: options.status ?? '', sha: args[2]?.toLowerCase() ?? '',
+            world: options.world ? identifier(options.world) : '', trigger: options.trigger ?? '', reference: options.reference ?? '', outcome: options.outcome ?? '',
+        });
+        output('ci_runs', rows, rows.results.map(one => `${one.id}  ${one.head_sha.slice(0, 12)}  ${one.pull_number ? `PR #${one.pull_number}` : terminalText(one.reference)}  ${label(one.state)}  ${one.recorded_report ? `Recorded: ${recordedOutcomes[one.recorded_report.status] ?? 'unavailable'} at ${one.recorded_report.observed_at}${one.recorded_report.complete ? '' : ' (coverage incomplete)'}` : 'No available report'}`).join('\n') || 'No CI runs match. CI runs on GitHub events independently of your terminal.');
+        return;
+    }
+    const selected = await run(args[1]);
+    if (action === 'coverage') {
+        await ciCoverage(selected.id, args[2], context, options, output);
+        return;
+    }
+    if (action === 'inputs' || action === 'open') {
+        await browser(`/ci/runs/${selected.id}${action === 'inputs' ? '/inputs' : ''}`);
+        return;
+    }
+    if (action === 'run') {
+        output('ci_run', { ...selected, url: link(context.workspace, `/ci/runs/${selected.id}`) }, `${selected.head_sha}\n${label(selected.state)} · configuration ${selected.configuration_revision}${selected.trigger === 'check_run' ? '\nReviewed rerun. Execution permissions are specific to this run.' : ''}\n${link(context.workspace, `/ci/runs/${selected.id}`)}`);
+        return;
+    }
+    if (action === 'result') {
+        const value = await read(`${prefix}/runs/${selected.id}/result`);
+        ciResultRead(value, ciResultMatches(value, context.workspace, selected.id, { sha: selected.head_sha, campaign: selected.campaign_id }));
+        const summary = value.result;
+        output('ci_result', value, summary ? `${summary.scenarios} scenarios · ${summary.planned_trials} planned drills\nCompleted: ${summary.trials.completed}. Agent failures: ${summary.trials.failed}. Platform failures: ${summary.trials.platform_failed}. Timed out: ${summary.trials.timed_out}. Unfinished: ${summary.trials.unfinished}.\n${label(summary.decision.status)}. ${value.published ? `GitHub result: ${value.ci_verdict}` : 'GitHub delivery is not confirmed for this result.'}`
+            : `Report: ${label(value.state)}. No result is implied yet.`);
+        return;
+    }
+    if (action === 'scores') {
+        if ((options.search?.length ?? 0) > 200 || /[\u0000-\u001f\u007f]/.test(options.search ?? ''))
+            throw new CliError('search_invalid', 'Use a criterion name prefix of 200 characters or fewer.', 2);
+        const value = await read(`${prefix}/runs/${selected.id}/result/scores?${new URLSearchParams({ page, q: options.search ?? '' })}`);
+        ciResultRead(value, ciScoresMatch(value, context.workspace, selected.id, options.search ?? '', Number(page)));
+        const score = (number) => number === null ? 'not assessed' : number.toLocaleString(undefined, { maximumFractionDigits: 2 });
+        output('ci_scores', value, value.state !== 'ready' || value.count === null ? `Scores: ${label(value.state)}. Refresh the original result before inspecting scores.`
+            : value.results.map(one => `${terminalText(one.cohort.scenario_name)} · ${terminalText(one.cohort.criterion)}\nMean ${score(one.summary.mean)}${one.summary.mean === null ? '' : ` / ${one.cohort.levels.length - 1}`} (${one.cohort.direction === 'lower' ? 'lower' : 'higher'} is better). ${one.summary.assessed} assessed; ${one.summary.not_assessable} not assessable; ${one.summary.not_applicable} not applicable.\nEvaluator: ${terminalText(one.cohort.model)}`).join('\n\n') || 'No retained CI score groups match. Missing evaluations remain in report coverage.');
+        return;
+    }
+    if (action === 'criteria') {
+        if ((options.search?.length ?? 0) > 200 || /[\u0000-\u001f\u007f]/.test(options.search ?? ''))
+            throw new CliError('search_invalid', 'Use a criterion name prefix of 200 characters or fewer.', 2);
+        if (options.status && !['complete', 'incomplete', 'not_assessable'].includes(options.status))
+            throw new CliError('status_invalid', 'Choose complete, incomplete or not_assessable coverage.', 2);
+        const value = await read(`${prefix}/runs/${selected.id}/result/criteria?${new URLSearchParams({ page, q: options.search ?? '', status: options.status ?? '' })}`);
+        ciResultRead(value, ciCriteriaMatches(value, context.workspace, selected.id, options.search ?? '', options.status ?? '', Number(page)));
+        output('ci_criteria', value, value.state !== 'ready' || value.count === null ? `Evaluation coverage: ${label(value.state)}. Refresh the original result before inspecting coverage.`
+            : value.results.map(one => `${terminalText(one.name ?? 'Unavailable criterion')} · ${one.counts.expected === 0 ? 'no applicable drills' : label(one.coverage_state)}\n${one.counts.assessed} of ${one.counts.expected} expected assessments scored; ${one.counts.not_applicable} not applicable; ${one.counts.not_assessable} not assessable; ${one.counts.unavailable} unavailable.${one.definition_url ? `\n${link(context.workspace, one.definition_url)}` : '\nSaved definition unavailable.'}`).join('\n\n') || 'No CI evaluation criteria match.');
+        return;
+    }
+    const channel = args[2] ?? 'check';
+    if (!['check', 'comment'].includes(channel))
+        throw new CliError('channel_invalid', 'Choose check or comment.', 2);
+    const path = `${prefix}/runs/${selected.id}/${channel}`;
+    if (action === 'delivery') {
+        const value = await read(path);
+        ciDeliveryRead(value, ciDeliveryMatches(value, context.workspace, selected.id, channel));
+        output('ci_delivery', value, `${channel}: ${label(value.state)}${value.head?.purpose === 'rerun_review' && value.head.rerun_event_id ? `\nRerun requested. Review before starting: ${link(context.workspace, `/ci/configurations/${selected.configuration_id}?${new URLSearchParams({ events: 'check_run', event: value.head.rerun_event_id })}`)}` : ''}\n${link(context.workspace, `/ci/runs/${selected.id}`)}`);
+        return;
+    }
+    if (options.status && !ciDeliveryStates.includes(options.status))
+        throw new CliError('status_invalid', 'Choose a retained GitHub delivery state.', 2);
+    const rows = await read(`${path}/history?${new URLSearchParams({ page, status: options.status ?? '' })}`);
+    ciDeliveryRead(rows, ciDeliveriesMatch(rows, context.workspace, selected.id, channel, options.status ?? '', Number(page)));
+    output('ci_delivery_history', rows, rows.results.map(row => `${row.intent_id}  ${label(row.purpose)}  ${label(row.state)}  ${row.created_at}`).join('\n') || 'No delivery records match.');
+}

package/dist/cli/src/coordinated-checkpoints.js

@@ -0,0 +1,133 @@
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { unlink } from 'node:fs/promises';
+import { api } from './auth.js';
+import { privateDirectory } from './credentials.js';
+import { CliError } from './http.js';
+import { selectOne, terminalText } from './prompts.js';
+import { selectedWorld } from './world-access.js';
+import { identifier } from './world-contracts.js';
+import { ownedSourceMetadataFile, readSourceMetadata, writeSourceMetadata } from './source-connection.js';
+import { withBootstrapProcessLock } from './bootstrap-process-lock.js';
+import { worldSessionMatches } from '../../contracts/session-contracts.js';
+import { resourcePageMatches } from '../../contracts/world-lifetime-contracts.js';
+import { coordinatedCheckpointMatches, coordinatedCheckpointDetailMatches } from '../../contracts/coordinated-checkpoint-contracts.js';
+export const COORDINATED_ACTIONS = ['coordinated-checkpoints', 'coordinated-checkpoint', 'save-world-and-agent'];
+const problem = () => new CliError('coordinated_checkpoint_unconfirmed', 'Inspect the original world and agent capture. No replacement capture was submitted.');
+const label = (value) => `${terminalText(value.name)} · ${value.available ? 'Saved' : value.state}\n`
+    + `${value.application_component_count} application components; ${value.excluded_count} excluded. `
+    + (value.consistency === 'not_observed' ? 'Capture not observed.' : value.consistency === 'application_consistent'
+        ? 'Source-attested application consistency with supported native data.' : 'Capture includes crash-consistent components.')
+    + (value.problem ? '\n' + terminalText(value.problem) : '');
+export async function coordinatedCheckpointsCommand(args, options, output) {
+    const action = args[0], writing = action === 'save-world-and-agent';
+    if (!COORDINATED_ACTIONS.includes(action) || (action === 'coordinated-checkpoints' ? args.length > 2 : args.length !== 2)
+        || options.page !== undefined && (!/^[1-9][0-9]{0,8}$/.test(options.page) || action !== 'coordinated-checkpoints')
+        || options.search !== undefined && (action !== 'coordinated-checkpoints' || options.search.length > 200)
+        || !writing && (options.name !== undefined || options.run !== undefined || options.request !== undefined))
+        throw new CliError('arguments_invalid', 'Use sessions coordinated-checkpoints [session], coordinated-checkpoint <id>, or save-world-and-agent <session> --name <name>.', 2);
+    const tty = !options.json && Boolean(process.stdin.isTTY && process.stderr.isTTY);
+    const scope = await selectedWorld({ ...options, interactive: tty });
+    const auth = (signal = options.signal) => ({ actor: scope.owner, workspace: scope.workspace, signal });
+    const read = async (key, session, input, signal = options.signal) => {
+        const value = await api(`${scope.prefix}/coordinated-checkpoints/${identifier(key)}`, auth(signal));
+        if (!coordinatedCheckpointDetailMatches(value, scope.world, { ...(session ? { session } : {}), ...(input ? { key: input.key, name: input.input.name } : {}) })
+            || !input && value.id !== key && value.request_key !== key)
+            throw problem();
+        return value;
+    };
+    const show = (value) => output('coordinated_checkpoint', value, label(value)
+        + `\n${value.record_count === null ? 'World data is unavailable.' : `${value.record_count} saved records in ${value.collection_count} collections.`}`
+        + (value.excluded.length ? `\nNot included: ${value.excluded.map(terminalText).join(', ')}.` : '')
+        + '\nNew-process continuation only. External accounts and elapsed wall time are not restored.');
+    if (action === 'coordinated-checkpoint') {
+        show(await read(identifier(args[1])));
+        return;
+    }
+    if (action === 'coordinated-checkpoints') {
+        const page = Number(options.page ?? 1), session = args[1] ? identifier(args[1]) : undefined;
+        const base = session ? `${scope.prefix}/runtime-sessions/${session}` : scope.prefix;
+        const value = await api(`${base}/coordinated-checkpoints?page=${page}&q=${encodeURIComponent(options.search ?? '')}`, auth());
+        if (!resourcePageMatches(value, page, row => coordinatedCheckpointMatches(row, scope.world, session ? { session } : {})))
+            throw problem();
+        output('coordinated_checkpoints', value, (value.results.map(label).join('\n\n') || 'No saved world and agent checkpoints.')
+            + `\nPage ${value.page}; ${value.count} matching captures.${value.next ? ` Continue with --page ${value.page + 1}.` : ''}`);
+        return;
+    }
+    const sessionId = identifier(args[1]);
+    const path = join(await privateDirectory(), `coordinated-capture-${scope.owner}-${scope.workspace}-${scope.world}-${sessionId}.json`);
+    await withBootstrapProcessLock(path + '.lock', options.signal, async (signal) => {
+        let intent = null;
+        try {
+            const file = await ownedSourceMetadataFile(path, 4096);
+            try {
+                intent = await readSourceMetadata(file, 4096);
+            }
+            finally {
+                await file.close();
+            }
+            if (!intent || intent.schema !== 'firedrill.coordinated-capture-intent.v1' || intent.owner !== scope.owner || intent.workspace !== scope.workspace
+                || intent.world !== scope.world || intent.session !== sessionId || Object.keys(intent).sort().join(',') !== 'input,key,owner,schema,session,workspace,world'
+                || identifier(intent.key) !== intent.key || !intent.input || Object.keys(intent.input).sort().join(',') !== 'capture_consent,expected_reset_count,name'
+                || intent.input.capture_consent !== true || typeof intent.input.name !== 'string' || intent.input.name.length < 1 || intent.input.name.length > 120
+                || !/^(0|[1-9][0-9]{0,18})$/.test(intent.input.expected_reset_count))
+                throw problem();
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (intent && (options.request !== undefined && identifier(options.request) !== intent.key
+            || options.name !== undefined && options.name.trim() !== intent.input.name))
+            throw problem();
+        const key = intent?.key ?? identifier(options.request ?? randomUUID());
+        try {
+            const prior = await read(key, sessionId, intent ?? undefined, signal);
+            show(prior);
+            if (intent && prior.state !== 'pending')
+                await unlink(path);
+            return;
+        }
+        catch (error) {
+            if (!(error instanceof CliError) || error.httpStatus !== 404)
+                throw error;
+        }
+        const row = await api(`${scope.prefix}/runtime-sessions/${sessionId}`, auth(signal));
+        if (!worldSessionMatches(row, { actor: scope.owner, workspace: scope.workspace, world: scope.world }, { id: sessionId })
+            || !row.coordinated_checkpoint.available || !row.observation_current || !row.can_control || row.reset_pending || row.external_effects || row.terminal_at
+            || intent && row.reset_count !== intent.input.expected_reset_count)
+            throw new CliError('coordinated_checkpoint_not_ready', 'The original capture needs the same current synthetic session and reset state. Its saved status remains available; no capture was submitted.', 2);
+        if (!intent) {
+            const name = options.name?.trim();
+            if (!name || name.length > 120 || /[\u0000-\u001f\u007f]/.test(name))
+                throw new CliError('arguments_invalid', 'Use --name with a plain checkpoint name up to 120 characters.', 2);
+            intent = { schema: 'firedrill.coordinated-capture-intent.v1', owner: scope.owner, workspace: scope.workspace, world: scope.world,
+                session: sessionId, key, input: { name, expected_reset_count: row.reset_count, capture_consent: true } };
+        }
+        if (!options.run && !(tty && await selectOne('Capture supported world and application state?', [
+            { value: false, label: 'Cancel' }, { value: true, label: 'Capture state', detail: 'Uses the source-declared quiescence API and supported native stores. Open tool views close. External accounts, live processes and elapsed wall time are not captured.' }
+        ], signal)))
+            throw new CliError('coordinated_checkpoint_consent_required', 'Use --run only after reviewing this exact capture.', 2);
+        await writeSourceMetadata(path, intent);
+        output('coordinated_checkpoint_intent', { request_key: intent.key, session_id: sessionId }, `Request: ${intent.key}\nRecovery: firedrill sessions coordinated-checkpoint ${intent.key} --world ${scope.world} --workspace ${scope.workspace}. A missing receipt does not authorize a replacement capture.`);
+        let accepted;
+        try {
+            accepted = await api(`${scope.prefix}/runtime-sessions/${sessionId}/coordinated-checkpoints`, {
+                ...auth(signal), method: 'POST', idempotencyKey: intent.key, body: intent.input
+            });
+        }
+        catch (error) {
+            if (error instanceof CliError && error.httpStatus === 400 && error.code === 'coordinated_checkpoint_input_invalid')
+                await unlink(path);
+            throw error;
+        }
+        if (!coordinatedCheckpointDetailMatches(accepted, scope.world, { session: sessionId, key: intent.key, name: intent.input.name }))
+            throw problem();
+        const observed = await read(intent.key, sessionId, intent, signal);
+        if (observed.id !== accepted.id)
+            throw problem();
+        show(observed);
+        if (observed.state !== 'pending')
+            await unlink(path);
+    });
+}

package/dist/cli/src/credential-mode.js

@@ -0,0 +1,139 @@
+/**
+ * Credential store availability and per-process credential mode selection
+ * (Plan20 section 3.6, W09/W13C).
+ *
+ * Platform record (source behavior, runtime unverified):
+ *
+ * | Platform | Persistent store | Typical unavailability | Session-only companion |
+ * | --- | --- | --- | --- |
+ * | macOS | Keychain (login keychain) | locked keychain, SSH session without unlock | supported |
+ * | Windows | Credential Manager | service account, non-interactive/restricted logon | supported (named pipe) |
+ * | Desktop Linux | Secret Service (GNOME Keyring, KWallet, KeePassXC) | locked collection, no provider | supported |
+ * | Headless/remote Linux | usually no Secret Service on a D-Bus session bus | common | supported, recommended |
+ * | Other / no native binding | none | always | supported |
+ *
+ * - No store never implies plaintext fallback, and headless Linux without a
+ *   keyring is not "unsupported": the session-only companion is the supported path.
+ * - Refresh: refresh_pending is recorded (OS store or memory) before the token
+ *   exchange; an unconfirmed refresh is never retried blindly, in either mode.
+ * - Concurrent login: persistent mode serializes through the OS-owned auth lock;
+ *   session mode serializes in the companion process, and only one companion
+ *   may serve a platform origin per user (companion.lock).
+ * - Cancellation: an interrupted device poll leaves the attempt marked uncertain
+ *   (persistent) or discards it with the process (session); the single-use
+ *   device code is never exchanged twice.
+ * - Private files: the state directory is 0700 and owned by the user; the
+ *   companion nonce is 0600 (exclusive create) and removed on shutdown; the
+ *   socket is 0600 inside a 0700 directory. On Windows these rely on the
+ *   user-profile ACL. No credential is ever written to a file.
+ */
+import { CliError } from './http.js';
+import { probeCredentialStore, setCredentialMode } from './credentials.js';
+import { companionPresent, companionRequest } from './native/companion-ipc.js';
+const SESSION_ONLY = 'Use `firedrill init --session-only` to keep the sign-in only in memory for one companion process';
+const OR_SESSION_ONLY = 'Or use `firedrill init --session-only` to keep the sign-in only in memory for one companion process.';
+const NO_FILE = 'Credentials are never saved to a plaintext file.';
+function platformBackend() {
+    if (process.platform === 'darwin')
+        return 'macos-keychain';
+    if (process.platform === 'win32')
+        return 'windows-credential-manager';
+    if (process.platform === 'linux')
+        return 'linux-secret-service';
+    return 'none';
+}
+/** Linux session without a desktop or session bus: SSH, container, CI or server. */
+export function headlessLinuxSession(env = process.env) {
+    if (process.platform !== 'linux')
+        return false;
+    const desktop = !!(env.DISPLAY || env.WAYLAND_DISPLAY);
+    const bus = !!env.DBUS_SESSION_BUS_ADDRESS;
+    return !bus && !desktop || !desktop && !!(env.SSH_CONNECTION || env.SSH_TTY);
+}
+function remediation(backend, reason, headless) {
+    if (reason === 'unsupported_platform' || reason === 'binding_unavailable')
+        return `No supported OS credential store is available for this platform build. ${SESSION_ONLY}. ${NO_FILE}`;
+    if (reason === 'ambiguous_entry')
+        return `More than one OS credential store item matches Firedrill's sign-in entry. Remove the duplicate "run.firedrill.simulation" items in your credential store, then sign in again. ${OR_SESSION_ONLY} ${NO_FILE}`;
+    if (backend === 'macos-keychain')
+        return reason === 'store_locked'
+            ? `Unlock the macOS login keychain (Keychain Access, or \`security unlock-keychain\` over SSH) and allow Firedrill access when asked, then sign in again. ${OR_SESSION_ONLY} ${NO_FILE}`
+            : `The macOS Keychain could not be used from this session. Sign in from a logged-in user session or unlock it with \`security unlock-keychain\`. ${OR_SESSION_ONLY} ${NO_FILE}`;
+    if (backend === 'windows-credential-manager')
+        return `Windows Credential Manager is unavailable in this session (for example a service account, a restricted or non-interactive logon, or a stopped Credential Manager service). Sign in from an interactive Windows user session. ${OR_SESSION_ONLY} ${NO_FILE}`;
+    if (headless)
+        return `No Secret Service is reachable in this headless or remote Linux session. ${SESSION_ONLY}, or start and unlock a Secret Service provider (for example gnome-keyring-daemon or KeePassXC with Secret Service integration) on a D-Bus session bus. ${NO_FILE}`;
+    return reason === 'store_locked'
+        ? `Unlock your login keyring (Secret Service), then sign in again. ${OR_SESSION_ONLY} ${NO_FILE}`
+        : `No Secret Service provider answered on this desktop session. Install or enable one (GNOME Keyring, KWallet with Secret Service, or KeePassXC), then sign in again. ${OR_SESSION_ONLY} ${NO_FILE}`;
+}
+/**
+ * Probe the persistent store without saving any secret. verifyWrite also stores
+ * and deletes a fixed non-secret marker (use before login so a store that cannot
+ * be written is reported before the browser ceremony starts).
+ */
+export async function credentialStoreStatus(options = {}) {
+    const backend = platformBackend(), headless = headlessLinuxSession();
+    if (backend === 'none')
+        return { available: false, backend, reason: 'unsupported_platform', headless, remediation: remediation(backend, 'unsupported_platform', headless) };
+    const probe = await probeCredentialStore({ write: options.verifyWrite === true, signal: options.signal });
+    if (probe.ok)
+        return { available: true, backend, remediation: null, reason: null, headless };
+    const effective = probe.failure === 'binding_unavailable' ? 'none' : backend;
+    return { available: false, backend: effective, reason: probe.failure, headless, remediation: remediation(effective, probe.failure, headless) };
+}
+async function runningCompanion(signal) {
+    if (!await companionPresent())
+        return null;
+    try {
+        return await companionRequest('status', signal);
+    }
+    catch (error) {
+        // A crashed, suspended, unverifiable or unsafe companion is not usable for
+        // mode selection. Treating it as absent keeps persistent-mode commands
+        // working; any later companion request still refuses with its own code.
+        if (error instanceof CliError && error.code.startsWith('companion_'))
+            return null;
+        throw error;
+    }
+}
+/**
+ * Resolve and set this process's credential mode, once, before any credential access.
+ * Precedence: --session-only / --persistent flags, then FIREDRILL_CREDENTIAL_MODE,
+ * then a running session-only companion, else persistent.
+ * companion: 'require' (this process becomes the companion), 'if-session' (init: require when the
+ * resolved mode is session-only),
+ * 'if-absent' (run: become the companion unless one already serves), 'never' (all other commands).
+ */
+export async function configureCredentialMode(options = {}) {
+    if (options.sessionOnly && options.persistent)
+        throw new CliError('credential_mode_conflict', 'Choose either --session-only or --persistent. No sign-in was started.', 2);
+    const env = process.env.FIREDRILL_CREDENTIAL_MODE;
+    if (env !== undefined && env !== 'session' && env !== 'persistent')
+        throw new CliError('credential_mode_invalid', 'Set FIREDRILL_CREDENTIAL_MODE to session or persistent, or unset it. No credential mode was selected.', 2);
+    const fromEnv = env;
+    const explicit = options.sessionOnly ? 'session' : options.persistent ? 'persistent' : fromEnv ?? null;
+    const requested = options.companion ?? 'never';
+    // An explicit persistent selection for a non-companion command needs nothing
+    // from a running companion, so it never waits on one.
+    const running = explicit === 'persistent' && requested === 'never' ? null : await runningCompanion(options.signal);
+    const mode = explicit ?? (running?.mode === 'session' ? 'session' : 'persistent');
+    // 'if-session' (init): become the companion exactly when the resolved mode is
+    // session-only, whether it came from --session-only or FIREDRILL_CREDENTIAL_MODE.
+    const role = requested === 'if-session' ? (mode === 'session' ? 'require' : 'never') : requested;
+    let companion = false;
+    if (role === 'require') {
+        if (running)
+            throw new CliError('companion_already_running', running.mode === 'session'
+                ? 'A session-only companion is already signed in for this platform. Use it from other terminals, or stop it with `firedrill logout` first. No second sign-in was started.'
+                : 'A Firedrill companion is already running for this platform. Stop it before starting another. No second sign-in was started.', 2);
+        companion = true;
+    }
+    else if (role === 'if-absent') {
+        if (running && running.mode !== mode)
+            throw new CliError('companion_mode_conflict', `A ${running.mode === 'session' ? 'session-only' : 'persistent'} companion is already running. Stop it or use the same credential mode. No work was started.`, 2);
+        companion = !running;
+    }
+    setCredentialMode(mode, { companion });
+    return { mode, companion, running };
+}