@shardflux/cli 0.20.0 → 0.23.0

package/dist/project-template-setup.js

@@ -52,7 +52,9 @@ export function projectTemplateSlug(slug, identity) {
     // Distinct dotted/underscored project keys must not collapse onto the same builder slug.
     return `${slug.replace(/[._]/g, '-').slice(0, 89)}-${createHash('sha256').update(identity).digest('hex').slice(0, 10)}`;
 }
-export async function prepareProjectTemplate(ctx, project, existing) {
+/** The repository's dependency hash, its project template, whether setup runs (no template for this hash yet) and the
+ * labels a passed setup saves the project template from. The hash is read first, before any await. */
+async function projectSetup(ctx, project) {
     const depsHash = dependencyHash(project.folder);
     const remote = project.remote ?? normalizeRemote(`file://${project.folder}`);
     let binding;
@@ -68,13 +70,68 @@ export async function prepareProjectTemplate(ctx, project, existing) {
     const setup = !binding || binding.deps_hash !== depsHash;
     // The builder only accepts lowercase letters, digits and hyphens. Keep L4's workspace identity unchanged.
     const templateSlug = binding?.template_slug ?? projectTemplateSlug(project.slug, remote);
+    return { depsHash, binding, setup,
+        labels: { shard_deps_hash: depsHash, shard_setup: String(setup), shard_setup_mode: 'assisted-v2', shard_template_slug: templateSlug, shard_repo_remote: remote } };
+}
+export async function prepareProjectTemplate(ctx, project, existing) {
+    const { depsHash, binding, setup, labels } = await projectSetup(ctx, project);
     const machine = await savedMachine(ctx);
     return {
         template: existing?.template.slug ?? (binding ? `${binding.template_slug}@${binding.version}` : machine?.template ? `${machine.template.slug}@${machine.template.version}` : 'coding'),
         setupHash: setup ? depsHash : undefined,
-        labels: { shard_deps_hash: depsHash, shard_setup: String(setup), shard_setup_mode: 'assisted-v2', shard_template_slug: templateSlug, shard_repo_remote: remote },
+        labels,
     };
 }
+/**
+ * Whether a new conversation sets its repository up (0.21.1+): when the project has no template for the repository's
+ * current dependency hash. Read as the conversation starts, so the hash is of the files it is seeded with; the API
+ * read runs while its VM starts. Never fails the start: an unreadable answer is reported and the conversation runs
+ * without setup.
+ */
+export function readConversationSetup(ctx, project) {
+    let read;
+    try {
+        read = projectSetup(ctx, project);
+    }
+    catch (error) {
+        read = Promise.reject(error instanceof Error ? error : new Error(String(error)));
+    }
+    return read.then(s => s.setup ? s : undefined, (error) => {
+        if (!ctx.signal.aborted)
+            ctx.io.stderr.write(`Project setup skipped: ${error instanceof Error ? error.message : String(error)}\n`);
+        return undefined;
+    });
+}
+/**
+ * The conversation's VM gets the labels a project workspace has, with its worktree as the repository, so the setup
+ * that passes there saves the project template the next conversation starts from. Runs beside the agent's start; the
+ * setup itself is queued once it is done. A failed label write is reported: setup still prepares this conversation.
+ */
+export function labelConversationSetup(ctx, ws, worktree, setup) {
+    if (!setup)
+        return undefined;
+    const labelled = (async () => {
+        // Labels are replaced as a whole: merge into the VM's current ones.
+        const current = await ctx.cloud().workspaces.get(ws.id, { signal: ctx.signal });
+        await current.setLabels({ ...current.labels, ...setup.labels, repo_path: worktree });
+    })().catch((error) => {
+        if (!ctx.signal.aborted)
+            ctx.io.stderr.write(`Project template will not be saved from this conversation: ${error instanceof Error ? error.message : String(error)}\n`);
+    });
+    return { hash: setup.depsHash, labelled };
+}
+/**
+ * The hash a new conversation's worktree is set up with, recorded in its VM before the seed. Its guest starts the agent
+ * as soon as the repository appears, and with this record starts it with the setup's context and toolchains on PATH
+ * (services/guest-agent conversation_runtime.go setupIntent; a guest without it ignores the record).
+ */
+export async function recordSetupIntent(cell, c, depsHash, signal) {
+    if (!/^conv_[a-z0-9]{26}$/.test(c.id) || !/^[a-f0-9]{64}$/.test(depsHash))
+        throw new Error('invalid conversation or dependency hash');
+    const r = await cell.exec.run(['sh', '-c', 'umask 077; d=/home/user/.local/share/shardflux/conversation-setup; mkdir -p "$d" && printf \'{"deps_hash":"%s"}\' "$2" > "$d/$1.json"', 'shard-setup', c.id, depsHash], { timeoutMs: 15_000, maxOutputBytes: 4096, ...(signal ? { signal } : {}) });
+    if (r.exitCode !== 0)
+        throw new Error(r.stderr.trim() || `exit ${r.exitCode}`);
+}
 export const PROJECT_TEMPLATE_HANDLERS = {
     async 'projects template'(ctx, _values, [path = './']) {
         const project = projectIdentity(path);

package/dist/secret-ask.d.ts

@@ -0,0 +1,72 @@
+import type { Ctx } from './commands.js';
+/** `secret`: a password field (multiple lines on request). `file`: a masked text area. `code`: a visible one-line code. */
+export type AskKind = 'secret' | 'file' | 'code';
+export interface AskPage {
+    kind: AskKind;
+    /** The page heading, e.g. "Add GITHUB_TOKEN". */
+    title: string;
+    /** One line: what it is for and where it goes. */
+    purpose: string;
+    /** The field's label. */
+    label: string;
+    /** The submit button. */
+    submit: string;
+    /** The heading after the command's action succeeded, e.g. "Saved". */
+    done: string;
+    /** The heading after an error that ends the command, e.g. "Not saved". */
+    failed: string;
+    /** A link the person may need on the way (the claude.ai sign-in). */
+    link?: {
+        href: string;
+        text: string;
+    };
+}
+export interface AskOptions<T> extends AskPage {
+    /** Largest accepted value in UTF-8 bytes. */
+    maxBytes: number;
+    timeoutMs: number;
+    /** Aborting closes the page; the result rejects with the signal's reason (an Error) or InterruptedError. */
+    signal: AbortSignal;
+    /** The command's action with the value. Resolved: the page says `done`. Thrown: see `retry`. */
+    use(value: string): Promise<T>;
+    /** Whether the person can fix the error on the page (default: UsageError, and the API's 400/422 validation errors). */
+    retry?: (error: unknown) => boolean;
+}
+export interface AskServer<T> {
+    /** http://127.0.0.1:<port>/<token> */
+    readonly url: string;
+    /** The value (in memory only) and the action's result, once the action succeeded. */
+    readonly result: Promise<{
+        value: string;
+        result: T;
+    }>;
+}
+export declare const DEFAULT_ASK_TIMEOUT_MS: number;
+/** `--timeout` of an asking command (default 10 minutes). */
+export declare function askTimeout(values: Record<string, unknown>): number;
+/** Starts the page's server (listening once this resolves); the caller opens `url`. */
+export declare function startAsk<T>(opts: AskOptions<T>): Promise<AskServer<T>>;
+/** What the person is told an asking command did: an NDJSON event with --json, else one line on stderr. */
+export declare function announce(ctx: Pick<Ctx, 'json' | 'io'>, event: Record<string, unknown> & {
+    event: string;
+    url: string;
+    opened: boolean;
+}, line: string): void;
+/** Opens `url` in the browser; whether it opened (the link is printed either way). */
+export declare function openInBrowser(ctx: Pick<Ctx, 'io'>, url: string): Promise<boolean>;
+export interface BrowserAsk<T> extends Omit<AskOptions<T>, 'signal' | 'timeoutMs'> {
+    /** What the person does on the page, for the text line: "to type GITHUB_TOKEN". */
+    doing: string;
+    /** The NDJSON event name (default `open`). */
+    event?: string;
+    timeoutMs: number;
+    signal?: AbortSignal;
+}
+/**
+ * Asks the person on the page and runs the command's action with the value: opens the page (printing its link), says
+ * so (`{"event":"open","url":...,"opened":...,"expires_in":...}` with --json), and resolves once the action succeeded.
+ */
+export declare function askInBrowser<T>(ctx: Ctx, ask: BrowserAsk<T>): Promise<{
+    value: string;
+    result: T;
+}>;

package/dist/secret-ask.js

@@ -0,0 +1,351 @@
+/**
+ * shard asks its user directly (0.20.1+): a value the coding agent running `shard` must never see (a secret, a secret
+ * file's contents, the code claude.ai shows after sign-in) is typed into a page on this computer instead of the chat.
+ *
+ * One small HTTP server listens on 127.0.0.1 at a random port and serves one page at an unguessable path (32 random
+ * bytes). The CLI opens it in the browser and always prints the link, so an agent can hand it to its user when no
+ * browser opened. The page is self-contained (inline styles from brand/tokens.css, no external requests, a strict CSP,
+ * no referrer, no caching). A POST is accepted only from that page: the path token, a per-page nonce, a same-origin
+ * `Origin` (or none), the form content type and this server's `Host`. The value goes to the command's own action
+ * (e.g. the API call that stores the secret); the page says "Saved" only after that action succeeded, or shows its
+ * error and lets the person try again. One success, a cancel or the timeout (default 10 minutes) closes the server.
+ * The value is never printed or logged, is added to the command's redaction list, and its request buffers are zeroed.
+ */
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { createServer } from 'node:http';
+import { ShardfluxApiError } from '@shardflux/sdk';
+import { parseDuration } from "./args.js";
+import { openUrl } from "./browser.js";
+import { CodedError, InterruptedError, UsageError } from "./errors.js";
+export const DEFAULT_ASK_TIMEOUT_MS = 10 * 60_000;
+/** `--timeout` of an asking command (default 10 minutes). */
+export function askTimeout(values) {
+    return typeof values.timeout === 'string' ? parseDuration(values.timeout, 'timeout') : DEFAULT_ASK_TIMEOUT_MS;
+}
+/** Ran out of time (exit 5 like every other wait; code `ask_timeout`). */
+class AskTimeoutError extends CodedError {
+    name = 'TimeoutError';
+}
+function defaultRetry(error) {
+    return error instanceof UsageError || (error instanceof ShardfluxApiError && (error.status === 400 || error.status === 422));
+}
+const FORM = /^application\/x-www-form-urlencoded(?:\s*;.*)?$/i;
+function same(a, b) {
+    const x = Buffer.from(a), y = Buffer.from(b);
+    return x.length === y.length && timingSafeEqual(x, y);
+}
+/** Starts the page's server (listening once this resolves); the caller opens `url`. */
+export async function startAsk(opts) {
+    const token = randomBytes(32).toString('base64url');
+    const path = `/${token}`;
+    const retry = opts.retry ?? defaultRetry;
+    const nonces = new Set();
+    let state = 'open';
+    const closed = () => state === 'closed';
+    let lastError;
+    let expired = false;
+    let port = 0;
+    let settle;
+    const result = new Promise((resolve, reject) => { settle = { resolve, reject }; });
+    // The command awaits it; a rejection before then must not be reported as unhandled.
+    result.catch(() => undefined);
+    const server = createServer((req, res) => {
+        handle(req, res).catch(() => {
+            if (!res.headersSent)
+                send(res, 500, page('Something went wrong', 'Close this tab and run the command again.'));
+            else
+                res.destroy();
+        });
+    });
+    /** Single use: stops listening at once; open connections (other tabs) end once `res`, the last answer, is sent. */
+    const finish = (outcome, res) => {
+        state = 'closed';
+        clearTimeout(timer);
+        opts.signal.removeEventListener('abort', aborted);
+        server.close();
+        if (res && !res.writableFinished)
+            res.once('close', () => server.closeAllConnections());
+        else
+            server.closeAllConnections();
+        if ('ok' in outcome)
+            settle.resolve(outcome.ok);
+        else
+            settle.reject(outcome.error);
+    };
+    const timeoutError = () => new AskTimeoutError('ask_timeout', `Nothing was entered in the page within ${duration(opts.timeoutMs)}.`, 'run the command again for a new page (--timeout sets how long it waits)');
+    const timer = setTimeout(() => {
+        expired = true;
+        // A submit in progress finishes first; its outcome decides.
+        if (state === 'open')
+            finish({ error: timeoutError() });
+    }, opts.timeoutMs);
+    const aborted = () => {
+        const reason = opts.signal.reason;
+        if (state !== 'closed')
+            finish({ error: reason instanceof Error && reason.name !== 'AbortError' ? reason : new InterruptedError('Interrupted.') });
+    };
+    function headers(nonce) {
+        const csp = nonce
+            ? `default-src 'none'; style-src 'nonce-${nonce}'; script-src 'nonce-${nonce}'; img-src data:; form-action 'self'; base-uri 'none'; frame-ancestors 'none'`
+            : "default-src 'none'; frame-ancestors 'none'";
+        return {
+            'content-security-policy': csp,
+            'referrer-policy': 'no-referrer',
+            'cache-control': 'no-store',
+            'x-content-type-options': 'nosniff',
+            'x-frame-options': 'DENY',
+            'cross-origin-opener-policy': 'same-origin',
+            'cross-origin-resource-policy': 'same-origin',
+        };
+    }
+    function send(res, status, html, last = false) {
+        if (html === null) {
+            res.writeHead(status, { ...headers(), 'content-type': 'text/plain; charset=utf-8' }).end(status === 404 ? 'Not found.\n' : 'Refused.\n');
+            return;
+        }
+        const nonce = randomBytes(16).toString('base64');
+        const body = html.replaceAll('%NONCE%', nonce);
+        res.writeHead(status, { ...headers(nonce), 'content-type': 'text/html; charset=utf-8', ...(last ? { connection: 'close' } : {}) }).end(body);
+    }
+    function form(error) {
+        const nonce = randomBytes(24).toString('base64url');
+        nonces.add(nonce);
+        // A few tabs or reloads of the same page each get a nonce; older ones expire.
+        if (nonces.size > 8)
+            nonces.delete(nonces.values().next().value);
+        return formPage(opts, path, nonce, error, opts.timeoutMs);
+    }
+    function page(heading, text, tone = 'plain') {
+        return statusPage(heading, text, tone);
+    }
+    async function handle(req, res) {
+        // DNS rebinding: only this server's own address is served.
+        if (req.headers.host !== `127.0.0.1:${port}`)
+            return send(res, 421, null);
+        if (req.url === undefined || !same(req.url, path))
+            return send(res, 404, null);
+        if (req.method === 'GET' || req.method === 'HEAD') {
+            if (state === 'closed')
+                return send(res, 410, page('This page was used', 'You can close this tab.'));
+            return send(res, 200, state === 'busy' ? page('Saving', 'Waiting for the result. Reload this tab in a moment.') : form(lastError));
+        }
+        if (req.method !== 'POST')
+            return send(res, 405, null);
+        // Only this page posts here: same origin, the form content type, a nonce it issued. Under no-referrer a browser
+        // posts the form with `Origin: null` (a sandboxed frame elsewhere does too), so null counts only with
+        // `Sec-Fetch-Site: same-origin`, which the browser sets from the real initiator.
+        const origin = req.headers.origin;
+        const site = req.headers['sec-fetch-site'];
+        if (site !== undefined && site !== 'same-origin')
+            return send(res, 403, null);
+        if (origin !== undefined && origin !== `http://127.0.0.1:${port}` && !(origin === 'null' && site === 'same-origin'))
+            return send(res, 403, null);
+        if (!FORM.test(req.headers['content-type'] ?? ''))
+            return send(res, 415, null);
+        const fields = await readForm(req, opts.maxBytes * 3 + 4096);
+        if (fields === null)
+            return send(res, 413, form(`The value is larger than ${opts.maxBytes} bytes.`), true);
+        const nonce = fields.get('nonce') ?? '';
+        const issued = [...nonces].find((n) => same(n, nonce));
+        if (issued === undefined)
+            return send(res, 403, page('This page expired', 'Reload it and try again.'));
+        if (state === 'busy')
+            return send(res, 409, page('Saving', 'The first submit is still being saved. Reload this tab in a moment.'));
+        if (state === 'closed')
+            return send(res, 410, page('This page was used', 'You can close this tab.'));
+        nonces.delete(issued);
+        if (fields.get('action') === 'cancel') {
+            send(res, 200, page('Canceled', 'Nothing was saved. You can close this tab.'), true);
+            const after = lastError ? `Canceled in the browser after: ${lastError}` : 'Canceled in the browser; nothing was saved.';
+            finish({ error: new CodedError('ask_canceled', after, 'ask your user whether to try again, then run the command again') }, res);
+            return;
+        }
+        let value = (fields.get('value') ?? '').replaceAll('\r\n', '\n');
+        if (opts.kind === 'code')
+            value = value.trim();
+        if (value.length === 0)
+            return send(res, 200, form('Type a value first.'));
+        if (Buffer.byteLength(value, 'utf8') > opts.maxBytes)
+            return send(res, 200, form(`The value is larger than ${opts.maxBytes} bytes.`));
+        state = 'busy';
+        try {
+            const out = await opts.use(value);
+            send(res, 200, page(opts.done, 'You can close this tab.', 'done'), true);
+            finish({ ok: { value, result: out } }, res);
+        }
+        catch (error) {
+            const message = errorText(error, value);
+            // Closed meanwhile (interrupted, or the command's own abort): the page only reports it.
+            if (closed())
+                return send(res, 410, page(opts.failed, message, 'failed'), true);
+            if (retry(error) && !expired) {
+                state = 'open';
+                lastError = message;
+                return send(res, 200, form(message));
+            }
+            send(res, 200, page(opts.failed, `${message} You can close this tab; your coding agent sees the same error.`, 'failed'), true);
+            finish({ error: retry(error) && expired ? timeoutError() : error }, res);
+        }
+    }
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => { server.off('error', reject); resolve(); });
+    });
+    port = server.address().port;
+    opts.signal.addEventListener('abort', aborted, { once: true });
+    if (opts.signal.aborted)
+        aborted();
+    return { url: `http://127.0.0.1:${port}${path}`, result };
+}
+/** The urlencoded body, or null past `max` bytes. The raw request bytes are zeroed once parsed. */
+async function readForm(req, max) {
+    const chunks = [];
+    let size = 0;
+    try {
+        for await (const chunk of req) {
+            size += chunk.length;
+            chunks.push(chunk);
+            if (size > max)
+                return null;
+        }
+        const body = Buffer.concat(chunks);
+        try {
+            return new URLSearchParams(body.toString('utf8'));
+        }
+        finally {
+            body.fill(0);
+        }
+    }
+    finally {
+        for (const chunk of chunks)
+            chunk.fill(0);
+    }
+}
+function errorText(error, value) {
+    const message = error instanceof Error ? error.message : String(error);
+    const redacted = value.length >= 4 ? message.split(value).join('[redacted]') : message;
+    // CLI messages start lower case ("the secret value is empty"); on the page they are sentences.
+    const text = redacted.charAt(0).toUpperCase() + redacted.slice(1);
+    return /[.!?]$/.test(text) ? text : `${text}.`;
+}
+function duration(ms) {
+    if (ms % 60_000 === 0)
+        return `${ms / 60_000} minute${ms === 60_000 ? '' : 's'}`;
+    return `${Math.max(1, Math.round(ms / 1000))} s`;
+}
+const esc = (text) => text.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+/** The Flux mark (brand/shardflux-mark.svg). */
+const MARK = '<svg viewBox="0 0 32 32" width="20" height="20" fill="currentColor" aria-hidden="true"><g transform="rotate(18 16 16)"><polygon points="16,1 11.13,12.4 20.87,12.4 16,1"/><polygon points="10.71,13.4 9,17.4 9.77,18.9 22.23,18.9 23,17.4 21.29,13.4"/><polygon points="10.29,19.9 12.86,24.9 19.14,24.9 21.71,19.9" opacity="0.72"/><polygon points="13.38,25.9 16,31 16,31 18.63,25.9" opacity="0.45"/></g></svg>';
+const FAVICON = `data:image/svg+xml,${encodeURIComponent(MARK.replace('fill="currentColor"', 'fill="#8B8F96"').replace(' aria-hidden="true"', ' xmlns="http://www.w3.org/2000/svg"'))}`;
+// Values from brand/tokens.css (dark primary, light for app surfaces), inlined: the page makes no other request.
+const STYLE = `
+:root{color-scheme:dark;--sf-bg:#0A0A0B;--sf-raise:#111113;--sf-ink:#EDEBE7;--sf-muted:#8B8F96;--sf-dim:#5D6168;
+--sf-line:rgba(237,235,231,.09);--sf-line-2:rgba(237,235,231,.16);--sf-line-3:rgba(237,235,231,.34);--sf-success:#7BC68A;--sf-danger:#F0645A;
+--sf-body:"Funnel Sans",system-ui,-apple-system,"Segoe UI",sans-serif;--sf-display:"Funnel Display",system-ui,-apple-system,"Segoe UI",sans-serif;
+--sf-mono:"Fragment Mono",ui-monospace,Menlo,monospace;--sf-fast:150ms}
+@media (prefers-color-scheme:light){:root{color-scheme:light;--sf-bg:#EDEBE7;--sf-raise:#F6F4F0;--sf-ink:#15161A;--sf-muted:#5B6068;--sf-dim:#8A8E94;
+--sf-line:rgba(21,22,26,.10);--sf-line-2:rgba(21,22,26,.18);--sf-line-3:rgba(21,22,26,.36);--sf-success:#2F8A4A;--sf-danger:#C8372D}}
+@media (prefers-reduced-motion:reduce){:root{--sf-fast:0ms}}
+*{box-sizing:border-box}
+html,body{margin:0;background:var(--sf-bg);color:var(--sf-ink);font:400 14px/1.5 var(--sf-body);-webkit-font-smoothing:antialiased}
+main{max-width:480px;margin:0 auto;padding:64px 16px 48px;display:flex;flex-direction:column;gap:24px}
+.lockup{display:flex;align-items:center;gap:8px;font:600 17px/1 var(--sf-display);letter-spacing:-.03em;color:var(--sf-ink)}
+h1{margin:0;font:500 26px/1.05 var(--sf-display);letter-spacing:-.03em;text-wrap:balance;display:flex;align-items:center;gap:12px;overflow-wrap:anywhere}
+p{margin:0;color:var(--sf-muted);font-size:15px;text-wrap:pretty;overflow-wrap:anywhere}
+a{color:var(--sf-ink);text-underline-offset:3px}
+form{display:flex;flex-direction:column;gap:8px}
+.row{display:flex;align-items:baseline;justify-content:space-between;gap:12px}
+label{color:var(--sf-muted);font-size:13px}
+.tools{display:flex;gap:12px}
+.text{background:none;border:0;padding:0;color:var(--sf-muted);font:500 13px var(--sf-body);cursor:pointer;transition:color var(--sf-fast)}
+.text:hover{color:var(--sf-ink)}
+input,textarea{width:100%;background:transparent;color:var(--sf-ink);border:1px solid var(--sf-line-2);border-radius:6px;font:400 14px/1.5 var(--sf-mono);
+font-variant-ligatures:none;padding:11px 12px;transition:border-color var(--sf-fast)}
+input{height:44px}
+textarea{min-height:168px;resize:vertical}
+textarea.masked{-webkit-text-security:disc}
+input:hover,textarea:hover{border-color:var(--sf-line-3)}
+input:focus-visible,textarea:focus-visible,button:focus-visible,a:focus-visible{outline:2px solid var(--sf-ink);outline-offset:2px;border-color:var(--sf-line-3)}
+.error{color:var(--sf-danger);font-size:14px}
+.actions{display:flex;gap:12px;margin-top:8px}
+.btn{height:44px;padding:0 18px;border-radius:6px;font:500 15px var(--sf-body);cursor:pointer;transition:border-color var(--sf-fast),opacity var(--sf-fast)}
+.primary{background:var(--sf-ink);color:var(--sf-bg);border:1px solid var(--sf-ink)}
+.primary:disabled{opacity:.6;cursor:default}
+.ghost{background:transparent;color:var(--sf-ink);border:1px solid var(--sf-line-2)}
+.ghost:hover{border-color:var(--sf-line-3)}
+.note{color:var(--sf-dim);font-size:13px;border-top:1px solid var(--sf-line);padding-top:16px}
+.ok{color:var(--sf-success);flex:none}
+.bad{color:var(--sf-danger)}
+[hidden]{display:none!important}
+`;
+function shell(title, body, script = '') {
+    return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">` +
+        `<meta name="referrer" content="no-referrer"><meta name="robots" content="noindex"><title>${esc(title)} · Shardflux</title>` +
+        `<link rel="icon" href="${FAVICON}"><style nonce="%NONCE%">${STYLE}</style></head><body><main>` +
+        `<div class="lockup">${MARK}<span>shardflux</span></div>${body}</main>${script ? `<script nonce="%NONCE%">${script}</script>` : ''}</body></html>`;
+}
+const CHECK = '<svg class="ok" viewBox="0 0 16 16" width="22" height="22" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M3 8.5l3.2 3L13 4.5"/></svg>';
+function statusPage(heading, text, tone) {
+    return shell(heading, `<h1>${tone === 'done' ? CHECK : ''}<span>${esc(heading)}</span></h1><p${tone === 'failed' ? ' class="bad"' : ''}>${esc(text)}</p>`);
+}
+// Show/hide, the multi-line switch for secrets, and one submit at a time. Everything works without it except Show.
+const SCRIPT = `(()=>{const f=document.getElementById('f'),show=document.getElementById('show'),lines=document.getElementById('lines'),save=document.getElementById('save');
+const field=()=>f.querySelector('[name=value]:not([disabled])');
+if(show)show.addEventListener('click',()=>{const el=field();const hidden=el.tagName==='INPUT'?el.type==='password':el.classList.contains('masked');
+if(el.tagName==='INPUT')el.type=hidden?'text':'password';else el.classList.toggle('masked',!hidden);
+show.textContent=hidden?'Hide':'Show';show.setAttribute('aria-pressed',String(hidden));el.focus();});
+if(lines)lines.addEventListener('click',()=>{const i=document.getElementById('v'),t=document.getElementById('t');
+t.classList.toggle('masked',i.type==='password');t.value=i.value;i.value='';i.disabled=true;i.hidden=true;t.disabled=false;t.hidden=false;lines.hidden=true;t.focus();});
+let sent=false;f.addEventListener('submit',e=>{if(sent){e.preventDefault();return;}sent=true;setTimeout(()=>{save.disabled=true;save.textContent=save.dataset.busy;});});})();`;
+function formPage(p, action, nonce, error, timeoutMs) {
+    const common = 'name="value" autocomplete="off" autocapitalize="off" autocorrect="off" spellcheck="false" data-1p-ignore data-lpignore="true"';
+    const field = p.kind === 'file'
+        ? `<textarea id="v" class="masked" ${common} required autofocus></textarea>`
+        : p.kind === 'code'
+            ? `<input id="v" type="text" ${common} required autofocus>`
+            : `<input id="v" type="password" ${common} required autofocus><textarea id="t" ${common} hidden disabled></textarea>`;
+    const tools = p.kind === 'code' ? '' : `<span class="tools">${p.kind === 'secret' ? '<button type="button" class="text" id="lines">Multiple lines</button>' : ''}<button type="button" class="text" id="show" aria-pressed="false">Show</button></span>`;
+    const link = p.link ? `<p><a href="${esc(p.link.href)}" target="_blank" rel="noreferrer noopener">${esc(p.link.text)}</a></p>` : '';
+    const minutes = Math.max(1, Math.round(timeoutMs / 60_000));
+    return shell(p.title, `<h1><span>${esc(p.title)}</span></h1><p>${esc(p.purpose)}</p>${link}` +
+        `<form id="f" method="post" action="${esc(action)}" accept-charset="utf-8" autocomplete="off">` +
+        `<input type="hidden" name="nonce" value="${esc(nonce)}"><div class="row"><label for="v">${esc(p.label)}</label>${tools}</div>${field}` +
+        `${error ? `<p class="error" role="alert">${esc(error)}</p>` : ''}</form>` +
+        `<form id="c" method="post" action="${esc(action)}" hidden><input type="hidden" name="nonce" value="${esc(nonce)}"><input type="hidden" name="action" value="cancel"></form>` +
+        `<div class="actions"><button type="submit" form="f" class="btn primary" id="save" data-busy="${p.kind === 'code' ? 'Signing in…' : 'Saving…'}">${esc(p.submit)}</button>` +
+        `<button type="submit" form="c" class="btn ghost">Cancel</button></div>` +
+        `<p class="note">Served by shard on your computer. It closes after one use or in ${minutes} minute${minutes === 1 ? '' : 's'}.</p>`, SCRIPT);
+}
+/** What the person is told an asking command did: an NDJSON event with --json, else one line on stderr. */
+export function announce(ctx, event, line) {
+    if (ctx.json)
+        ctx.io.stdout.write(`${JSON.stringify(event)}\n`);
+    else
+        ctx.io.stderr.write(`${line}\n`);
+}
+/** Opens `url` in the browser; whether it opened (the link is printed either way). */
+export async function openInBrowser(ctx, url) {
+    try {
+        return await openUrl(url, ctx.io.env);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Asks the person on the page and runs the command's action with the value: opens the page (printing its link), says
+ * so (`{"event":"open","url":...,"opened":...,"expires_in":...}` with --json), and resolves once the action succeeded.
+ */
+export async function askInBrowser(ctx, ask) {
+    const server = await startAsk({
+        ...ask,
+        signal: ask.signal ? AbortSignal.any([ctx.signal, ask.signal]) : ctx.signal,
+        use: async (value) => {
+            ctx.addSecret(value);
+            return ask.use(value);
+        },
+    });
+    const opened = await openInBrowser(ctx, server.url);
+    announce(ctx, { event: ask.event ?? 'open', url: server.url, opened, expires_in: Math.round(ask.timeoutMs / 1000) }, opened ? `Opened a page in your browser ${ask.doing} (or open: ${server.url})` : `Open this page ${ask.doing}: ${server.url}`);
+    return server.result;
+}

package/dist/seed-phases.d.ts

@@ -1,6 +1,7 @@
 /**
  * The start path's phase clock. SHARDFLUX_TRACE_SEED=1 prints how long each phase of a conversation start took
- * (`seed <phase> <ms> ms`) on stderr, for measurements and support. Silent otherwise.
+ * (`seed <phase> <ms> ms @<epoch ms>`) on stderr, for measurements and support, up to the first prompt's Enter. The
+ * wall clock lets a measurement line the phases up with the server's logs. Silent otherwise.
  *
  * The same marks drive the launchers' phase line (0.19.0+): with SHARDFLUX_PROGRESS_FILE set to a private file the
  * launcher created, a start rewrites that file with the phase it is in, as one JSON line
@@ -11,10 +12,14 @@ export type StartPhase = 'computer' | 'project' | 'checkout' | 'copy_changes' |
 type App = 'claude' | 'codex';
 export declare const startPhaseLine: (phase: StartPhase, app: App) => string;
 export declare function seedPhase(name: string, env?: Record<string, string | undefined>): void;
+/** A moment of the start that happened elsewhere (the VM's own clock), for the same trace: `seed <name> 0 ms @<epoch>`. */
+export declare function seedEvent(name: string, epochMs: number, env?: Record<string, string | undefined>): void;
 /** A conversation start begins: the launcher's file (if any) is remembered and the first phase is written. */
 export declare function startProgress(app: App, env?: Record<string, string | undefined>): void;
 /** Moves the current start to this phase; the file is rewritten only when the phase changes. */
 export declare function startPhase(phase: StartPhase): void;
+/** Accepted identity survives later phase updates and the foreground deadline. */
+export declare function acceptedProgress(conversation: string, key: string): void;
 /**
  * The caller's own private file in the caller's own private directory: a regular file (a symlink is refused, never
  * followed) owned by this user with no group or other access, in a directory owned by this user that nobody else can
@@ -28,5 +33,7 @@ export declare function privateProgressFile(file: string): boolean;
 export declare function writeProgress(file: string, doc: {
     phase: string;
     line: string;
+    conversation_id?: string;
+    workspace_key?: string;
 }): boolean;
 export {};

package/dist/seed-phases.js

@@ -13,6 +13,7 @@ const NEXT = {
     apply_history: 'checkout',
     local_changes: 'checkout',
     checkout_head: 'copy_changes',
+    prepared_transfer: 'checkout',
     seed_done: 'harness',
 };
 let last = performance.now();
@@ -20,12 +21,17 @@ let target = null;
 export function seedPhase(name, env = process.env) {
     const now = performance.now();
     if (env.SHARDFLUX_TRACE_SEED)
-        process.stderr.write(`seed ${name} ${Math.round(now - last)} ms\n`);
+        process.stderr.write(`seed ${name} ${Math.round(now - last)} ms @${Math.round(performance.timeOrigin + now)}\n`);
     last = now;
     const next = NEXT[name];
     if (next)
         startPhase(next);
 }
+/** A moment of the start that happened elsewhere (the VM's own clock), for the same trace: `seed <name> 0 ms @<epoch>`. */
+export function seedEvent(name, epochMs, env = process.env) {
+    if (env.SHARDFLUX_TRACE_SEED && Number.isFinite(epochMs))
+        process.stderr.write(`seed ${name} 0 ms @${Math.round(epochMs)}\n`);
+}
 /** A conversation start begins: the launcher's file (if any) is remembered and the first phase is written. */
 export function startProgress(app, env = process.env) {
     const file = env.SHARDFLUX_PROGRESS_FILE;
@@ -37,7 +43,16 @@ export function startPhase(phase) {
     if (!target || target.phase === phase)
         return;
     target.phase = phase;
-    writeProgress(target.file, { phase, line: startPhaseLine(phase, target.app) });
+    writeProgress(target.file, { phase, line: startPhaseLine(phase, target.app), ...(target.conversation_id ? { conversation_id: target.conversation_id, workspace_key: target.workspace_key } : {}) });
+}
+/** Accepted identity survives later phase updates and the foreground deadline. */
+export function acceptedProgress(conversation, key) {
+    if (!target)
+        return;
+    target.conversation_id = conversation;
+    target.workspace_key = key;
+    const phase = target.phase ?? 'computer';
+    writeProgress(target.file, { phase, line: startPhaseLine(phase, target.app), conversation_id: conversation, workspace_key: key });
 }
 /**
  * The caller's own private file in the caller's own private directory: a regular file (a symlink is refused, never

package/dist/setup-cache.d.ts

@@ -1,5 +1,12 @@
 import type { Workspace } from '@shardflux/sdk';
 import type { Ctx } from './commands.js';
 export declare const SETUP_CACHE_PATH = "/mnt/shardflux-cache";
+export declare const SETUP_CACHE_LOG = "setup-cache.log";
 /** Uses ordinary fenced shared-volume operations, after the managed PTY starts. */
 export declare function prepareSetupCache(ctx: Ctx, workspace: Workspace): Promise<void>;
+/**
+ * The account cache is optional: without it the conversation runs and setup caches in its own workspace
+ * (`shard template` reports `cache_scope`). A failure is a JSON line in setup-cache.log of the config directory, with
+ * the API's code, reason and request id, never terminal output (0.21.1+). The log starts over past 64 KiB.
+ */
+export declare function recordSetupCacheFailure(ctx: Ctx, workspace: Workspace, error: unknown): void;

package/dist/setup-cache.js

@@ -1,5 +1,10 @@
+import { appendFileSync, mkdirSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ShardfluxApiError } from '@shardflux/sdk';
 const name = 'shardflux-setup-cache';
 export const SETUP_CACHE_PATH = '/mnt/shardflux-cache';
+export const SETUP_CACHE_LOG = 'setup-cache.log';
+const LOG_MAX_BYTES = 64 * 1024;
 /** Uses ordinary fenced shared-volume operations, after the managed PTY starts. */
 export async function prepareSetupCache(ctx, workspace) {
     const cloud = ctx.cloud();
@@ -9,3 +14,30 @@ export async function prepareSetupCache(ctx, workspace) {
         throw new Error('account setup cache is not available');
     await cloud.volumes.attach(workspace.id, { volumeId: volume.id, mountPath: SETUP_CACHE_PATH, wait });
 }
+/**
+ * The account cache is optional: without it the conversation runs and setup caches in its own workspace
+ * (`shard template` reports `cache_scope`). A failure is a JSON line in setup-cache.log of the config directory, with
+ * the API's code, reason and request id, never terminal output (0.21.1+). The log starts over past 64 KiB.
+ */
+export function recordSetupCacheFailure(ctx, workspace, error) {
+    const api = error instanceof ShardfluxApiError ? error : undefined;
+    const line = JSON.stringify({
+        at: new Date().toISOString(), workspace_id: workspace.id, project_id: workspace.data.project_id,
+        message: error instanceof Error ? error.message : String(error),
+        ...(api ? { code: api.code, reason: api.reason ?? null, request_id: api.requestId || null } : {}),
+    }) + '\n';
+    try {
+        mkdirSync(ctx.store.dir, { recursive: true, mode: 0o700 });
+        const file = join(ctx.store.dir, SETUP_CACHE_LOG);
+        let size = 0;
+        try {
+            size = statSync(file).size;
+        }
+        catch { /* first failure */ }
+        if (size > LOG_MAX_BYTES)
+            writeFileSync(file, line, { mode: 0o600 });
+        else
+            appendFileSync(file, line, { mode: 0o600 });
+    }
+    catch { /* the trace is best effort, like the cache itself */ }
+}

package/dist/t3-launch.d.ts

@@ -32,6 +32,7 @@ export declare function launchT3(ctx: Ctx, values: Values, path: string, explici
 export declare function t3Fields(ws: Workspace, project: string, install: T3Install | undefined, started: T3ThreadResult | undefined, conversation?: string | null): Record<string, unknown>;
 /**
  * `agents open t3 <conversation>` for a conversation that runs on T3's Shardflux provider (ACP mode): T3 is brought to
- * the front with that thread's id. A conversation of another route opens its VM as T3's SSH environment.
+ * the front with that thread's id. A Codex Cloud conversation opens its Codex chat; a conversation of another route
+ * opens its VM as T3's SSH environment.
  */
 export declare function openT3Conversation(ctx: Ctx, conversationId: string, values?: Values): Promise<number>;