firedrill-run 2.2.5 → 3.0.1

package/dist/cli/src/simple/reassessment.js

@@ -0,0 +1,323 @@
+// `firedrill report <campaign> drill <drill> reassess ...`: a separately quoted,
+// human-approved new evaluation of one finished drill's retained evidence.
+// The agent is never run again and no local compute is charged. The drill's
+// original result stays exactly as it was; each reassessment is its own attempt
+// with its own criterion results, never merged into the original result or the
+// campaign's quality figures.
+//
+// Root reviews it under a request key printed before anything is sent and
+// freezes an estimate at once; nothing is reserved or evaluated until the human
+// approves that exact estimate. A rerun with the printed key continues the
+// original review, never a second one, and a lost approval is read back, never
+// charged twice. A reviewed reassessment can be cancelled unused; an approved one
+// cannot. Only the member who ran the drill can review one (root reads only that
+// member's retained basis), only the member who reviewed one can approve or
+// cancel it, and anyone in the workspace can read them.
+import { randomUUID } from 'node:crypto';
+import { approveCredits } from './credit-approval.js';
+import { CliError } from '../http.js';
+import { selectOne, terminalText } from '../prompts.js';
+import { getNativeEvaluationReport } from '../native/cloud-resources.js';
+import { errorCode, isTransient, retryTransient } from '../native/control-plane.js';
+import { admitReassessment, cancelReassessment, getReassessment, listReassessmentCriteria, listReassessments, reassessmentId, recoverReassessment, reviewReassessment, } from '../native/reassessments.js';
+import { criterionLine, drillSlot, nativeCampaign, scopeOf } from './native-report.js';
+import { amount } from './plan-apply.js';
+/** The verbs this module owns under `report <campaign> drill <drill>`. */
+export const REASSESSMENT_VERBS = new Set(['reassess', 'reassessments', 'reassessment', 'reassessment-request', 'cancel-reassessment']);
+/** An estimate this close to expiry is not approved: approval would race it. */
+const QUOTE_MARGIN_MS = 60_000;
+const RECOVER_MS = 15_000;
+/** Original evaluation states with a frozen basis and nothing left to evaluate. */
+const FINISHED = new Set(['complete', 'needs_attention']);
+const POLICY_REFUSALS = new Set(['native_evaluation_policy_required', 'assessment_configuration_required',
+    'native_funding_policy_unavailable', 'billing_credit_policy_unavailable']);
+const policyRefusal = (error) => error instanceof CliError && error.httpStatus === 503 && POLICY_REFUSALS.has(error.code);
+const uncertainResponse = (error) => !policyRefusal(error) && (isTransient(error)
+    || ['request_failed', 'connection_uncertain', 'response_unavailable', 'native_response_unconfirmed'].includes(errorCode(error) ?? ''));
+const SEPARATE_NOTE = 'A reassessment is a new evaluation of the drill\'s retained evidence: the agent is not run again and no local compute is '
+    + 'charged. Its results are its own, kept apart from the drill\'s original result and the campaign\'s quality figures, and never combined with them. '
+    + 'Each scored criterion is assessed 0-100 against its own threshold. A criterion without a score is not assessed; inspect its status for the reason. It is not a zero or an agent failure.';
+/** Whether these `report` arguments name a reassessment command (checked before any request). */
+export function reassessmentShape(args) {
+    return args[1] === 'drill' && args[2] !== undefined && REASSESSMENT_VERBS.has(args[3] ?? '');
+}
+function stateText(row) {
+    switch (row.state) {
+        case 'reviewed': return 'reviewed, not approved (nothing reserved or evaluated)';
+        case 'evaluating': return 'approved, evaluating';
+        case 'completed': return 'completed';
+        case 'cancelled': return row.basis_id === null ? 'cancelled before approval (nothing reserved or evaluated)'
+            : 'stopped by Firedrill after approval, before every criterion was evaluated (no results are shown for it)';
+    }
+}
+function evaluatorText(row) {
+    switch (row.profile_comparison) {
+        case 'same': return 'the same evaluator as the original result';
+        case 'different': return 'a different evaluator from the one behind the original result, so scores may differ for that reason too';
+        case 'unknown': return 'not comparable with the original result (it made no scoring request whose evaluator could be compared)';
+    }
+}
+const estimate = (row) => amount(row.quote.maximum_units, row.quote.credit_scale, row.quote.denomination);
+function reassessmentText(drill, row) {
+    return [
+        `Reassessment ${row.id} of drill ${drill}: ${stateText(row)}`,
+        `  ${row.criteria_count} criteria from the original evaluation ${row.source_basis_id}; evaluator: ${evaluatorText(row)}`,
+        `  Request ${row.request_key}, reviewed ${terminalText(row.created_at)}${row.completed_at ? `, ended ${terminalText(row.completed_at)}` : ''}`,
+        `  Estimate: up to ${estimate(row)} (estimate ${row.quote.id})`,
+    ].join('\n');
+}
+function quoteText(drill, row) {
+    return [
+        `Reassess drill ${drill}: a new evaluation of its ${row.criteria_count} criteria over its retained evidence.`,
+        'The agent is not run again and no local compute is charged. The original result stays as it is; this one is kept separately.',
+        `Evaluator: ${evaluatorText(row)}.`,
+        `Evaluation estimate (maximum, reserved only once approved): ${estimate(row)}`,
+        `Estimate expires: ${terminalText(row.quote.expires_at)}`,
+    ].join('\n');
+}
+function pageNumber(value) {
+    if (value === undefined)
+        return undefined;
+    if (!/^[1-9][0-9]{0,6}$/.test(value))
+        throw new CliError('arguments_invalid', 'Use --page with a positive page number.', 2);
+    return Number(value);
+}
+const tty = (options) => !options.json && !!process.stdin.isTTY && !!process.stderr.isTTY;
+/** Root admits and cancels only the reviewer's own reassessment; after a successful read, its refusal says so. */
+const reviewerOnly = (error) => {
+    if (errorCode(error) === 'native_reassessment_unavailable') {
+        throw new CliError('native_reassessment_owner_only', 'Only the member who reviewed this reassessment can approve or cancel it, and only while '
+            + 'its original evaluation is retained. Nothing was reserved or changed.', 2, error instanceof CliError ? error.httpStatus : null);
+    }
+    throw error;
+};
+/** Each verb's arguments and flags, checked before anything is read or sent. */
+export function checkReassessmentArguments(args, options) {
+    const [, , , verb, value, sub] = args;
+    const takes = {
+        reassess: ['request', 'quote', 'approve', 'approveCredits'], reassessments: ['page'], reassessment: sub === 'results' ? ['page'] : [],
+        'reassessment-request': [], 'cancel-reassessment': ['approve'],
+    };
+    const flags = { request: '--request-key', quote: '--usage-quote',
+        approve: '--approve-assessment', approveCredits: '--approve-credits', page: '--page' };
+    const extra = Object.keys(flags)
+        .filter((flag) => options[flag] !== undefined && options[flag] !== false && !takes[verb]?.includes(flag));
+    if (extra.length)
+        throw new CliError('arguments_invalid', `report <campaign> drill <drill> ${verb} does not take ${extra.map((flag) => flags[flag]).join(', ')}.`, 2);
+    const valid = verb === 'reassess' || verb === 'reassessments' ? args.length === 4
+        : verb === 'reassessment' ? args.length === 5 || (args.length === 6 && sub === 'results')
+            : args.length === 5;
+    if (!valid) {
+        throw new CliError('arguments_invalid', 'Use report <campaign> drill <drill> reassess, reassessments, reassessment <reassessment-id> [results], '
+            + 'reassessment-request <key> or cancel-reassessment <reassessment-id>.', 2);
+    }
+    if (verb === 'reassess' && options.quote !== undefined && options.request === undefined) {
+        throw new CliError('arguments_invalid', 'Use --usage-quote with the --request-key that was printed with it. Nothing was sent.', 2);
+    }
+    // Every id and page is checked here, before the workspace or campaign is read.
+    if (options.request !== undefined)
+        reassessmentId(options.request, 'request key');
+    if (options.quote !== undefined)
+        reassessmentId(options.quote, 'quote id');
+    if (value !== undefined)
+        reassessmentId(value, verb === 'reassessment-request' ? 'request key' : 'reassessment id');
+    pageNumber(options.page);
+}
+/**
+ * `reassess [--request-key <key>] [--usage-quote <quote-id>] [--approve-assessment]`.
+ * The review is continued by its key; approval names the exact estimate the human saw.
+ */
+async function reassess(scope, drill, assignmentId, command, options, emit) {
+    const signal = options.signal;
+    const quoteGiven = options.quote === undefined ? undefined : reassessmentId(options.quote, 'quote id');
+    const requestKey = options.request === undefined ? randomUUID() : reassessmentId(options.request, 'request key');
+    const recovery = `${command} reassess --request-key ${requestKey}`;
+    const read = `${command} reassessment-request ${requestKey}`;
+    // A reassessment already reviewed under this key is continued, never reviewed again.
+    let row = options.request === undefined ? null : await recoverReassessment(scope, { assignmentId, requestKey, signal });
+    if (!row) {
+        const original = await getNativeEvaluationReport(scope, { assignmentId, signal });
+        if (original.basis_id === null || !FINISHED.has(original.status) || !original.criteria_total || original.pending !== 0) {
+            throw new CliError('native_reassessment_not_ready', 'Only a drill whose original evaluation has finished can be reassessed; this one is '
+                + `${terminalText(original.status.replace(/_/g, ' '))}${original.pending ? ' with criteria still pending' : original.criteria_total ? '' : ' with no criteria evaluated'}. `
+                + `Check it with ${command} results. Nothing was sent.`, 2);
+        }
+        emit('native_reassessment_request', { drill_id: drill, assignment_id: assignmentId, basis_id: original.basis_id, request_key: requestKey }, `Reassessment request: ${requestKey}\nIf interrupted, continue with ${recovery}. Do not start again under a new key.`);
+        try {
+            row = await reviewReassessment(scope, { assignmentId, basisId: original.basis_id, requestKey, signal });
+        }
+        catch (error) {
+            // Root reviews only from the drill runner's own retained basis; the report above was readable, so this is who, or retention.
+            if (errorCode(error) === 'native_evaluation_basis_unavailable') {
+                throw new CliError('native_reassessment_runner_only', 'Only the member who ran this drill can reassess it, and only while its original '
+                    + 'evaluation evidence is retained. Nothing was reserved or evaluated.', 2, error instanceof CliError ? error.httpStatus : null);
+            }
+            // Only an unanswered (or cancelled) review may have landed; a refusal is reported as it is. A review reserves nothing.
+            if (policyRefusal(error) || (!signal.aborted && !uncertainResponse(error)))
+                throw error;
+            row = await recoverReassessment(scope, { assignmentId, requestKey, signal: AbortSignal.timeout(RECOVER_MS) }).catch(() => null);
+            if (!row) {
+                throw new CliError('native_reassessment_unconfirmed', `The reassessment request was not confirmed. Nothing is reserved by a review. `
+                    + `Read it with ${read}, or continue it with ${recovery}.`);
+            }
+        }
+    }
+    const reviewed = row;
+    if (reviewed.state !== 'reviewed') {
+        // Already approved or closed: shown as it is, never approved again.
+        emit('native_reassessment', reviewed, reassessmentText(drill, reviewed) + (reviewed.state === 'cancelled'
+            ? '\nThis reassessment is closed. To reassess the drill, start a new one without --request-key.'
+            : `\nResults: ${command} reassessment ${reviewed.id} results`));
+        return;
+    }
+    const cancel = `${command} cancel-reassessment ${reviewed.id}`;
+    if (Date.parse(reviewed.quote.expires_at) - Date.now() <= QUOTE_MARGIN_MS) {
+        throw new CliError('native_reassessment_quote_expired', 'This estimate has expired or expires within a minute. Nothing was reserved or evaluated. '
+            + `Close this review with ${cancel} --approve-assessment, then start a new reassessment without --request-key.`, 2);
+    }
+    if (quoteGiven !== undefined && quoteGiven !== reviewed.quote.id) {
+        throw new CliError('idempotency_conflict', `That estimate is not this reassessment's (its estimate is ${reviewed.quote.id}). Nothing was reserved or evaluated.`, 2);
+    }
+    let approved = options.approve === true && (!reviewed.quote.credit_approval_required || quoteGiven === reviewed.quote.id);
+    emit('native_reassessment_quote', { ...reviewed, drill_id: drill }, quoteText(drill, reviewed));
+    if (!approved && tty(options)) {
+        approved = await selectOne('Reassess this drill?', [
+            { value: false, label: 'Not now', detail: 'Nothing is reserved or evaluated. The review stays open until it is closed or its estimate expires.' },
+            { value: true, label: 'Reassess it', detail: 'Reserves up to the estimate above and evaluates the retained evidence again. The agent is not run again.' },
+        ], signal);
+    }
+    if (!approved) {
+        throw new CliError('assessment_consent_required', 'Nothing was reserved or evaluated. Show the human this estimate; after they approve it: '
+            + `${recovery} --usage-quote ${reviewed.quote.id} --approve-assessment\nIf they decline, close the review: ${cancel} --approve-assessment`, 2);
+    }
+    if (!Number.isFinite(Date.parse(reviewed.quote.expires_at)) || Date.parse(reviewed.quote.expires_at) - Date.now() <= QUOTE_MARGIN_MS) {
+        throw new CliError('native_reassessment_quote_expired', 'This estimate expired or is too close to expiry after approval. Nothing was submitted. '
+            + `Close this review with ${cancel} --approve-assessment, then review a new estimate.`, 2);
+    }
+    const creditApproval = await approveCredits([reviewed.quote], options, tty(options), `${recovery} --usage-quote ${reviewed.quote.id} --approve-assessment`);
+    let admitted;
+    try {
+        admitted = await retryTransient(() => admitReassessment(scope, { reassessment: reviewed, signal, creditApproval }), {
+            signal, attempts: 3, onTransient: (error) => { if (policyRefusal(error))
+                throw error; },
+        });
+    }
+    catch (error) {
+        if (signal.aborted)
+            throw error;
+        if (policyRefusal(error))
+            throw error;
+        // An unanswered approval may have landed: the reassessment says, and nothing is admitted or charged twice.
+        const current = await getReassessment(scope, { assignmentId, reassessmentId: reviewed.id, signal: AbortSignal.timeout(RECOVER_MS) }).catch(() => null);
+        if (!current || current.state === 'reviewed') {
+            if (error instanceof CliError && error.httpStatus !== null && !uncertainResponse(error))
+                throw error;
+            throw new CliError('native_reassessment_unconfirmed', `The approval was not confirmed. Check ${command} reassessment ${reviewed.id}; `
+                + `if it is still reviewed, run ${recovery} --usage-quote ${reviewed.quote.id} --approve-assessment. It is never charged twice.`);
+        }
+        admitted = current;
+    }
+    emit('native_reassessment', admitted, reassessmentText(drill, admitted) + (admitted.state === 'cancelled'
+        ? admitted.basis_id === null ? '\nIt was closed before approval, so nothing was evaluated.'
+            : '\nIt stopped after approval. Any confirmed evaluation usage remains recorded separately.'
+        : `\nThe new evaluation runs over the retained evidence only. Results: ${command} reassessment ${admitted.id} results`));
+}
+/**
+ * `report <campaign> drill <drill> reassess [--request-key <key>] [--usage-quote <quote-id>] [--approve-assessment]
+ *  | reassessments [--page <n>] | reassessment <id> [results [--page <n>]] | reassessment-request <key>
+ *  | cancel-reassessment <id> [--approve-assessment]`.
+ */
+export async function reassessmentCommand(args, options, emit) {
+    checkReassessmentArguments(args, options);
+    const [campaignId, , drillId, verb, value, sub] = args;
+    const signal = options.signal;
+    const scope = await scopeOf(options);
+    const campaign = await nativeCampaign(scope, campaignId, signal);
+    if (!campaign) {
+        throw new CliError('native_campaign_not_found', 'That is not a simulation in this workspace that can be reassessed. Find simulations with firedrill report.', 2);
+    }
+    const slot = await drillSlot(scope, campaign.campaign_id, drillId, signal);
+    const assignmentId = slot.assignment_id;
+    const drill = slot.drill_id ?? drillId;
+    const command = `firedrill report ${campaign.campaign_id} drill ${drill}`;
+    if (verb === 'reassess')
+        return reassess(scope, drill, assignmentId, command, options, emit);
+    if (verb === 'reassessments') {
+        const page = await listReassessments(scope, { assignmentId, page: pageNumber(options.page), signal });
+        emit('native_reassessments', { drill_id: drill, assignment_id: assignmentId, ...page }, [
+            `Reassessments of drill ${drill}, page ${page.page} (${page.count} in all):`,
+            ...page.results.map((one) => `  ${one.id}  ${stateText(one)}  ${one.criteria_count} criteria  ${terminalText(one.created_at)}`),
+            page.results.length ? null : '  none',
+            page.next ? `More: --page ${page.page + 1}` : null,
+            page.results.length ? `Read one: ${command} reassessment <reassessment-id> [results]` : null,
+            `The original result: ${command} results`,
+            `Reassess the drill: ${command} reassess`,
+        ].filter((line) => line !== null).join('\n'));
+        return;
+    }
+    if (verb === 'reassessment-request') {
+        const requestKey = reassessmentId(value, 'request key');
+        const row = await recoverReassessment(scope, { assignmentId, requestKey, signal });
+        if (!row) {
+            emit('native_reassessment_request', { drill_id: drill, assignment_id: assignmentId, request_key: requestKey, state: 'not_found' }, `None of your reassessments of this drill is recorded under request ${requestKey}. An unanswered request may still arrive; `
+                + `a review reserves nothing. Continue it with ${command} reassess --request-key ${requestKey}.`);
+            return;
+        }
+        emit('native_reassessment', row, reassessmentText(drill, row));
+        return;
+    }
+    const id = reassessmentId(value, 'reassessment id');
+    const row = await getReassessment(scope, { assignmentId, reassessmentId: id, signal }).catch((error) => {
+        if (error instanceof CliError && error.httpStatus === 404) {
+            throw new CliError('native_reassessment_not_found', `That is not a reassessment of this drill. List them with ${command} reassessments.`, 2);
+        }
+        throw error;
+    });
+    if (verb === 'reassessment' && sub === 'results') {
+        const page = pageNumber(options.page);
+        const criteria = await listReassessmentCriteria(scope, { assignmentId, reassessmentId: row.id, page, signal });
+        const shown = criteria.page;
+        emit('native_reassessment_results', { reassessment: row, criteria }, [
+            reassessmentText(drill, row),
+            ...criteria.results.length ? [
+                `Criteria of this reassessment, page ${shown} (${criteria.count} in all):`,
+                ...criteria.results.map((one) => criterionLine(one, true)),
+                criteria.next ? `More: --page ${shown + 1}` : null,
+            ] : [row.state === 'reviewed' ? `No results: it has not been approved. Approve it with ${command} reassess --request-key ${row.request_key}`
+                    : row.state === 'cancelled' ? 'No results are shown for a cancelled reassessment.' : 'No criterion results yet.'],
+            `The original result: ${command} results`,
+            SEPARATE_NOTE,
+        ].filter((line) => line !== null).join('\n'));
+        return;
+    }
+    if (verb === 'reassessment' || row.state !== 'reviewed') {
+        emit('native_reassessment', row, reassessmentText(drill, row) + (row.state === 'reviewed'
+            ? `\nApprove it: ${command} reassess --request-key ${row.request_key}\nClose it unused: ${command} cancel-reassessment ${row.id}`
+            : verb === 'cancel-reassessment' ? `\nThis reassessment is ${stateText(row)}, so there is nothing to cancel; nothing was sent.`
+                : row.state === 'cancelled' ? '' : `\nResults: ${command} reassessment ${row.id} results`));
+        return;
+    }
+    let approved = options.approve === true;
+    if (!approved && tty(options)) {
+        approved = await selectOne('Cancel this unused reassessment review?', [
+            { value: false, label: 'Not now', detail: 'Nothing is sent.' },
+            { value: true, label: 'Cancel it', detail: 'Its estimate can no longer be approved. Nothing was reserved or evaluated for it.' },
+        ], signal);
+    }
+    if (!approved)
+        throw new CliError('assessment_consent_required', `Nothing was sent. After the human approves: ${command} cancel-reassessment ${row.id} --approve-assessment`, 2);
+    // Cancelling is idempotent; an approved reassessment is refused by root and read back, never undone.
+    let closed;
+    try {
+        closed = await retryTransient(() => cancelReassessment(scope, { assignmentId, reassessmentId: row.id, signal }), { signal, attempts: 3 });
+    }
+    catch (error) {
+        if (errorCode(error) !== 'native_reassessment_already_admitted')
+            reviewerOnly(error);
+        closed = await getReassessment(scope, { assignmentId, reassessmentId: row.id, signal });
+    }
+    emit('native_reassessment', closed, reassessmentText(drill, closed) + (closed.state === 'cancelled'
+        ? closed.basis_id === null ? '\nCancelled before approval. Nothing was reserved or evaluated.'
+            : '\nStopped after approval. Any confirmed evaluation usage remains recorded separately.'
+        : `\nIt had already been approved, so nothing was cancelled or undone. Results: ${command} reassessment ${closed.id} results`));
+}

