firedrill-run 3.0.0 → 3.0.2

package/README.md

@@ -9,19 +9,17 @@ Use the CLI yourself, or let a coding agent operate it for you. Local execution
 is not an operating-system sandbox. Approved commands run with your own user
 permissions.
 
-**Release candidate:** the proposed public package is `firedrill-run@3.0.0`.
-It is not published or approved for public activation yet. The existing
-unversioned package resolves to the older product. Do not use `@latest` to
-install this candidate. Once the owner approves and publishes this release,
-the intended commands are:
+## Get started
+
+Use this version explicitly while the unversioned package still points to the
+previous platform:
 
 ```sh
-npx --yes firedrill-run@3.0.0 init
-npx --yes firedrill-run@3.0.0 --help
+npx firedrill-run@3.0.1 init
+npx firedrill-run@3.0.1 --help
 ```
 
-Until then, use only an explicitly supplied private candidate tarball.
-`firedrill --help` of that exact installed candidate is authoritative.
+For automation, `firedrill --help` and `--json` describe the installed version.
 
 ## Requirements
 

package/dist/assembly.json

@@ -1,7 +1,7 @@
 {
   "schema": "firedrill.cli-assembly.v1",
   "package": "firedrill-run",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "entry": "cli/src/main.js",
   "helpers": [
     "cli/runtime/source_snapshot.py",

package/dist/cli/src/auth.js

@@ -130,6 +130,15 @@ export async function login(options) {
             throw new CliError('authorization_exchange_uncertain', 'The original token exchange was interrupted and cannot be safely repeated. Review Account access in the browser. Clear the local attempt with logout --local-only before starting another.', 2);
         if (!pending) {
             const grant = await jsonRequest(new URL(config.device_authorization_endpoint), { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ client_id: config.client_id }), signal: options.signal });
+            if (grant.status === 429) {
+                // No grant exists yet. Report a definitive refusal without creating a
+                // second grant or replaying an unknown device-authorization POST.
+                const wait = grant.retryAfterMs;
+                const advice = wait !== undefined && Number.isFinite(wait) && wait <= 3_600_000
+                    ? ` Wait at least ${Math.max(1, Math.ceil(wait / 1000))} seconds before starting sign-in again.`
+                    : ' Wait before starting sign-in again; do not repeatedly restart it.';
+                throw new CliError('device_authorization_rate_limited', 'Browser sign-in is temporarily busy.' + advice, 2);
+            }
             if (grant.status !== 200)
                 throw new CliError('device_authorization_failed', 'Browser sign-in could not be started.');
             const value = grant.body;
@@ -166,6 +175,7 @@ export async function login(options) {
                 : 'Run the same command to resume if interrupted.'}\n`);
         if (launchBrowser)
             await openBrowser(pending.verification_url);
+        let rateRefusals = 0;
         while (Date.now() < pending.expires_at * 1000) {
             await sleep(Math.min(Math.max(0, pending.next_poll_at - Date.now()), Math.max(0, pending.expires_at * 1000 - Date.now())), undefined, { signal: options.signal });
             options.signal.throwIfAborted();
@@ -183,7 +193,38 @@ export async function login(options) {
                 return finishAuthorization(saved);
             }
             const error = result.body && typeof result.body === 'object' ? result.body.error : undefined;
+            if (result.status === 429) {
+                // A complete, parsed HTTP refusal is distinct from transport/parse
+                // failure or a response that may contain exchanged credentials. Those
+                // uncertain cases keep the polling marker and are never replayed.
+                const body = result.body;
+                if (!body || typeof body !== 'object' || Array.isArray(body)
+                    || ['access_token', 'refresh_token', 'id_token', 'user'].some(key => key in body))
+                    throw new CliError('authorization_exchange_uncertain', 'The authorization response was not confirmed. Review Account access before clearing the original local attempt. No exchange was retried.', 2);
+                rateRefusals += 1;
+                const interval = error === 'slow_down' ? Math.min(3600, pending.interval + 5) : pending.interval;
+                const backoff = Math.min(60_000, 5_000 * 2 ** Math.min(rateRefusals - 1, 4));
+                const minimumWait = Math.max(interval * 1000, result.retryAfterMs ?? backoff);
+                // Never retry earlier than Retry-After or extend the original grant.
+                // An advertised wait beyond that lifetime reaches expiry, not a retry.
+                const deadline = pending.expires_at * 1000;
+                const nextPollAt = Math.min(deadline, Date.now() + minimumWait + Math.floor(Math.random() * 1000));
+                pending = { ...pending, state: 'waiting', interval, next_poll_at: nextPollAt };
+                await savePendingDevice(pending, options.signal);
+                const waitSeconds = Math.max(1, Math.ceil((nextPollAt - Date.now()) / 1000));
+                if (options.json)
+                    process.stdout.write(JSON.stringify({ type: 'authorization_waiting', authorization_id: pending.id,
+                        reason: 'rate_limited', retry_in_seconds: nextPollAt < deadline ? waitSeconds : null,
+                        expires_in: Math.max(0, Math.ceil((deadline - Date.now()) / 1000)),
+                        same_authorization: true, new_device_grant: false }) + '\n');
+                else
+                    process.stderr.write(nextPollAt < deadline
+                        ? `Sign-in is temporarily busy. Waiting ${waitSeconds} seconds before checking the same authorization again.\n`
+                        : 'Sign-in is temporarily busy. Its required wait reaches the original authorization expiry; no new authorization will be started automatically.\n');
+                continue;
+            }
             if (error === 'authorization_pending' || error === 'slow_down') {
+                rateRefusals = 0;
                 // RFC 8628: slow_down permanently adds 5 seconds to the polling interval.
                 const interval = error === 'slow_down' ? Math.min(3600, pending.interval + 5) : pending.interval;
                 pending = { ...pending, state: 'waiting', interval, next_poll_at: Date.now() + interval * 1000 };

package/dist/cli/src/main.js

@@ -745,12 +745,17 @@ export async function main() {
         if (args[0] === 'init') {
             if (Object.keys(parsed.values).some(key => !['json', 'help', 'workspace', 'no-browser', 'open'].includes(key)))
                 throw new CliError('arguments_invalid', 'Use firedrill init with optional --session-only or --persistent, --workspace <id>, --no-browser, --open and --json.', 2);
-            await initCommand(args.slice(1), { json, signal: controller.signal, workspace: parsed.values.workspace,
+            const initialization = await initCommand(args.slice(1), { json, signal: controller.signal, workspace: parsed.values.workspace,
                 openBrowser: !parsed.values['no-browser'], explicitOpen, mode: credentialMode.mode }, emit);
             if (companion) {
                 // Session-only credentials live only in this process: keep serving until
                 // a signal or logout (companion shutdown) stops it.
-                emit('companion_running', { endpoint_ready: true, mode: 'session' }, 'Session-only companion running. Keep this terminal open; other firedrill commands use it. Stop it with Ctrl-C or firedrill logout.');
+                emit('companion_running', { endpoint_ready: true, mode: 'session', initialization_state: initialization.state,
+                    initialization_complete: initialization.state === 'ready',
+                    command_phase_complete: true,
+                    workspace_id: initialization.state === 'ready' ? initialization.workspace_id : null,
+                    process_lifetime: 'until_logout_or_signal',
+                    next_command: initialization.state === 'workspace_pending' ? 'firedrill workspace list --session-only --json' : null }, 'Session-only companion running. Keep this terminal open; other firedrill commands use it. Stop it with Ctrl-C or firedrill logout.');
                 if (!controller.signal.aborted)
                     await once(controller.signal, 'abort');
                 emit('companion_stopping', { reason: signalled ? 'signal' : 'shutdown' }, 'Stopping the companion. In-memory credentials are erased on close.');

package/dist/cli/src/runner-identity.js

@@ -101,7 +101,11 @@ async function lock(scope, key, signal, work) {
     const directory = join(await privateDirectory(), `runner-lock-${identifier(scope.owner)}-${identifier(scope.workspace)}-${identifier(key)}`);
     return withBootstrapProcessLock(directory, signal, work);
 }
-async function proof(value, payload) {
+/** Read only the original signing material and verify its retained public identity.
+ * A metadata journal can outlive a session-only process's in-memory key.
+ * Reading that journal alone therefore does not make a runner usable.
+ */
+async function privateSigningKey(value) {
     try {
         const encoded = MEMORY_KEYS.get(value.key) ?? (await store(value, value.key)).getPassword();
         if (!encoded || encoded.length > 2048)
@@ -112,6 +116,15 @@ async function proof(value, payload) {
         const publicKey = createPublicKey(key).export({ format: 'jwk' });
         if (!publicKey.x || Buffer.from(publicKey.x, 'base64url').toString('base64') !== value.enrollment.public_key)
             throw new Error();
+        return key;
+    }
+    catch {
+        throw new CliError('runner_key_unavailable', 'This runner key could not be read from the OS credential store. It was not regenerated.');
+    }
+}
+async function proof(value, payload) {
+    try {
+        const key = await privateSigningKey(value);
         return { payload, signature: sign(null, Buffer.from('firedrill.local-runner-proof.v1\n' + canonical(payload)), key).toString('base64') };
     }
     catch {
@@ -513,17 +526,29 @@ export async function withNativeExecutor(scope, key, signal, work) {
  * identity on this machine. Enrollment stays an explicit, consented step.
  */
 export async function nativeExecutorKey(scope, requested, signal) {
+    const usableKey = async (key) => {
+        const retained = await currentLocalRunner(scope, key, signal);
+        // Recheck the local journal against the exact validated server receipt.
+        // No key is generated, persisted, signed or sent while selecting a device.
+        const value = await saved(scope, retained.device_key);
+        matches(value, retained);
+        signal.throwIfAborted();
+        await privateSigningKey(value);
+        signal.throwIfAborted();
+        return retained.device_key;
+    };
+    // Explicit requests never fall back to a different runner or enroll a key.
     if (requested !== undefined)
-        return (await currentLocalRunner(scope, identifier(requested), signal)).device_key;
+        return usableKey(identifier(requested));
     const usable = [];
     for (let page = 1; page <= 5; page++) {
         const { directory, candidates } = await localRunnerSelectionPage(scope, page, signal);
         for (const candidate of candidates) {
             try {
-                usable.push((await currentLocalRunner(scope, candidate.device_key, signal)).device_key);
+                usable.push(await usableKey(candidate.device_key));
             }
             catch (error) {
-                if (!(error instanceof CliError) || !['runner_identity_not_local', 'runner_scope_changed', 'runner_access_removed'].includes(error.code))
+                if (!(error instanceof CliError) || !['runner_identity_not_local', 'runner_scope_changed', 'runner_access_removed', 'runner_key_unavailable'].includes(error.code))
                     throw error;
             }
         }

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

@@ -1,5 +1,5 @@
 import { api, login } from '../auth.js';
-import { CliError } from '../http.js';
+import { APP_ORIGIN, CliError } from '../http.js';
 import { terminalText } from '../prompts.js';
 import { selectedWorkspace } from '../world-access.js';
 import { machineReport, machineText } from './status.js';
@@ -40,7 +40,41 @@ export async function initCommand(args, options, emit) {
             throw error;
         session = await login({ json: options.json, open: options.openBrowser, explicitOpen: options.explicitOpen, signal: options.signal });
     }
-    const scope = await selectedWorkspace({ workspace: options.workspace, interactive, signal: options.signal, openBrowser });
+    let scope;
+    try {
+        scope = await selectedWorkspace({ workspace: options.workspace, interactive, signal: options.signal, openBrowser });
+    }
+    catch (error) {
+        // Device authorization already succeeded. A durable workspace discovery or
+        // explicit setup step must not erase the only copy of that signed-in session.
+        // Only session-only init owns a companion lifetime; persistent commands and
+        // authorization/transport/cancellation failures retain their normal errors.
+        if (mode !== 'session' || options.signal.aborted || !(error instanceof CliError)
+            || !['workspace_discovery_pending', 'workspace_setup_required'].includes(error.code))
+            throw error;
+        const reason = error.code === 'workspace_discovery_pending' ? 'workspace_discovery_pending' : 'workspace_setup_required';
+        emit('init_pending', {
+            state: 'workspace_pending', reason, authenticated: true, initialization_complete: false,
+            account: { id: session.user.id, email: session.user.email }, workspace_id: null, credential_mode: 'session',
+            companion_required: true, process_lifetime: 'until_logout_or_signal',
+            next_command: 'firedrill workspace list --session-only --json',
+            select_command_template: 'firedrill workspace use <workspace-id> --session-only --json',
+            status_command: 'firedrill status --session-only --json',
+            ...(reason === 'workspace_setup_required' ? { browser_url: new URL('/onboarding', APP_ORIGIN).href,
+                action_required: 'create_or_select_workspace_with_person_approval' } : {}),
+            uploaded: false, model_called: false,
+        }, [
+            `Signed in as ${terminalText(session.user.email)}.`,
+            reason === 'workspace_discovery_pending' ? 'Workspace access is still being checked.' : 'A workspace still needs to be created or selected.',
+            'Initialization is not complete. Keep this terminal open to retain the session-only sign-in.',
+            'In another terminal, run firedrill workspace list --session-only, then firedrill workspace use <workspace-id> --session-only.',
+            'Use only a workspace returned for this account. Normal organization authorization and person approvals still apply.',
+            ...(reason === 'workspace_setup_required' ? [`Workspace setup: ${new URL('/onboarding', APP_ORIGIN).href}`] : []),
+            'After selecting it, firedrill status --session-only shows the current account, workspace and machine.',
+            'Do not start another init while this companion is running. Stop with Ctrl-C or firedrill logout.',
+        ].join('\n'));
+        return { state: 'workspace_pending', reason };
+    }
     const machine = await machineReport(options.signal);
     emit('init', {
         account: { id: session.user.id, email: session.user.email }, workspace_id: scope.workspace, credential_mode: mode, machine,
@@ -58,4 +92,5 @@ export async function initCommand(args, options, emit) {
         ...NEXT.map((step, index) => `  ${index + 1}. ${step.command}\n     ${step.note}`),
         'Nothing was uploaded and no model was called.',
     ].join('\n'));
+    return { state: 'ready', workspace_id: scope.workspace };
 }

package/dist/cli/src/simple/native-tools.js

@@ -265,11 +265,17 @@ async function start(args, options, emit) {
     }
     const reviewed = setup;
     let children = items ?? await setupItems(scope, { setup: reviewed, signal });
-    if (setup.state === 'reviewed' && setup.approved_at === null && setup.stop_requested_at === null) {
+    const recoveringAdmission = options.request !== undefined && setup.state === 'needs_attention'
+        && setup.approved_at !== null && setup.stop_requested_at === null;
+    if ((setup.state === 'reviewed' && setup.approved_at === null && setup.stop_requested_at === null) || recoveringAdmission) {
         // Quoting reserves nothing. Root keeps one estimate per session and replays it for its quote key only,
         // so a later run admits exactly the estimate the human saw. An approval holds only for that key.
         const original = setup.quote_request_key;
         const given = options.quote?.toLowerCase();
+        if (recoveringAdmission && (original === null || setup.bundle_digest === null))
+            throw new CliError('tool_start_unconfirmed', 'The original approved estimate could not be confirmed. Inspect this same tool session; do not create a replacement request.', 2);
+        if (recoveringAdmission && (ids.length || options.file !== undefined || options.seconds !== undefined || options.service !== undefined))
+            throw new CliError('arguments_invalid', `Continue this original tool session without changing its selection or duration: ${recovery} --usage-quote ${original} --approve-tool-change.`, 2);
         if (given !== undefined && original !== null && given !== original)
             throw new CliError('idempotency_conflict', 'That quote key is not this setup’s original estimate. Read the original setup before continuing. Nothing was admitted.', 2);
         const quoteKey = original ?? given ?? randomUUID();
@@ -280,24 +286,37 @@ async function start(args, options, emit) {
             notice = `This session's estimate was quoted under ${original}, not the key given, so it needs its own approval. `;
         const quoted = children;
         const quotes = await retryTransient(() => quoteSetup(scope, { setup: reviewed, items: quoted, requestKey: quoteKey, signal }), { signal, attempts: 3 });
-        if (!quotes.quotes.every(live))
+        if (recoveringAdmission && (quotes.quote_key !== original || quotes.bundle_digest !== setup.bundle_digest))
+            throw new CliError('idempotency_conflict', 'The retained approved estimate changed. Nothing was retried. Inspect the original tool session.', 2);
+        // The server replays an existing approval without replacing its quote.
+        // Only a never-approved review must still meet the initial quote deadline.
+        if (!recoveringAdmission && !quotes.quotes.every(live))
             throw expiredReview(setup.id);
-        let approved = options.approve === true && (!quotes.quotes.some(quote => quote.credit_approval_required) || (original !== null && given === original));
+        let approved = options.approve === true && (recoveringAdmission ? given === original
+            : !quotes.quotes.some(quote => quote.credit_approval_required) || (original !== null && given === original));
         const interactive = tty(options);
         if (!approved && interactive)
             process.stderr.write(setupText(setup, children) + '\n');
-        emit('tool_start_quote', quotes, `${notice}${quoteText(quotes, children)}`);
+        emit('tool_start_quote', quotes, `${recoveringAdmission ? 'Continuing the original approved tool session with its retained estimate. Existing tools are not replaced.\n' : notice}${quoteText(quotes, children)}`);
         if (!approved && interactive) {
-            approved = await selectOne(`Start ${children.length} tool${children.length === 1 ? '' : 's'} for ${duration(setup.duration_seconds)} each?`, [
-                { value: false, label: 'Not now', detail: 'Nothing is reserved or started.' },
-                { value: true, label: 'Start tools', detail: 'Reserves up to the estimate above. The tools run in the cloud, not on this machine.' },
+            approved = await selectOne(recoveringAdmission ? 'Continue this original approved tool session?'
+                : `Start ${children.length} tool${children.length === 1 ? '' : 's'} for ${duration(setup.duration_seconds)} each?`, [
+                { value: false, label: 'Not now', detail: recoveringAdmission ? 'The original session and existing allocations stay unchanged.' : 'Nothing is reserved or started.' },
+                { value: true, label: recoveringAdmission ? 'Continue original session' : 'Start tools',
+                    detail: recoveringAdmission ? 'Uses the same approved selection and estimate. Existing tool allocations are retained.'
+                        : 'Reserves up to the estimate above. The tools run in the cloud, not on this machine.' },
             ], signal);
         }
         if (!approved) {
-            throw new CliError('tool_change_consent_required', `${notice}Nothing was reserved or started. Show the human this estimate; after they approve it: `
+            throw new CliError('tool_change_consent_required', (recoveringAdmission
+                ? 'The original approval and any existing allocations were left unchanged. After the human approves continuing this same session: '
+                : `${notice}Nothing was reserved or started. Show the human this estimate; after they approve it: `)
                 + `${recovery} --usage-quote ${quoteKey} --approve-tool-change`, 2);
         }
-        const creditApproval = await approveCredits(quotes.quotes, options, interactive, `${recovery} --usage-quote ${quoteKey} --approve-tool-change`);
+        // Recovery does not invent another credit approval. The backend verifies
+        // and uses its durable original approval_digest and per-child request keys.
+        const creditApproval = recoveringAdmission ? false
+            : await approveCredits(quotes.quotes, options, interactive, `${recovery} --usage-quote ${quoteKey} --approve-tool-change`);
         try {
             setup = await retryTransient(() => admitSetup(scope, { quotes, signal, creditApproval }), { signal, attempts: 3 });
         }
@@ -340,6 +359,20 @@ async function start(args, options, emit) {
     }
     emit('tool_session', { ...setup, items: children }, setupText(setup, children)
         + (settled(setup, children) ? '' : `\nFollow it: firedrill tools session ${setup.id}`));
+    if (options.follow) {
+        // A completed follow is an observation, not proof that admission or every
+        // child succeeded. Preserve its full final receipt before the typed error.
+        // Normal stopped/expired history and user cancellation are not failures.
+        const failed = children.filter(item => item.instance_state === 'failed' || item.instance_state === 'rejected'
+            || item.failure_code !== null && item.admission_state !== 'cancelled'
+                && !['stopped', 'canceled', 'cancelled', 'expired'].includes(item.instance_state ?? ''));
+        if (failed.length)
+            throw new CliError('tool_start_failed', `${failed.length} tool${failed.length === 1 ? '' : 's'} failed in this original session. Inspect its retained result with firedrill tools session ${setup.id}. Nothing was restarted.`, 1);
+        if (setup.stop_requested_at === null && (setup.state === 'needs_attention' || children.some(item => item.admission_state === 'needs_attention')))
+            throw new CliError('tool_start_needs_attention', `This original tool session needs attention. Inspect it with firedrill tools session ${setup.id} before explicitly continuing its original request. Nothing was retried.`, 1);
+        if (!settled(setup, children))
+            throw new CliError('tool_start_pending', `This original tool session is still preparing after the follow window. Read its progress with firedrill tools session ${setup.id}. This is not a startup failure, and nothing was restarted.`, 1);
+    }
 }
 /** `tools runnable [--search <text>] [--page <n>]`: saved versions and the lane each service would start in. */
 async function runnable(options, emit) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firedrill-run",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "description": "Local AI agent simulations with cloud-hosted worlds and tools",
   "type": "module",
   "bin": {