@north-light/api 0.3.580 → 0.3.588

package/dist/commands/sys/signin.js

@@ -0,0 +1,149 @@
+// `crtr sys signin` / `crtr sys signout`: the person's own sign-in on this computer (proposal-mac-cli-auth, option A).
+import { spawn } from 'node:child_process';
+import { mkdirSync, openSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { defineLeaf } from '../../core/command.js';
+import { CrtrError } from '../../core/errors.js';
+import { signIn, signOut } from '../../core/directory/person-credential.js';
+import { moveRecordPath, readMachineConfig } from '../../daemon/machine-link/config.js';
+import { sanitizedDaemonEnv, spawnDaemon, stopAllDaemons } from '../../daemon/manage.js';
+import { northlightUnreachable } from '../../core/directory/reach.js';
+import { envNodeId } from '../../shared/env.js';
+import { ExitCode } from '../../types.js';
+import { insideBroker } from './join.js';
+import { cliClient } from '../api-client.js';
+import { defaultDirectoryUrl, finishMove, runMove, settleEarlierMove } from './import/move.js';
+import { WAIT_FOR_PID_ENV } from './import/start.js';
+/** Open the confirm page in the person's browser; a failure to open it is harmless because the code and address are printed too. */
+function openBrowser(url) {
+    const [command, args] = process.platform === 'darwin' ? ['open', [url]] : ['xdg-open', [url]];
+    try {
+        spawn(command, args, { stdio: 'ignore', detached: true }).on('error', () => undefined).unref();
+    }
+    catch { /* printed below */ }
+}
+/** Print the pairing code and open the confirm page: what the person sees while `signIn` polls. */
+export function showSignIn(prompt) {
+    process.stderr.write(`Confirm this code at ${prompt.verificationUri}: ${prompt.userCode}\n`);
+    openBrowser(prompt.complete);
+}
+/** On a moved computer, refuse a sign-in to any account but the one its records moved into: the control plane answers `GET /v1/imports/<run>` only
+ *  to the run's own person (404 `import_not_found` to anyone else). */
+function sameAccountOnly(machine) {
+    return async (approved) => {
+        let response;
+        try {
+            response = await fetch(new URL(`/v1/imports/${machine.runId}`, machine.apiUrl), { headers: { authorization: `Bearer ${approved.bearer}` }, signal: AbortSignal.timeout(30_000) });
+        }
+        catch (error) {
+            return northlightUnreachable(error, machine.apiUrl);
+        }
+        if (response.ok)
+            return undefined;
+        if (response.status === 404) {
+            return new CrtrError('signin_other_account', `This computer's crtr belongs to the Northlight account ${machine.account?.display ?? 'it was moved into'}. Sign in to that account.`, ExitCode.USAGE);
+        }
+        return new CrtrError('signin_unchecked', `the control plane did not say which account owns this computer (HTTP ${response.status}); nothing was written.`, ExitCode.GENERAL, { next: 'Retry `crtr sys signin`.' });
+    };
+}
+/** Start the move in a process of its own: a node's tool call cannot run it, because the drain waits for that very turn to end and the restart
+ *  ends the broker it runs under. The exporter waits for this process to exit, so it is outside every broker's process tree when it drains. */
+function startDetachedMove(notify) {
+    const log = join(dirname(moveRecordPath()), 'move.log');
+    mkdirSync(dirname(log), { recursive: true });
+    const fd = openSync(log, 'a', 0o600);
+    const env = sanitizedDaemonEnv();
+    for (const key of ['CRTR_API_SOCKET', 'CRTR_API_TOKEN', 'CRTR_API_URL'])
+        delete env[key];
+    env[WAIT_FOR_PID_ENV] = String(process.pid);
+    const args = [...process.execArgv, process.argv[1], 'sys', 'import', 'start', '--kind', 'machine', ...(notify === undefined ? [] : ['--notify', notify])];
+    spawn(process.execPath, args, { detached: true, stdio: ['ignore', fd, fd], env }).unref();
+}
+const MOVING = (account) => `Signed in as ${account}. crtr is now moving this computer's records to Northlight; every agent here pauses for seconds to minutes. End your turn now; this conversation carries on when the move finishes.`;
+export const sysSigninLeaf = defineLeaf({
+    name: 'signin',
+    description: 'sign this computer\'s crtr in to the person\'s Northlight account',
+    whenToUse: 'the person agreed to sign in to Northlight (a Northlight command needs the account, or they asked), or a command answered `not_signed_in` or `move_unfinished`',
+    help: {
+        name: 'sys signin',
+        summary: 'pair this computer with the person\'s Northlight account in the browser, then move this computer\'s records into it',
+        guide: 'Prints a code and opens the directory\'s confirm page; the person signs in or signs up there if asked, checks the code and clicks Allow. The command waits for that. On a computer whose records are still local it then moves them into the account: run from a terminal it prints each step and returns when done; run from inside a node it returns at once and the node is messaged when the move finishes or fails. A computer already moved accepts only the account it moved into. For an unfinished move (`move_unfinished`), it checks the account\'s move result and finishes the switch-over if the records arrived. If the stored sign-in is missing or revoked, it first pairs only the account recorded for that move. Until the result is known, agents remain paused. The sign-in ends after 90 days without use, when revoked on the account page, or with `crtr sys signout`.',
+        params: [
+            { kind: 'flag', name: 'directory-url', type: 'string', required: false, constraint: 'Directory base URL (http or https). Default: the one in `runtime/machine.json`, else the stored sign-in\'s, else Northlight\'s.' },
+        ],
+        output: [
+            { name: 'account', type: 'string', required: true, constraint: 'The account this computer is now signed in as.' },
+            { name: 'moved', type: 'boolean', required: false, constraint: 'Present when this command moved the records, or finished an earlier move\'s switch-over.' },
+            { name: 'moving', type: 'boolean', required: false, constraint: 'Present when the move runs on in its own process (run from inside a node): end the turn; the node is messaged when it finishes or fails.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Calls the directory (`POST /v1/developer/logins`, then polls `/v1/developer/logins/poll`) and, once approved, writes `runtime/secrets/person-credential` (0600) and replaces the cached bearer. A declined, abandoned or refused sign-in writes nothing and leaves an existing sign-in as it was.',
+            'On a computer whose records are local: the move of `crtr sys import start --kind machine` (drains the daemon, uploads, restarts it in machine role); a move confirmed failed before the account holds the records ends the drain and signs this computer out again. If the account\'s result is unknown, the move record and drain remain for recovery. From inside a node it runs as a detached process logging to `runtime/import/move.log`.',
+            'On a moved computer: restarts the daemon so it reconnects to Northlight.',
+        ],
+    },
+    run: async (input) => {
+        const directoryUrl = input.directoryUrl === undefined ? defaultDirectoryUrl() : String(input.directoryUrl);
+        const unfinished = await settleEarlierMove(showSignIn);
+        if (unfinished !== undefined) {
+            if (insideBroker()) {
+                startDetachedMove(undefined);
+                return { account: unfinished.account.display, moving: true };
+            }
+            await finishMove(unfinished);
+            return { account: unfinished.account.display, moved: true };
+        }
+        const machine = readMachineConfig();
+        if (machine !== undefined) {
+            const { account } = await signIn(directoryUrl, showSignIn, { accept: sameAccountOnly(machine) });
+            await stopAllDaemons();
+            await spawnDaemon();
+            return { account };
+        }
+        const { account } = await signIn(directoryUrl, showSignIn);
+        if (insideBroker()) {
+            startDetachedMove(envNodeId());
+            return { account, moving: true };
+        }
+        await runMove({ directoryUrl, notify: null });
+        return { account, moved: true };
+    },
+    render: (r) => r['moving'] === true
+        ? `<signin account="${r['account']}" moving="true">${MOVING(String(r['account']))}</signin>`
+        : `<signin account="${r['account']}"${r['moved'] === true ? ' moved="true"' : ''}/>`,
+});
+/** Restart crtrd on a moved computer after sign-out; the machine daemon, finding no sign-in, stops every agent and cron on this computer and only
+ *  then answers `/healthz` with `signed_in: false`. Answers whether it did. */
+async function stopMovedComputer() {
+    await stopAllDaemons();
+    await spawnDaemon();
+    const health = await cliClient({ local: true }).healthz();
+    return health.signed_in === false;
+}
+export const sysSignoutLeaf = defineLeaf({
+    name: 'signout',
+    description: 'sign this computer\'s crtr out, revoke its credential, and stop its agents',
+    whenToUse: 'this computer should stop acting as the person on Northlight, or its stored sign-in may have leaked',
+    help: {
+        name: 'sys signout',
+        summary: 'revoke the stored credential, delete it from this computer, and on a moved computer stop every agent and cron here',
+        params: [],
+        output: [
+            { name: 'signed_out', type: 'boolean', required: true, constraint: 'False when no sign-in was stored.' },
+            { name: 'revoked', type: 'boolean', required: true, constraint: 'True when the directory ended the credential now; false when it was already ended or none was stored.' },
+            { name: 'stopped', type: 'boolean', required: true, constraint: 'True when this computer\'s records are in Northlight and its agents and running crons have stopped; false on a computer whose records are local, where nothing else is tied to the sign-in.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Calls `POST /v1/developer/token/revoke` with the stored secret, then deletes `runtime/secrets/person-credential` and `person-bearer.json`. A bearer already issued stays valid for at most 5 minutes.',
+            'On a computer whose records are in Northlight: restarts the daemon, which stops every agent and running cron here and takes no new work until `crtr sys signin`; agents keep their mail on Northlight and wake after it. Commands answer `not_signed_in`.',
+        ],
+    },
+    run: async () => {
+        const { signedOut, revoked } = await signOut();
+        const stopped = readMachineConfig() === undefined ? false : await stopMovedComputer();
+        return { signed_out: signedOut, revoked, stopped };
+    },
+    render: (r) => `<signout signed_out="${r['signed_out']}" revoked="${r['revoked']}" stopped="${r['stopped']}"/>`,
+});

package/dist/commands/sys/spaces.d.ts

@@ -0,0 +1 @@
+export declare const sysSpacesLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/sys/spaces.js

@@ -0,0 +1,22 @@
+import { defineLeaf } from '../../core/command.js';
+import { cliClient } from '../api-client.js';
+import { formatSize } from './worktrees.js';
+export const sysSpacesLeaf = defineLeaf({
+    name: 'spaces',
+    description: 'list every space on the runtime with its size',
+    whenToUse: 'you need to see how much disk the person\'s space and each app\'s space occupy on this runtime',
+    help: {
+        name: 'sys spaces',
+        summary: 'list the person\'s space and every app space with its size',
+        params: [],
+        output: [
+            { name: 'spaces', type: 'SpaceDTO[]', required: true, constraint: '`user` first, then each app space by id. Each record: {space, path, size_bytes}; size_bytes is null when the space cannot be measured.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async () => ({ spaces: (await cliClient().listSpaces()).spaces }),
+    render: (result) => result['spaces']
+        .map((s) => `- \`${s.space}\` — ${formatSize(s.size_bytes)} · \`${s.path}\``)
+        .join('\n'),
+});

package/dist/commands/sys/spend.d.ts

@@ -0,0 +1 @@
+export declare const sysSpendBranch: import("../../core/command.js").BranchDef;

package/dist/commands/sys/spend.js

@@ -0,0 +1,144 @@
+import { defineBranch, defineLeaf } from '../../core/command.js';
+import { InputError } from '../../core/io.js';
+import { cliClient } from '../api-client.js';
+const usd = (value) => value === null ? 'unpriced' : `$${value.toFixed(value < 1 ? 4 : 2)}`;
+const filters = (l) => [l.funding && `funding ${l.funding}`, l.grantee && `grantee ${l.grantee}`, l.provider && `provider ${l.provider}`, l.sub && `sub ${l.sub}`].filter(Boolean).join(', ') || 'everything';
+const limitLine = (l) => `- \`${l.id}\` ${l.payer ?? l.account} ${usd(l.usd_per_month)}/month on ${filters(l)} (${l.source})`;
+const show = defineLeaf({
+    name: 'show',
+    description: 'show a month\'s spend by payer and funding, with the limits',
+    whenToUse: 'checking what a payer has spent this month and which limits apply',
+    help: {
+        name: 'sys spend show',
+        summary: 'month totals by payer and by payer and funding from the ledger, then every limit row',
+        params: [{ kind: 'flag', name: 'month', type: 'string', required: false, constraint: 'UTC month YYYY-MM. Default: the current month.' }],
+        output: [
+            { name: 'month', type: 'string', required: true, constraint: 'The month shown, YYYY-MM.' },
+            { name: 'totals', type: 'ChargeTotalsDTO', required: true, constraint: 'Record: {month, by_payer, by_funding, limits}. Migrated user-paid model history has funding `legacy`.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const out = await cliClient().listCharges({ limit: 1, ...(input['month'] === undefined ? {} : { month: String(input['month']) }) });
+        // The route returns totals and limits to the person only; a node or app caller sees just its own app's rows.
+        if (out.totals === undefined) {
+            throw new InputError({ error: 'owner_only', message: 'month totals and limits are read by the person; this caller sees only its own app\'s charges', next: 'Run `crtr sys spend show` from the person\'s own shell, not from inside a node.' });
+        }
+        return { month: out.month, totals: out.totals };
+    },
+    render: (result) => {
+        const totals = result['totals'];
+        return [
+            `Spend for ${totals.month}:`,
+            ...(totals.by_payer.length === 0 ? ['- nothing charged'] : totals.by_payer.map((p) => `- ${p.payer} ${usd(p.usd)}${totals.by_funding.filter((f) => f.payer === p.payer).map((f) => `  ${f.funding} ${usd(f.usd)}`).join('')}`)),
+            'Limits:',
+            ...(totals.limits.length === 0 ? ['- none'] : totals.limits.map(limitLine)),
+        ].join('\n');
+    },
+});
+function tree(rows) {
+    const byProvider = new Map();
+    for (const row of rows)
+        byProvider.set(row.provider ?? '(none)', (byProvider.get(row.provider ?? '(none)') ?? 0) + (row.usd ?? 0));
+    const ids = new Set(rows.map((r) => r.request));
+    const children = (parent) => rows.filter((r) => (r.caused_by ?? null) === parent);
+    const lines = [];
+    const seen = new Set();
+    const print = (row, depth) => {
+        if (seen.has(row.id))
+            return;
+        seen.add(row.id);
+        lines.push(`${'  '.repeat(depth)}- ${row.at} ${row.kind} ${row.what} ${usd(row.usd)} ${row.payer}/${row.funding}${row.provider ? ` → ${row.provider}` : ''} vendor_ref ${row.vendor_ref ?? 'none'}${row.refused ? ` REFUSED by ${row.refused.limit}` : ''}`);
+        if (row.request !== null)
+            for (const child of children(`request:${row.request}`))
+                print(child, depth + 1);
+    };
+    const roots = rows.filter((r) => r.caused_by === null || !(r.caused_by.startsWith('request:') && ids.has(r.caused_by.slice(8))));
+    for (const row of roots)
+        print(row, 0);
+    for (const row of rows)
+        print(row, 0);
+    return [...lines, 'Total per provider:', ...[...byProvider].map(([p, v]) => `- ${p} ${usd(v)}`)].join('\n');
+}
+const chain = defineLeaf({
+    name: 'chain',
+    description: 'list the charge rows under a run, message, request or charge on this runtime',
+    whenToUse: 'finding what one run, message or request cost and matching its vendor_ref to a vendor\'s usage line',
+    help: {
+        name: 'sys spend chain',
+        summary: 'the rows under a reference as a tree, with each row\'s vendor_ref and a total per provider',
+        params: [{ kind: 'positional', name: 'reference', type: 'string', required: true, constraint: '`run:<id>`, `message:<id>`, `request:<id>`, `cron_run:<id>` or a charge id. Reads this runtime only.' }],
+        output: [
+            { name: 'reference', type: 'string', required: true, constraint: 'The reference read.' },
+            { name: 'charges', type: 'ChargeDTO[]', required: true, constraint: 'Rows in time order; empty when this runtime holds none under the reference.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const reference = String(input['reference']);
+        const charges = [];
+        for (let after;;) {
+            const page = await cliClient().listCharges({ under: reference, ...(after === undefined ? {} : { after }) });
+            charges.push(...page.charges);
+            if (page.next === null)
+                break;
+            after = page.next;
+        }
+        return { reference, charges };
+    },
+    render: (result) => {
+        const rows = result['charges'];
+        return rows.length === 0 ? `No charges under ${String(result['reference'])} on this runtime.` : tree(rows);
+    },
+});
+const limit = defineLeaf({
+    name: 'limit',
+    description: 'set or clear one of the person\'s dollar limits',
+    whenToUse: 'stopping a payer\'s spend (0 is an emergency stop) or capping it per month; clearing a limit you set',
+    help: {
+        name: 'sys spend limit',
+        summary: 'write or remove the limit row `person:<name>`; the check refuses calls billed to the payer once the month reaches it',
+        params: [
+            { kind: 'positional', name: 'name', type: 'string', required: true, constraint: 'A name for the row; the id is `person:<name>`.' },
+            { kind: 'flag', name: 'payer', type: 'string', required: false, constraint: '`user:<id>` (the person) or `app:<id>`. Required unless --clear.' },
+            { kind: 'flag', name: 'usd', type: 'string', required: false, constraint: 'Dollars per month, 0 or more; 0 stops the payer. Required unless --clear.' },
+            { kind: 'flag', name: 'funding', type: 'enum', choices: ['bill', 'subscription', 'key', 'endpoint', 'take', 'legacy'], required: false, constraint: 'Limit only this funding. Default: any.' },
+            { kind: 'flag', name: 'grantee', type: 'string', required: false, constraint: 'Limit only charges attributed to this app, such as `app:terminal`. Default: any.' },
+            { kind: 'flag', name: 'provider', type: 'string', required: false, constraint: 'Limit only money going to this vendor or provider app, such as `anthropic`. Default: any.' },
+            { kind: 'flag', name: 'clear', type: 'bool', required: false, constraint: 'Remove the row instead of writing it.' },
+        ],
+        output: [
+            { name: 'limit', type: 'LimitDTO', required: false, constraint: 'The row written; absent with --clear.' },
+            { name: 'removed', type: 'string', required: false, constraint: 'The id removed with --clear.' },
+        ],
+        outputKind: 'object',
+        effects: ['Writes or deletes one `limits` row with source `person`. Takes effect on the next call.'],
+    },
+    run: async (input) => {
+        const id = `person:${String(input['name'])}`;
+        if (input['clear'] === true)
+            return { removed: (await cliClient().removeSpendLimit(id)).id };
+        const dollars = input['usd'] === undefined ? Number.NaN : Number(input['usd']);
+        if (typeof input['payer'] !== 'string' || !Number.isFinite(dollars) || dollars < 0) {
+            throw new InputError({ error: 'nothing_to_set', message: 'a limit needs --payer and --usd (0 or more), or --clear', next: 'Pass --payer user:<id> --usd 20, or --clear to remove the row.' });
+        }
+        const row = await cliClient().setSpendLimit(id, { payer: input['payer'], usd_per_month: dollars,
+            ...(input['funding'] === undefined ? {} : { funding: input['funding'] }),
+            ...(input['grantee'] === undefined ? {} : { grantee: String(input['grantee']) }), ...(input['provider'] === undefined ? {} : { provider: String(input['provider']) }) });
+        return { limit: row };
+    },
+    render: (result) => result['removed'] !== undefined ? `Removed ${String(result['removed'])}.` : limitLine(result['limit']),
+});
+export const sysSpendBranch = defineBranch({
+    name: 'spend',
+    description: 'the money ledger: spend by payer, the chain under a run, and dollar limits',
+    whenToUse: 'reading what was spent and why, or stopping or capping a payer\'s spend',
+    help: {
+        name: 'sys spend',
+        summary: 'read this runtime\'s charges and set the person\'s dollar limits',
+        model: 'Every model call and priced tool call is one charge row naming its payer, funding and cause. A limit row bounds a payer\'s month; the check refuses calls billed to that payer once it is reached. `sys limits` is the unrelated per-app memory and disk cap.',
+    },
+    children: [show, chain, limit],
+});

package/dist/commands/sys/support/prepare.d.ts

@@ -0,0 +1,13 @@
+import type { LeafDef } from '../../../core/command.js';
+export interface SupportPrepareResult {
+    status: 'prepared';
+    reference: string;
+    path: string;
+    node_id: string;
+    source_count: number;
+    bytes: number;
+}
+/** Output-free: collects and writes the prepared artifact and returns a
+ *  small result. Never prints; the leaf below owns argv/rendering. */
+export declare function prepareSupportBundle(nodeId: string): SupportPrepareResult;
+export declare const supportPrepareLeaf: LeafDef;

package/dist/commands/sys/support/prepare.js

@@ -0,0 +1,239 @@
+// `crtr sys support prepare` — the local, zero-egress half of the support
+// bundle flow. Collects one node's diagnostics into a bounded artifact that
+// satisfies the plain manifest/bundle shape `sys support submit` validates
+// before any upload; prepare never touches the network, gh, or a repository.
+import { randomBytes } from 'node:crypto';
+import { closeSync, constants as fsConstants, fstatSync, lstatSync, mkdirSync, openSync, readSync, rmSync, writeFileSync, } from 'node:fs';
+import { join, relative } from 'node:path';
+import { defineLeaf } from '../../../core/command.js';
+import { general, usage } from '../../../core/errors.js';
+import { crtrHome, isSafeNodeId, jobDir } from '../../../core/canvas/paths.js';
+import { MAX_EVENT_RECORD_BYTES } from '../../../core/events/serialize.js';
+import { readLogSnapshot } from '../../../core/events/read.js';
+import { userScopeRoot } from '../../../core/scope.js';
+const MANIFEST_NAME = 'manifest.json';
+const BUNDLE_NAME = 'bundle.jsonl';
+const CAP_BYTES = 2_097_152;
+const MAX_RUNTIME_STATE_BYTES = MAX_EVENT_RECORD_BYTES - 1;
+const CATEGORIES = ['events', 'runtime_state', 'raw_residue'];
+// reference generation
+function pad(value, length) {
+    return String(value).padStart(length, '0');
+}
+/** `YYYYMMDDTHHmmssSSSZ-xxxxxxxx`, matching submit's REFERENCE_PATTERN. */
+function generateReference(now) {
+    const date = `${now.getUTCFullYear()}${pad(now.getUTCMonth() + 1, 2)}${pad(now.getUTCDate(), 2)}`;
+    const time = `${pad(now.getUTCHours(), 2)}${pad(now.getUTCMinutes(), 2)}${pad(now.getUTCSeconds(), 2)}${pad(now.getUTCMilliseconds(), 3)}`;
+    return `${date}T${time}Z-${randomBytes(4).toString('hex')}`;
+}
+// compact bundle records
+function compactLine(record) {
+    return Buffer.from(`${JSON.stringify(record)}\n`, 'utf8');
+}
+/** Node-relevant canonical events plus visibly selected broker/daemon raw
+ *  residue, from the one bounded snapshot call this leaf is allowed. Returned
+ *  newest-first (the snapshot itself is chronological ascending) so that
+ *  `fitToCap`'s tail-drop trims the oldest history first. */
+function collectSnapshotRecords(nodeId, sources) {
+    const snapshot = readLogSnapshot({ nodeId }, true);
+    const records = [];
+    for (const item of snapshot.items) {
+        const category = item.kind === 'event' ? 'events' : 'raw_residue';
+        const ts = item.kind === 'event' ? item.envelope.ts : new Date(item.effectiveTsMs).toISOString();
+        const content = item.kind === 'event' ? item.envelope : item.content;
+        const existing = sources.get(item.source);
+        if (existing === undefined) {
+            sources.set(item.source, { category, status: 'read', truncated: item.truncated });
+        }
+        else if (item.truncated) {
+            existing.truncated = true;
+        }
+        records.push({ source: item.source, line: compactLine({ category, source: item.source, ts, content }) });
+    }
+    return records.reverse();
+}
+/** A single, shared, capped, no-symlink, identity-safe read of one fixed
+ *  state file — used for both job/fault and job/telemetry.json. Never follows
+ *  a symlink and confirms the fd it reads is the exact file it lstat'd. */
+function readFixedStateFile(absolute, maxBytes) {
+    let lst;
+    try {
+        lst = lstatSync(absolute);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { status: 'absent', truncated: false };
+        return { status: 'unreadable', truncated: false };
+    }
+    if (lst.isSymbolicLink() || !lst.isFile())
+        return { status: 'unreadable', truncated: false };
+    let fd;
+    try {
+        fd = openSync(absolute, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+    }
+    catch {
+        return { status: 'unreadable', truncated: false };
+    }
+    try {
+        const fst = fstatSync(fd);
+        if (!fst.isFile() || fst.dev !== lst.dev || fst.ino !== lst.ino)
+            return { status: 'raced', truncated: false };
+        if (!Number.isSafeInteger(fst.size) || fst.size < 0)
+            return { status: 'unreadable', truncated: false };
+        const length = Math.min(fst.size, maxBytes);
+        const buffer = Buffer.alloc(length);
+        let offset = 0;
+        while (offset < length) {
+            const got = readSync(fd, buffer, offset, length - offset, offset);
+            if (got <= 0)
+                return { status: 'unreadable', truncated: false };
+            offset += got;
+        }
+        let content;
+        try {
+            content = JSON.parse(buffer.toString('utf8'));
+        }
+        catch {
+            content = buffer.toString('utf8');
+        }
+        return { status: 'read', truncated: fst.size > maxBytes, content };
+    }
+    finally {
+        try {
+            closeSync(fd);
+        }
+        catch {
+            // Best effort; the read already succeeded or failed.
+        }
+    }
+}
+/** Current job/fault and job/telemetry.json, one shared safe read each. */
+function collectRuntimeState(nodeId, ts, sources) {
+    const dir = jobDir(nodeId);
+    const home = crtrHome();
+    const records = [];
+    for (const name of ['fault', 'telemetry.json']) {
+        const absolute = join(dir, name);
+        const label = relative(home, absolute);
+        const read = readFixedStateFile(absolute, MAX_RUNTIME_STATE_BYTES);
+        sources.set(label, { category: 'runtime_state', status: read.status, truncated: read.truncated });
+        if (read.status === 'read') {
+            records.push({ source: label, line: compactLine({ category: 'runtime_state', source: label, ts, content: read.content }) });
+        }
+    }
+    return records;
+}
+// manifest + cap fitting
+function renderManifestBuffer(base, sources) {
+    const manifest = {
+        reference: base.reference,
+        created_at: base.created_at,
+        node_id: base.node_id,
+        sources: [...sources.entries()].map(([source, state]) => ({
+            source,
+            category: state.category,
+            status: state.status,
+            truncated: state.truncated,
+        })),
+    };
+    return Buffer.from(`${JSON.stringify(manifest)}\n`, 'utf8');
+}
+/** Drop only trailing admitted records until manifest+bundle fit the cap.
+ *  Nothing in the manifest depends on the final byte count, so no fixed-point
+ *  convergence is needed — each drop can only flip a source's `truncated`
+ *  from false to true, and the loop is bounded by the record count. */
+function fitToCap(records, sources, base) {
+    const admitted = records.slice();
+    for (;;) {
+        const manifestBuffer = renderManifestBuffer(base, sources);
+        const bundleBuffer = Buffer.concat(admitted.map((record) => record.line));
+        if (manifestBuffer.length + bundleBuffer.length <= CAP_BYTES)
+            return { manifestBuffer, bundleBuffer };
+        if (admitted.length === 0)
+            throw general(`prepared support manifest alone exceeds the ${CAP_BYTES}-byte cap`);
+        const dropped = admitted.pop();
+        const state = sources.get(dropped.source);
+        if (state !== undefined)
+            state.truncated = true;
+    }
+}
+// core
+/** Output-free: collects and writes the prepared artifact and returns a
+ *  small result. Never prints; the leaf below owns argv/rendering. */
+export function prepareSupportBundle(nodeId) {
+    if (typeof nodeId !== 'string' || !isSafeNodeId(nodeId)) {
+        throw usage('node_id must be a safe, non-empty single path segment of at most 128 UTF-8 bytes.');
+    }
+    const referenceRoot = join(userScopeRoot(), 'support');
+    mkdirSync(referenceRoot, { recursive: true });
+    const reference = generateReference(new Date());
+    const dir = join(referenceRoot, reference);
+    mkdirSync(dir); // Exclusive: throws if `reference` already names anything.
+    try {
+        const createdAt = new Date().toISOString();
+        const sources = new Map();
+        // Tiny, high-value current state goes first so a cap-trim only ever drops
+        // from the (potentially large) historical event/residue tail, and drops
+        // the oldest of that tail first — never runtime_state, never the newest
+        // history — without any per-category budget or priority machinery.
+        const runtimeRecords = collectRuntimeState(nodeId, createdAt, sources);
+        const snapshotRecords = collectSnapshotRecords(nodeId, sources);
+        const records = [...runtimeRecords, ...snapshotRecords];
+        const { manifestBuffer, bundleBuffer } = fitToCap(records, sources, { reference, created_at: createdAt, node_id: nodeId });
+        writeFileSync(join(dir, MANIFEST_NAME), manifestBuffer, { flag: 'wx' });
+        writeFileSync(join(dir, BUNDLE_NAME), bundleBuffer, { flag: 'wx' });
+        return {
+            status: 'prepared',
+            reference,
+            path: dir,
+            node_id: nodeId,
+            source_count: sources.size,
+            bytes: manifestBuffer.length + bundleBuffer.length,
+        };
+    }
+    catch (error) {
+        rmSync(dir, { recursive: true, force: true });
+        throw error;
+    }
+}
+export const supportPrepareLeaf = defineLeaf({
+    name: 'prepare',
+    description: 'locally collect one node\u2019s diagnostics into a bounded support bundle (zero egress)',
+    whenToUse: 'you want to hand a maintainer diagnostics for one node without exposing anything beyond that node\u2019s canonical events, current fault/telemetry state, and residue mentioning it. This step never leaves the machine; run `crtr sys support submit <reference>` afterward to actually share it.',
+    help: {
+        name: 'sys support prepare',
+        summary: 'locally collect one node\u2019s bounded diagnostics into ~/.crouter/support/<reference>/manifest.json + bundle.jsonl',
+        params: [
+            {
+                kind: 'positional',
+                name: 'node_id',
+                required: true,
+                constraint: 'The node to collect diagnostics for — a safe, non-empty single path segment.',
+            },
+        ],
+        output: [
+            { name: 'reference', type: 'string', required: true, constraint: 'Generated YYYYMMDDTHHmmssSSSZ-xxxxxxxx — pass this to `crtr sys support submit`.' },
+            { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the new ~/.crouter/support/<reference>/ directory.' },
+            { name: 'source_count', type: 'number', required: true, constraint: 'Number of distinct sources declared in the manifest.' },
+            { name: 'bytes', type: 'number', required: true, constraint: 'Combined size of manifest.json + bundle.jsonl, always \u2264 2,097,152.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Reads only local diagnostic sources for node_id: canonical events (node-relevant across daemon/broker/web), current job/fault and job/telemetry.json, and broker/daemon raw residue mentioning the node.',
+            'Creates a new ~/.crouter/support/<reference>/ directory containing exactly manifest.json and bundle.jsonl, bounded to 2,097,152 combined bytes; removes that directory if preparation fails partway.',
+            'Performs no network, DNS, gh, or repository access — the bundle stays entirely local until an explicit `crtr sys support submit <reference>`.',
+        ],
+    },
+    run: async (input) => {
+        const nodeId = input['node_id'];
+        if (nodeId === undefined || nodeId === '')
+            throw usage('node_id is required. Run `crtr sys support prepare -h`.');
+        const result = prepareSupportBundle(nodeId);
+        return {
+            reference: result.reference,
+            path: result.path,
+            source_count: result.source_count,
+            bytes: result.bytes,
+        };
+    },
+});

package/dist/commands/sys/support/submit.d.ts

@@ -0,0 +1,19 @@
+import type { LeafDef } from '../../../core/command.js';
+export interface GhRunResult {
+    code: number | null;
+    stdout: Buffer;
+    stderr: string;
+    error?: Error;
+    /** HTTP status parsed from `gh api --include`; absent is deliberately indeterminate. */
+    httpStatus?: number;
+}
+export type GhRunner = (args: string[], input?: Buffer) => GhRunResult;
+export declare function defaultGhRunner(args: string[], input?: Buffer): GhRunResult;
+export interface SubmitResult {
+    status: 'submitted';
+    reference: string;
+    repository: string;
+    url: string;
+}
+export declare function submitPreparedBundle(reference: string, env: NodeJS.ProcessEnv, ghRunner?: GhRunner): Promise<SubmitResult>;
+export declare const supportSubmitLeaf: LeafDef;