package/dist/cli/src/simple/register.js

@@ -0,0 +1,123 @@
+import { CliError } from '../http.js';
+import { terminalText } from '../prompts.js';
+import { selectedWorkspace } from '../world-access.js';
+import { declaredAgentName, declaredNameRecorded, getNativeDescriptor, listNativeDescriptors, registerNativeAgent, registrationKey, reviseNativeDescriptor } from '../native/registration.js';
+import { normalizeDescriptor } from '../native/canonical.js';
+import { answerLost, recoverLostWrite } from '../native/metadata-requests.js';
+import { metadataRequestCommand } from './metadata-requests.js';
+import { readJsonInput } from './plan-apply.js';
+const unconfirmed = () => new CliError('native_registration_unconfirmed', 'The recovered registration does not match this descriptor. Nothing else was sent.', 2);
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function registeredText(receipt) {
+    return `Agent ${receipt.agent_id}.\n${revisionText(receipt.descriptor)}`;
+}
+const scopeOf = (options) => selectedWorkspace({ workspace: options.workspace, signal: options.signal,
+    interactive: !options.json && !!process.stdin.isTTY && !!process.stderr.isTTY, openBrowser: options.openBrowser && !options.json });
+function revisionText(row) {
+    return [`Agent: ${row.agent_id}`, `Descriptor revision ${row.revision}: ${row.id}`, `Digest: ${row.descriptor_sha256}`,
+        `Serial execution required: ${row.requires_serial_execution ? 'yes' : 'no'}`, `Recorded: ${terminalText(row.created_at)}`,
+        ...(row.caller_attribution ? [`Recorded from: ${row.caller_attribution.channel === 'management_mcp' ? 'remote MCP' : row.caller_attribution.channel}`
+                + (row.caller_attribution.declared_agent_name ? `, by a coding agent that called itself ${terminalText(row.caller_attribution.declared_agent_name)} (self-reported, not verified)` : '')] : []),
+        ...(row.startup_order ? [`Startup order: ${row.startup_order.map(terminalText).join(', ')}`] : [])].join('\n');
+}
+/**
+ * Registers declared target metadata (no source upload, no paths, no secrets,
+ * nothing executes). Without --agent it creates a local agent; with --agent it
+ * records the next immutable descriptor revision.
+ */
+export async function registerCommand(args, options, emit) {
+    if (args[0] === 'request' || args[0] === 'withdraw-request') {
+        // The original first registration of an agent, by its request key. A descriptor revision's request is under `descriptors`.
+        if (args.length !== 2 || options.descriptor !== undefined || options.name !== undefined || options.agent !== undefined
+            || options.expectedRevision !== undefined || options.request !== undefined)
+            throw new CliError('arguments_invalid', 'Use firedrill register request|withdraw-request <request-key>. For a descriptor revision use firedrill descriptors request|withdraw-request <request-key> --agent <id>.', 2);
+        if (options.declaredAgentName !== undefined)
+            throw new CliError('arguments_invalid', '--declared-agent-name applies to a registration or revision, not to reading or withdrawing one.', 2);
+        const scope = await scopeOf(options);
+        await metadataRequestCommand(args[0], { kind: 'agent', requestKey: args[1] }, scope, options, emit, registeredText, `firedrill register withdraw-request ${args[1].toLowerCase()}`);
+        return;
+    }
+    if (options.approve !== undefined)
+        throw new CliError('arguments_invalid', '--approve-change applies to register withdraw-request only. Nothing was submitted.', 2);
+    const revising = options.agent !== undefined;
+    if (args.length || !options.descriptor || (revising ? options.name !== undefined || options.expectedRevision === undefined
+        : options.name === undefined || options.expectedRevision !== undefined))
+        throw new CliError('arguments_invalid', 'Use firedrill register --descriptor <path|-> --name <name>, or --descriptor <path|-> --agent <id> --expected-revision <n> for a new revision. Nothing was submitted.', 2);
+    if (revising && !/^(0|[1-9][0-9]{0,8})$/.test(options.expectedRevision ?? ''))
+        throw new CliError('native_revision_invalid', 'Use the latest descriptor revision number. Nothing was submitted.', 2);
+    // Checked before anything is read or sent; a replay with --request must repeat the same name (or none).
+    const declared = declaredAgentName(options.declaredAgentName);
+    const descriptor = JSON.parse(await readJsonInput(options.descriptor, 'the local descriptor', options.signal));
+    const requestKey = registrationKey(options.request);
+    const scope = await scopeOf(options);
+    // Announce the key before any request so an interrupted attempt can be replayed exactly.
+    if (options.json)
+        emit('request_prepared', { request_key: requestKey, declared_agent_name: declared ?? null }, '');
+    else
+        process.stderr.write(`Request key: ${requestKey} (rerun with --request ${requestKey}${declared === undefined ? '' : ' and the same --declared-agent-name'} to replay this exact registration)\n`);
+    // A lost answer is read back by its key: never sent again here, never under a new key.
+    const digest = () => normalizeDescriptor(descriptor).descriptor_sha256;
+    if (revising) {
+        let row;
+        try {
+            row = await reviseNativeDescriptor(scope, { agentId: options.agent, expectedRevision: Number(options.expectedRevision),
+                descriptor, requestKey, declaredAgentName: declared, signal: options.signal });
+        }
+        catch (error) {
+            if (!answerLost(error) || options.signal.aborted || !UUID.test(options.agent))
+                throw error;
+            const recovered = await recoverLostWrite(scope, { kind: 'descriptor', requestKey, agentId: options.agent }, { replay: `the same command with --request ${requestKey}`, withdraw: `firedrill descriptors withdraw-request ${requestKey} --agent ${options.agent.toLowerCase()}` });
+            if (recovered.revision !== Number(options.expectedRevision) + 1 || recovered.descriptor_sha256 !== digest()
+                || !declaredNameRecorded(recovered, declared))
+                throw unconfirmed();
+            row = { ...recovered, request_key: requestKey };
+        }
+        emit('native_descriptor', row, `${revisionText(row)}\nRequest key: ${row.request_key}\nMetadata only. Nothing was uploaded or started.`);
+        return;
+    }
+    let receipt;
+    try {
+        receipt = await registerNativeAgent(scope, { name: options.name, descriptor, requestKey, declaredAgentName: declared, signal: options.signal });
+    }
+    catch (error) {
+        if (!answerLost(error) || options.signal.aborted)
+            throw error;
+        const recovered = await recoverLostWrite(scope, { kind: 'agent', requestKey }, { replay: `the same command with --request ${requestKey}`, withdraw: `firedrill register withdraw-request ${requestKey}` });
+        if (recovered.descriptor.descriptor_sha256 !== digest() || !declaredNameRecorded(recovered.descriptor, declared))
+            throw unconfirmed();
+        // The receipt contains the descriptor, not the original registration name.
+        // A lost conflict for a changed name must not be reported as a new success.
+        emit('native_request', { kind: 'agent', request_key: requestKey, state: 'committed', receipt: recovered,
+            submitted_change_confirmed: false }, `Recovered original agent ${recovered.agent_id}.\n${revisionText(recovered.descriptor)}\nRequest key: ${requestKey}\nThe submitted registration name is not confirmed. Inspect the original agent before continuing.`);
+        return;
+    }
+    emit('native_agent', receipt, `Registered agent ${receipt.agent_id}.\n${revisionText(receipt.descriptor)}\nRequest key: ${receipt.request_key}`
+        + '\nMetadata only. Nothing was uploaded or started. Prepare and approve a cloud campaign, then use firedrill run --campaign <campaign-id> --plan <file> --descriptor <file>.');
+}
+export async function descriptorsCommand(args, options, emit) {
+    if (args[0] === 'request' || args[0] === 'withdraw-request') {
+        // One descriptor revision's original request, by its key, for the agent it was recorded on.
+        if (args.length !== 2 || !options.agent || options.descriptor !== undefined || options.page !== undefined)
+            throw new CliError('arguments_invalid', 'Use firedrill descriptors request|withdraw-request <request-key> --agent <id>.', 2);
+        const scope = await scopeOf(options);
+        await metadataRequestCommand(args[0], { kind: 'descriptor', requestKey: args[1], agentId: options.agent }, scope, options, emit, revisionText, `firedrill descriptors withdraw-request ${args[1].toLowerCase()} --agent ${options.agent.toLowerCase()}`);
+        return;
+    }
+    if (options.approve !== undefined)
+        throw new CliError('arguments_invalid', '--approve-change applies to descriptors withdraw-request only.', 2);
+    if (args.length || !options.agent || options.descriptor !== undefined && options.page !== undefined)
+        throw new CliError('arguments_invalid', 'Use firedrill descriptors --agent <id> [--page <n>], or --agent <id> --descriptor <id>.', 2);
+    if (options.page !== undefined && !/^[1-9][0-9]{0,8}$/.test(options.page))
+        throw new CliError('native_page_invalid', 'Use a page number of 1 or more.', 2);
+    const scope = await scopeOf(options);
+    if (options.descriptor !== undefined) {
+        const row = await getNativeDescriptor(scope, { agentId: options.agent, descriptorId: options.descriptor, signal: options.signal });
+        emit('native_descriptor', row, revisionText(row));
+        return;
+    }
+    const page = Number(options.page ?? '1');
+    const result = await listNativeDescriptors(scope, { agentId: options.agent, page, signal: options.signal });
+    emit('native_descriptors', result, [result.results.map(row => `Revision ${row.revision}  ${row.id}  ${row.descriptor_sha256}  ${terminalText(row.created_at)}`).join('\n')
+            || 'No descriptor revisions for this agent.', `Page ${page}, ${result.count} revisions.`,
+        ...(result.next ? [`Next: firedrill descriptors --agent ${options.agent} --page ${page + 1}`] : [])].join('\n'));
+}

package/dist/cli/src/simple/run.js

@@ -0,0 +1,122 @@
+import { CliError } from '../http.js';
+import { login } from '../auth.js';
+import { credentialMode, isCredentialCompanion, loadCredentials } from '../credentials.js';
+import { terminalText } from '../prompts.js';
+import { selectedWorkspace } from '../world-access.js';
+import { approvePlan, parsePlan, planDigest } from '../native/plan.js';
+import { localSecretBindings } from '../native/local-secrets.js';
+import { normalizeDescriptor } from '../native/canonical.js';
+import { httpControlPlane } from '../native/control-plane.js';
+import { detectCapabilities } from '../native/drivers/index.js';
+import { runCompanion } from '../native/session.js';
+import { LOCAL_RUN_ERRORS, runOwnedAliases } from '../native/local-run.js';
+import { readJsonInput } from './plan-apply.js';
+import { enrollLocalRunner, nativeExecutorKey, withNativeExecutor } from '../runner-identity.js';
+// Release wiring supplies the packaged version; there is no version constant in source yet.
+const CLIENT_VERSION = 'development';
+/**
+ * Approve the local plan for this session and run the companion until the
+ * signal stops it. Commands come only from the approved plan; the cloud learns
+ * only the plan digest. SIGINT/SIGTERM abort the signal, and the companion
+ * stops the processes it owns before returning.
+ */
+export async function runCommand(args, options, emit) {
+    if (args.length || !options.plan || !options.descriptor)
+        throw new CliError('arguments_invalid', 'Use firedrill run --plan <path|-> --descriptor <path|-> --campaign <id>, with --approve for automation.', 2);
+    // A run follows one campaign over the runner device's single channel with the service.
+    if (options.campaign === undefined)
+        throw new CliError('native_campaign_required', 'Use --campaign with the campaign id Firedrill printed (campaign_created): a run follows one campaign\'s drills. Nothing was started.', 2);
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(options.campaign))
+        throw new CliError('arguments_invalid', 'Use --campaign with the campaign id Firedrill printed. Nothing was started.', 2);
+    if (options.enrollDevice && (credentialMode() !== 'session' || options.runner !== undefined))
+        throw new CliError('arguments_invalid', 'Use --enroll-device with run only in session-only mode and without --runner; otherwise enroll a runner for this terminal sign-in with firedrill runner enroll. Nothing was started.', 2);
+    if (options.plan === '-' && options.descriptor === '-')
+        throw new CliError('arguments_invalid', 'Read only one of --plan or --descriptor from standard input. Nothing was started.', 2);
+    const stdinUsed = options.plan === '-' || options.descriptor === '-';
+    const interactive = !options.json && !stdinUsed && !!process.stdin.isTTY && !!process.stderr.isTTY;
+    const plan = parsePlan(await readJsonInput(options.plan, 'the local plan', options.signal));
+    let descriptorValue;
+    try {
+        descriptorValue = JSON.parse(await readJsonInput(options.descriptor, 'the local descriptor', options.signal));
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        throw new CliError('request_file_invalid', 'The descriptor is not valid JSON. Nothing was started.', 2);
+    }
+    const normalized = normalizeDescriptor(descriptorValue);
+    if (plan.descriptor_sha256 !== normalized.descriptor_sha256)
+        throw new CliError('native_descriptor_mismatch', 'The local plan was written for a different descriptor. Nothing was started.', 2);
+    const digest = planDigest(plan);
+    const approval = await approvePlan(plan, normalized.descriptor, { interactive, approve: options.approve === true, signal: options.signal,
+        output: text => { if (!options.json)
+            process.stderr.write(text); } });
+    for (const service of plan.services)
+        localSecretBindings(service);
+    emit('plan_approved', { plan_sha256: digest, descriptor_sha256: normalized.descriptor_sha256 }, `Local plan approved for this session.\nPlan: ${digest}`);
+    // A run that became the companion signs in itself when no credential is held
+    // (always true in session-only mode; also on first use in persistent mode).
+    const held = isCredentialCompanion() ? await loadCredentials().catch((error) => {
+        // login() reports the platform remediation for an unavailable OS store.
+        if (error instanceof CliError && error.code === 'credential_store_unavailable')
+            return null;
+        throw error;
+    }) : true;
+    if (!held) {
+        const session = await login({ json: options.json, open: options.openBrowser, explicitOpen: options.explicitOpen === true, signal: options.signal });
+        const mode = credentialMode();
+        emit('signed_in', { mode }, mode === 'session'
+            ? `Signed in for this session only as ${terminalText(session.user.email)}.`
+            : `Signed in as ${terminalText(session.user.email)}; the credential is kept in the OS store.`);
+    }
+    const scope = await selectedWorkspace({ workspace: options.workspace, interactive, signal: options.signal,
+        openBrowser: options.openBrowser && !options.json });
+    const capabilities = { client_version: CLIENT_VERSION, platform: process.platform, arch: process.arch,
+        drivers: await detectCapabilities(plan), max_parallel_drills: plan.max_parallel_drills, isolation: 'native-trusted' };
+    emit('companion_capabilities', capabilities, ['Drivers:', ...capabilities.drivers.map(one => `  ${one.profile}: ${one.available ? 'available' : `unavailable${one.reason ? ` (${terminalText(one.reason)})` : ''}`}`),
+        'Local targets run as trusted native processes, not in a sandbox.'].join('\n'));
+    // The enrolled runner device executes and signs for this companion; enrollment stays its own consented step.
+    let runner;
+    try {
+        runner = await nativeExecutorKey(scope, options.runner, options.signal);
+    }
+    catch (error) {
+        // Runners are bound to one native session, and session-only sign-in keeps nothing in the OS store (the headless
+        // case it exists for). So with no runner for this session, a session-only run enrolls one whose private key stays
+        // in this process's memory. It needs the same consent as runner enroll: a prompt, or --enroll-device.
+        if (!(error instanceof CliError) || error.code !== 'runner_required' || options.runner !== undefined || credentialMode() !== 'session')
+            throw error;
+        // The campaign's shared services can be closed only by the runner that registered them, and this one's key
+        // would end with this process: refused before any runner is enrolled or anything starts.
+        const shared = runOwnedAliases(plan);
+        if (shared.length) {
+            throw new CliError(LOCAL_RUN_ERRORS.persistent_runner_required, `This plan runs shared services for the whole campaign `
+                + `(${shared.map(terminalText).join(', ')}). Only the runner device that started them can report how they ended and close them, `
+                + 'and a session-only runner\'s key exists only in this run\'s memory, so they could never be closed after it ends. '
+                + 'Ask the human to enroll a runner whose key this machine keeps (firedrill runner enroll; it needs the OS credential store), '
+                + 'then rerun, or make these services per drill (per_drill: true in the plan). Nothing was enrolled and no drill was started.', 2);
+        }
+        const receipt = await enrollLocalRunner(scope, { json: options.json, openBrowser: options.openBrowser, signal: options.signal,
+            enroll: options.enrollDevice === true || undefined, name: 'Session-only runner', ephemeral: true }, emit).catch((enrollError) => {
+            // Without a prompt, the flag stands in for the person's consent, so the message says to ask them first.
+            if (!(enrollError instanceof CliError) || enrollError.code !== 'runner_consent_required')
+                throw enrollError;
+            throw new CliError('runner_consent_required', 'No runner is enrolled for this session-only sign-in. Ask the person first; only after they agree, '
+                + 'rerun with --enroll-device to enroll one whose key stays in this run\'s memory. Nothing was enrolled and no drill was started.', 2);
+        });
+        if (['not_retained', 'revoked', 'expired', 'access_removed'].includes(receipt.state)) {
+            throw new CliError('runner_required', `The session-only runner ${receipt.device_key} is not usable (${receipt.state.replaceAll('_', ' ')}). `
+                + 'Its key existed only in this process; run again to enroll a new one. No drill was started.', 2);
+        }
+        runner = receipt.device_key;
+    }
+    emit('runner_selected', { device_key: runner, campaign_id: options.campaign.toLowerCase() }, `Runner device ${runner} runs the drills of campaign ${options.campaign.toLowerCase()}: those offered to it and the campaign's waiting ones.`);
+    // runCompanion reports its own native_companion_stopped result and stops the processes it owns.
+    await withNativeExecutor(scope, runner, options.signal, executor => runCompanion({
+        controlPlane: httpControlPlane({ workspace: scope.workspace, actor: scope.owner, executor,
+            campaign: options.campaign ? { id: options.campaign.toLowerCase(), descriptor_sha256: normalized.descriptor_sha256 } : null }),
+        plan, descriptor: normalized.descriptor, campaignId: options.campaign?.toLowerCase() ?? null,
+        capabilities, signal: options.signal, output: emit, approval
+    }));
+    options.signal.throwIfAborted();
+}

package/dist/cli/src/simple/status.js

@@ -0,0 +1,49 @@
+import { api, credentialOverview } from '../auth.js';
+import { CliError } from '../http.js';
+import { terminalText } from '../prompts.js';
+import { detectCapabilities } from '../native/drivers/index.js';
+import { parsePlan, processControlLimitations } from '../native/plan.js';
+import { readJsonInput } from './plan-apply.js';
+export async function machineReport(signal, planPath) {
+    const credentials = await credentialOverview(signal);
+    // Without a plan, drivers report machine-level availability only; a plan adds its own checks.
+    const plan = planPath ? parsePlan(await readJsonInput(planPath, 'the local plan', signal)) : null;
+    const drivers = await detectCapabilities(plan);
+    return { platform: process.platform, arch: process.arch, node: process.version, isolation: 'native-trusted', credentials, drivers,
+        drivers_checked_against_plan: plan !== null, limitations: processControlLimitations() };
+}
+export function machineText(value) {
+    return [
+        `Machine: ${value.platform} ${value.arch}, Node ${value.node}. Local targets run as trusted native processes, not in a sandbox.`,
+        ...value.limitations,
+        `Credentials: ${value.credentials.mode === 'session' ? 'session-only (memory)' : 'persistent (OS credential store)'}, ${value.credentials.signed_in ? 'signed in' : 'not signed in'}`,
+        ...(value.credentials.store && !value.credentials.store.available
+            ? [`Credential store: unavailable (${value.credentials.store.backend})${value.credentials.store.remediation ? `\n${value.credentials.store.remediation}` : ''}`]
+            : value.credentials.store ? [`Credential store: ${value.credentials.store.backend}`] : []),
+        `Companion: ${value.credentials.companion_process ? 'this process' : value.credentials.companion
+            ? `running (pid ${value.credentials.companion.pid}, ${value.credentials.companion.mode === 'session' ? 'session-only' : 'persistent'})` : 'not running'}`,
+        `Drivers${value.drivers_checked_against_plan ? ' (checked against the plan)' : ' (machine only; add --plan <path|-> for plan checks)'}:\n`
+            + value.drivers.map(one => `  ${one.profile}: ${one.available ? 'available' : `unavailable${one.reason ? ` (${one.reason})` : ''}`}`).join('\n'),
+    ].map(line => line.split('\n').map(terminalText).join('\n'));
+}
+export async function statusCommand(args, options, emit) {
+    if (args.length)
+        throw new CliError('arguments_invalid', 'Use firedrill status with optional --plan <path|-> and --json.', 2);
+    const machine = await machineReport(options.signal, options.plan);
+    let session = null;
+    if (machine.credentials.signed_in) {
+        try {
+            session = await api('/api/auth/native/session', { signal: options.signal });
+        }
+        catch (error) {
+            if (!(error instanceof CliError) || error.code !== 'authentication_required')
+                throw error;
+        }
+    }
+    emit('status', { signed_in: session !== null, account: session ? { id: session.user.id, email: session.user.email } : null,
+        workspace: session?.workspace ? { id: session.workspace.id, name: session.workspace.name } : null, machine }, [
+        session ? `Account: ${terminalText(session.user.email)}` : 'Account: not signed in. Run firedrill init.',
+        `Workspace: ${session?.workspace ? terminalText(session.workspace.name) : 'Not selected'}`,
+        ...machineText(machine),
+    ].join('\n'));
+}