@north-light/api 0.3.580 → 0.3.588

package/dist/commands/sys/import/move.js

@@ -0,0 +1,391 @@
+// The exporter's run (design-import "Exporter") and the move of a person's computer into their Northlight account (design-crtr-northlight-signin
+// component 4): `exportRun` uploads, drains, dumps and loads one run; `runMove` wraps it for a computer with the move record, the two commit
+// boundaries (the cloud run reaching `done`; activation) and the messages to the node that asked; `finishMove` is activation, shared with
+// `crtr sys signin` finishing an unfinished switch-over.
+import { mkdtempSync, readFileSync, readdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { CrtrError, general } from '../../../core/errors.js';
+import { ExitCode } from '../../../types.js';
+import { cliClient } from '../../api-client.js';
+import { ImportCloud, STORE_FILE, STORE_ORDER } from '../../../core/import/export/cloud.js';
+import { Uploader, localObjects, reviewSourceObject } from '../../../core/import/export/files.js';
+import { bundleKeys } from '../../../core/import/bundle/layout.js';
+import { crtrVersion } from '../../../shared/crtr-version.js';
+import { nodeArchive } from '../../../core/import/export/archive.js';
+import { buildSourceJson } from '../../../core/import/export/source.js';
+import { runDaemonBodiesDump, runDaemonImportDump, runDaemonInstallId, spawnDaemon, stopAllDaemons } from '../../../daemon/manage.js';
+import { deleteMoveRecord, moveUnfinishedError, readMachineConfig, readMoveRecord, writeMachineConfig, writeMachineCredential, writeMoveRecord } from '../../../daemon/machine-link/config.js';
+import { notifyMoveFinished } from '../../../daemon/machine-link/move-notify.js';
+import { controlPlaneUrl, forgetSignIn, personAccount, personBearer, readPersonCredential, signIn, signOut } from '../../../core/directory/person-credential.js';
+import { NORTHLIGHT_DIRECTORY_URL } from '../../../core/directory/issuer.js';
+import { isPidAlive } from '../../../core/canvas/pid.js';
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** The directory a sign-in or move uses when none is typed: `runtime/machine.json`'s, else the stored sign-in's, else Northlight's (design D5). */
+export function defaultDirectoryUrl() {
+    return readMachineConfig()?.directoryUrl ?? readPersonCredential()?.directoryUrl ?? NORTHLIGHT_DIRECTORY_URL;
+}
+/** End the daemon's drain and confirm the daemon answers `drained: false`, retrying a lost answer: the daemon persists its drain before it waits for
+ *  busy nodes, so a request that timed out or was lost may have left one on. Throws `drain_not_ended` when it cannot be confirmed ended.
+ *  The daemon refuses to end a drain while a move record exists (the cloud outcome may be unknown), so every caller here has a positive answer that
+ *  the run failed or never loaded: the record is settled (deleted) first, and no other path ends a computer's drain. */
+export async function endDrainConfirmed(client) {
+    let last = 'the daemon still reports a drain';
+    for (let attempt = 1; attempt <= 3; attempt++) {
+        try {
+            if ((await client.endDaemonDrain()).drained === false)
+                return;
+        }
+        catch (error) {
+            last = error instanceof Error ? error.message : String(error);
+        }
+        if (attempt < 3)
+            await sleep(1000);
+    }
+    throw new CrtrError('drain_not_ended', `the local daemon's pause could not be confirmed ended: ${last}`, ExitCode.GENERAL, { next: 'Run `crtr sys import resume`.' });
+}
+/** The drain's end once the exporter stops: a run that never reached `done` ends it, confirmed. A run that reached `done` leaves it on — a hosted
+ *  runtime for hosting's quiesce, a computer because its records now live in the account and local agents must not carry on against the local database. */
+export async function settleDrainAtEnd(done, client) {
+    if (done)
+        return;
+    await endDrainConfirmed(client);
+}
+const OUTCOME_RETRY_MAX_MS = 30_000;
+/** After `load` was sent the run's outcome is unknown until the control plane says it: wait for `done`, throw on `failed` / `rolled_back`, and keep asking
+ *  while the control plane cannot be reached or answers an error (a lost answer must never read as a failure: the account may hold the records). Only a
+ *  sign-in that no longer works, or an answer the control plane will repeat, ends the wait with `move_outcome_unknown`, because asking can never succeed again. A `load` that threw while the run
+ *  never left `uploading` did not start, so its error stands. */
+async function awaitRunOutcome(cloud, runId, loadError) {
+    let gap = 2000;
+    for (;;) {
+        let state;
+        try {
+            state = await cloud.get(runId);
+        }
+        catch (error) {
+            const status = error instanceof CrtrError ? error.details?.['status'] : undefined;
+            // A sign-in that no longer works, or a refusal the control plane will repeat: asking can never succeed, so the outcome stays unknown.
+            if (error instanceof CrtrError && (error.code === 'not_signed_in' || (typeof status === 'number' && status < 500 && status !== 408 && status !== 429))) {
+                throw new CrtrError('move_outcome_unknown', `could not confirm whether Northlight finished loading this computer's records: ${error.message}`, ExitCode.GENERAL, { next: 'Run `crtr sys signin` to settle the move.' });
+            }
+            process.stderr.write(`waiting for Northlight: ${error instanceof Error ? error.message : String(error)}\n`);
+            await sleep(gap);
+            gap = Math.min(gap * 2, OUTCOME_RETRY_MAX_MS);
+            continue;
+        }
+        gap = 2000;
+        if (state.state === 'done')
+            return;
+        if (state.state === 'failed' || state.state === 'rolled_back')
+            throw general(`the import failed at ${state.failure?.step ?? state.step ?? 'an unknown step'}: ${state.failure?.message ?? state.state}`, { code: state.failure?.code ?? 'import_failed' });
+        if (state.state === 'uploading' && loadError !== undefined)
+            throw loadError;
+        await sleep(2000);
+    }
+}
+/** One export: open the run (or use hosting's), upload blobs, drain, dump, upload rows and stores, load, wait for `done`. `step.name` is the step in
+ *  progress, so a failure can name it. The drain ends here when the run did not reach `done`, and stays on when it did. */
+export async function exportRun(kind, cloud, existingRun, step, onStarted = () => undefined, onFailed = () => undefined) {
+    let mark = Date.now();
+    const next = (finished, upcoming) => {
+        const now = Date.now();
+        const line = `${finished}=${((now - mark) / 1000).toFixed(1)}s`;
+        step.timings.push(line);
+        process.stderr.write(`${finished} ${((now - mark) / 1000).toFixed(1)}s\n`);
+        mark = now;
+        step.name = upcoming;
+    };
+    const out = mkdtempSync(join(tmpdir(), 'crtr-import-'));
+    const client = cliClient({ local: true });
+    let drained = false;
+    let done = false;
+    // True from the moment `load` is sent until the run is confirmed failed: the account may hold the records, so the drain must stay on.
+    let outcomeUnknown = false;
+    let failure;
+    try {
+        step.name = 'start';
+        const { installId } = await runDaemonInstallId();
+        const run = existingRun === undefined ? await cloud.start({ source_install_id: installId, source_kind: kind, release: crtrVersion() }) : { run_id: existingRun };
+        onStarted(run.run_id);
+        step.name = 'blobs';
+        const uploader = new Uploader(cloud, run.run_id, (line) => process.stderr.write(`${line}\n`));
+        await uploader.upload(localObjects());
+        // Every `bodies` row (revision text) while nodes still run: bodies never change once written, so the pause dump adds only the rows written since.
+        await runDaemonBodiesDump(out);
+        for (const file of readdirSync(join(out, 'rows', 'bodies')))
+            await uploader.uploadBytes(bundleKeys.bodyRows(run.run_id, file.replace(/\.jsonl\.zst$/, '')), readFileSync(join(out, 'rows', 'bodies', file)));
+        next('blobs', 'drain');
+        // Possibly on from the moment the request is sent: the daemon persists the drain before it waits for busy nodes.
+        drained = true;
+        await client.drainDaemon({ settle_limit_ms: 600_000 });
+        next('drain', 'dump');
+        await uploader.upload(localObjects());
+        const dump = await runDaemonImportDump(out, kind);
+        const extra = [];
+        for (const r of dump.requests) {
+            const o = reviewSourceObject(r.id, r.dir, r.file);
+            if (o !== null)
+                extra.push(o);
+        }
+        await uploader.upload(extra);
+        next('dump', 'upload');
+        for (const file of readdirSync(join(out, 'rows'), { withFileTypes: true })) {
+            if (file.isFile())
+                await uploader.uploadBytes(bundleKeys.rows(run.run_id, file.name.replace(/\.jsonl\.zst$/, '')), readFileSync(join(out, 'rows', file.name)));
+        }
+        // The pause dump's `bodies` parts; the pre-pause parts went up above.
+        const preParts = new Set(readdirSync(join(out, 'rows', 'bodies')).filter((f) => f.startsWith('pre-')));
+        for (const file of readdirSync(join(out, 'rows', 'bodies')))
+            if (!preParts.has(file))
+                await uploader.uploadBytes(bundleKeys.bodyRows(run.run_id, file.replace(/\.jsonl\.zst$/, '')), readFileSync(join(out, 'rows', 'bodies', file)));
+        const prefixes = [];
+        if (kind === 'hosted') {
+            for (const node of dump.runningNodes) {
+                const { data, prefixes: archived } = await nodeArchive(node);
+                prefixes.push(...archived);
+                await uploader.uploadBytes(bundleKeys.nodeFiles(run.run_id, node.node), data);
+            }
+        }
+        await uploader.uploadBytes(bundleKeys.source(run.run_id), Buffer.from(JSON.stringify(buildSourceJson(dump.source, prefixes))));
+        const stores = JSON.parse(readFileSync(join(out, STORE_FILE), 'utf8'));
+        for (const name of STORE_ORDER)
+            await cloud.putStore(run.run_id, name, stores[name]);
+        next('upload', 'load');
+        outcomeUnknown = true;
+        let loadError;
+        try {
+            await cloud.load(run.run_id);
+        }
+        catch (error) {
+            loadError = error;
+        }
+        try {
+            await awaitRunOutcome(cloud, run.run_id, loadError);
+        }
+        catch (error) {
+            if (!(error instanceof CrtrError && error.code === 'move_outcome_unknown'))
+                outcomeUnknown = false;
+            throw error;
+        }
+        outcomeUnknown = false;
+        done = true;
+        next('load', 'restart');
+        return run.run_id;
+    }
+    catch (error) {
+        failure = error;
+        throw error;
+    }
+    finally {
+        rmSync(out, { recursive: true, force: true });
+        // Only the exporter that owns this move settles its record, and only with a known failed outcome, before the daemon may end its drain.
+        if (!done && !outcomeUnknown)
+            onFailed();
+        if (drained && !outcomeUnknown) {
+            try {
+                await settleDrainAtEnd(done, client);
+            }
+            catch (error) {
+                if (failure === undefined)
+                    throw error;
+                const code = error instanceof CrtrError ? error.code : 'drain_not_ended';
+                throw new CrtrError(code, `${failure instanceof Error ? failure.message : String(failure)} (and ${error instanceof Error ? error.message : String(error)})`, ExitCode.GENERAL, { next: 'Run `crtr sys import resume`.' });
+            }
+        }
+    }
+}
+/** Activation, the second commit boundary: the asking node's message first (stored in the account as mail; the node can wake only once the machine
+ *  link is up), then the machine credential (re-minted with `rotate` when an earlier attempt already minted one), `machine.json`, a restart of
+ *  crtrd in machine role, and the move record's deletion. Safe to repeat. */
+export async function finishMove(move) {
+    await notifyMoveFinished(move);
+    const cloud = new ImportCloud(move.apiUrl, () => personBearer(move.directoryUrl));
+    let credential;
+    try {
+        credential = await cloud.machineCredential(move.runId);
+    }
+    catch (error) {
+        if (!(error instanceof CrtrError) || error.details?.['code'] !== 'credential_exists')
+            throw error;
+        credential = await cloud.machineCredential(move.runId, true);
+    }
+    writeMachineCredential(credential.credential);
+    writeMachineConfig({ apiUrl: move.apiUrl, environmentId: credential.environment_id, runId: move.runId, directoryUrl: move.directoryUrl, account: move.account });
+    await stopAllDaemons();
+    await spawnDaemon();
+    // Only now has the computer switched over: until the machine-role daemon is up the record keeps every command at `move_unfinished`.
+    deleteMoveRecord();
+}
+const ACTIVATION_ATTEMPTS = 3;
+const ACTIVATION_GAP_MS = 30_000;
+/** Move this computer into the signed-in person's account. Before the cloud run reaches `done`, any failure undoes the move: the drain ends, the
+ *  sign-in is revoked and deleted, the move record goes, and `notify` (a node) is told through the local daemon. After `done` the move record says
+ *  `committed` and activation is retried three times over a minute; still failing, the record, the sign-in and the drain stay for `crtr sys signin`. */
+export async function runMove(opts) {
+    const step = { name: 'sign-in', timings: [] };
+    let move;
+    let runId = '';
+    let base;
+    try {
+        const account = await personAccount(opts.directoryUrl);
+        const apiUrl = opts.apiUrl ?? await controlPlaneUrl(opts.directoryUrl);
+        const cloud = new ImportCloud(apiUrl, () => personBearer(opts.directoryUrl));
+        base = { apiUrl, directoryUrl: opts.directoryUrl, account, notify: opts.notify, notified: false, pid: process.pid };
+        await exportRun('machine', cloud, undefined, step, (id) => { runId = id; writeMoveRecord({ ...base, runId: id, state: 'running' }); }, deleteMoveRecord);
+    }
+    catch (error) {
+        // Once `load` was sent and its outcome is unknown, the record and the drain stay: the next starter (`crtr sys signin`, the local daemon's start)
+        // asks the control plane and settles the move.
+        if (error instanceof CrtrError && error.code === 'move_outcome_unknown')
+            throw error;
+        throw await undoMove(step.name, error, opts.notify);
+    }
+    // The run is `done`: from here nothing may undo the move, so a failed record write is reported as it is and the `running` record settles to `committed` later.
+    move = { ...base, runId, state: 'committed' };
+    writeMoveRecord(move);
+    let last;
+    const activating = Date.now();
+    for (let attempt = 1; attempt <= ACTIVATION_ATTEMPTS; attempt++) {
+        try {
+            await finishMove(move);
+            step.timings.push(`restart=${((Date.now() - activating) / 1000).toFixed(1)}s`);
+            process.stderr.write(`restart ${((Date.now() - activating) / 1000).toFixed(1)}s\n`);
+            return { runId: move.runId, account: move.account.display, timings: step.timings.join(' ') };
+        }
+        catch (error) {
+            last = error;
+            process.stderr.write(`switch-over attempt ${attempt} failed: ${error instanceof Error ? error.message : String(error)}\n`);
+            if (attempt < ACTIVATION_ATTEMPTS)
+                await sleep(ACTIVATION_GAP_MS);
+            move = readMoveRecord() ?? move;
+        }
+    }
+    throw moveUnfinishedError(last instanceof Error ? last.message : String(last));
+}
+/** Undo a move that never reached `done` (the drain is already confirmed ended), tell the asking node, and return the error to throw. */
+async function undoMove(step, error, notify) {
+    const reason = error instanceof Error ? error.message : String(error);
+    const still = error instanceof CrtrError && error.code === 'drain_not_ended' ? 'crtr is still local, but its pause could not be ended: run `crtr sys import resume`' : 'crtr is still local and working as before';
+    const failed = `The move to Northlight failed at ${step}: ${reason}. ${still}.`;
+    const revokeFailure = await dropMove(failed, notify);
+    const code = error instanceof CrtrError && error.code !== 'error' ? error.code : (error instanceof CrtrError && typeof error.details?.['code'] === 'string' ? error.details['code'] : 'move_failed');
+    return new CrtrError(code, `the move to Northlight failed at ${step}: ${reason}. ${still}, and ${signedOutText(revokeFailure)}`, ExitCode.GENERAL);
+}
+/** What the person is told about the sign-in a failed move removes: revoked at Northlight, or removed here only. */
+const signedOutText = (revokeFailure) => revokeFailure === undefined ? 'this computer is signed out.' : `this computer's sign-in was removed here but could not be revoked at Northlight (${revokeFailure}); revoke it on your Northlight account page.`;
+/** The shared end of a failed move: delete the record, sign this computer out, and tell the node that asked (a failed revoke is added to its
+ *  message). Returns why the sign-in could not be revoked at Northlight, or undefined when it was revoked or already ended: the secret is deleted here either way,
+ *  so a failed revoke leaves one that is still valid there. */
+async function dropMove(message, notify) {
+    deleteMoveRecord();
+    let revokeFailure;
+    try {
+        await signOut();
+    }
+    catch (error) {
+        forgetSignIn();
+        revokeFailure = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`could not revoke the sign-in at Northlight: ${revokeFailure}\n`);
+    }
+    if (notify === null)
+        return revokeFailure;
+    try {
+        await cliClient({ local: true }).sendMessage(notify, { from: null, body: `${message} Tell the person the move failed.${revokeFailure === undefined ? '' : ` ${signedOutText(revokeFailure)}`}` });
+    }
+    catch (sendError) {
+        process.stderr.write(`could not message ${notify}: ${sendError instanceof Error ? sendError.message : String(sendError)}\n`);
+    }
+    return revokeFailure;
+}
+/** Where an earlier move stands before a new sign-in or move starts, and when the local daemon starts. A `running` record whose exporter is alive
+ *  refuses; one whose exporter died is settled against the control plane, and only its positive answer moves it: a run that reached `done` becomes
+ *  `committed` (returned, so the caller finishes the switch-over); a run still loading there refuses until it settles; a run that failed or never
+ *  loaded is a failed move, undone here (record deleted and drain ended and confirmed, sign-in revoked, the asking node told). Any other outcome —
+ *  the control plane unreachable or refusing, no working sign-in — leaves the record and the drain as they are and throws. With no working sign-in
+ *  `show` signs back in first, and only to the account that owns the move (another account is refused, nothing written); without `show` (the daemon) it throws `not_signed_in`.
+ *  Answers the committed record, or undefined when no move is left (an `activated` record only awaits its notification, which the machine daemon sends). */
+export async function settleEarlierMove(show) {
+    const move = readMoveRecord();
+    if (move === undefined || move.state === 'activated')
+        return undefined;
+    const signBackIn = async () => {
+        await signIn(move.directoryUrl, show, { accept: async (approved) => approved.account.id === move.account.id ? undefined
+                : new CrtrError('signin_other_account', `This computer's move belongs to the Northlight account ${move.account.display}. Sign in to that account.`, ExitCode.USAGE) });
+    };
+    if (move.state === 'committed') {
+        if (show !== undefined) {
+            try {
+                await personAccount(move.directoryUrl);
+            }
+            catch (error) {
+                if (!(error instanceof CrtrError && error.code === 'not_signed_in'))
+                    throw error;
+                await signBackIn();
+            }
+        }
+        return move;
+    }
+    if (move.pid > 0 && isPidAlive(move.pid)) {
+        throw new CrtrError('move_running', `a move to Northlight is already running (process ${move.pid}).`, ExitCode.USAGE, { next: 'Wait for it to finish; the node that asked is messaged when it does.' });
+    }
+    const ask = () => new ImportCloud(move.apiUrl, () => personBearer(move.directoryUrl)).get(move.runId);
+    let run;
+    try {
+        run = await ask();
+    }
+    catch (error) {
+        if (!(error instanceof CrtrError && error.code === 'not_signed_in') || show === undefined)
+            throw error;
+        await signBackIn();
+        run = await ask();
+    }
+    if (run.state === 'done') {
+        const committed = { ...move, state: 'committed' };
+        writeMoveRecord(committed);
+        return committed;
+    }
+    if (run.state === 'loading' || run.state === 'committed') {
+        throw new CrtrError('move_running', 'Northlight is still loading this computer\'s records from an earlier move.', ExitCode.USAGE, { next: 'Retry in a minute.' });
+    }
+    if (run.state !== 'failed' && run.state !== 'rolled_back' && run.state !== 'uploading') {
+        throw new CrtrError('move_outcome_unknown', 'Northlight did not report a settled outcome for this move.', ExitCode.GENERAL, { next: 'Run `crtr sys signin` to settle the move.' });
+    }
+    const step = run.failure?.step ?? 'an earlier step';
+    const reason = run.failure == null ? 'the process that was moving this computer stopped before Northlight had the records' : run.failure.message;
+    deleteMoveRecord();
+    try {
+        await endDrainConfirmed(cliClient({ local: true }));
+    }
+    catch (error) {
+        throw await undoMove(step, new CrtrError('drain_not_ended', `${reason} (and ${error instanceof Error ? error.message : String(error)})`, ExitCode.GENERAL), move.notify);
+    }
+    await dropMove(`The move to Northlight failed at ${step}: ${reason}. crtr is still local and working as before.`, move.notify);
+    return undefined;
+}
+const DAEMON_SETTLE_GAP_MS = 60_000;
+/** The daemon answers its own socket only once startup is done, which is a moment after the settle is scheduled. */
+const DAEMON_SETTLE_FIRST_MS = 5_000;
+/** The local daemon's start is a starter of the move record (design-crtr-northlight-signin component 4): a `running` record whose exporter died (a crash,
+ *  a reboot) leaves the daemon drained and the asking node untold until someone runs `crtr sys signin`, so the daemon settles it itself once it serves.
+ *  Retries every minute while the settle cannot finish (the control plane unreachable, the run still loading); a run that reached `done` stays `committed`
+ *  for `crtr sys signin`. Returns when there is nothing to settle, the exporter is alive, or `stopped()` says the daemon is closing. */
+export async function settleMoveAtDaemonStart(stopped, onRetry) {
+    await sleep(DAEMON_SETTLE_FIRST_MS);
+    while (!stopped()) {
+        const move = readMoveRecord();
+        if (move === undefined || move.state !== 'running' || (move.pid > 0 && isPidAlive(move.pid)))
+            return;
+        try {
+            await settleEarlierMove();
+            return;
+        }
+        catch (error) {
+            onRetry(error);
+            // No working sign-in: only the person signing back in (`crtr sys signin`) can settle it, so asking again every minute cannot help.
+            if (error instanceof CrtrError && error.code === 'not_signed_in')
+                return;
+        }
+        await sleep(DAEMON_SETTLE_GAP_MS);
+    }
+}

package/dist/commands/sys/import/resume.d.ts

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

package/dist/commands/sys/import/resume.js

@@ -0,0 +1,23 @@
+// `crtr sys import resume`: ends the drain an import left on this daemon (src/daemon/drain.ts).
+import { defineLeaf } from '../../../core/command.js';
+import { cliClient } from '../../api-client.js';
+export const resume = defineLeaf({
+    name: 'resume',
+    description: 'end the pause an import left on this daemon',
+    whenToUse: 'an import failed or its exporter was killed, so this runtime stayed paused and should carry on',
+    help: {
+        name: 'sys import resume',
+        summary: 'end the drain so the daemon takes wakes, cron fires and deliveries again',
+        guide: 'Safe to repeat: when the daemon is not drained it says so and exits 0. Refused (409 `conflict`) while a move record exists: the account may hold this computer\'s records, so agents here must not carry on against the local database until `crtr sys signin` settles the move.',
+        params: [],
+        output: [
+            { name: 'was_drained', type: 'boolean', required: true, constraint: 'Whether the daemon was drained before this call.' },
+        ],
+        outputKind: 'object',
+        effects: ['Deletes the `drain` row of `runtime_state`; nothing else changes. Refused while `runtime/import/move.json` exists.'],
+    },
+    run: async () => {
+        return { was_drained: (await cliClient({ local: true }).endDaemonDrain()).was_drained === true };
+    },
+    render: (r) => (r['was_drained'] === true ? '<import drain="ended"/>' : '<import drain="none">the daemon was not drained</import>'),
+});

package/dist/commands/sys/import/start.d.ts

@@ -0,0 +1,4 @@
+/** Set by `crtr sys signin` on the detached exporter it starts from inside a node: the signin process, which the exporter outlives before it drains,
+ *  so it is never in a broker's process tree. */
+export declare const WAIT_FOR_PID_ENV = "CRTR_IMPORT_WAIT_PID";
+export declare const sysImportBranch: import("../../../core/command.js").BranchDef;

package/dist/commands/sys/import/start.js

@@ -0,0 +1,92 @@
+// `crtr sys import start`: the source side of an import (design-import, "Exporter"). Uploads blobs, drains the daemon, dumps the rows and file
+// stores, uploads them, asks the control plane to load, and on a computer switches this install to the machine role (`./move.ts`).
+import { defineBranch, defineLeaf } from '../../../core/command.js';
+import { general, usage } from '../../../core/errors.js';
+import { ImportCloud } from '../../../core/import/export/cloud.js';
+import { ensureSignedIn } from '../../../core/directory/person-credential.js';
+import { isPidAlive } from '../../../core/canvas/pid.js';
+import { showSignIn } from '../signin.js';
+import { insideBroker } from '../join.js';
+import { defaultDirectoryUrl, exportRun, settleEarlierMove, finishMove, runMove } from './move.js';
+import { resume } from './resume.js';
+/** Set by `crtr sys signin` on the detached exporter it starts from inside a node: the signin process, which the exporter outlives before it drains,
+ *  so it is never in a broker's process tree. */
+export const WAIT_FOR_PID_ENV = 'CRTR_IMPORT_WAIT_PID';
+async function waitForExit(pid) {
+    while (isPidAlive(pid))
+        await new Promise((resolve) => setTimeout(resolve, 200));
+}
+const start = defineLeaf({
+    name: 'start',
+    description: 'export this runtime into the person\'s Northlight account',
+    whenToUse: 'moving this computer or hosted runtime\'s canvas into Northlight: run it from a plain terminal, not from inside a node',
+    help: {
+        name: 'sys import start',
+        summary: 'upload blobs, pause the daemon, dump rows and file stores, and have the control plane load them',
+        guide: 'Order: open the run, upload blobs and request files, drain the daemon (turns in flight settle for up to 10 minutes), upload them again, dump every table and the file stores, upload the rows, request the load and wait for `done` or `failed`, printing each step\'s time. Before `done`, a failure ends the drain and this runtime carries on as before; a computer\'s move also signs it out. On `done` the daemon stays drained: a hosted runtime until hosting quiesces it (`crtr sys import resume` ends it), a computer until it has switched over — machine credential, `runtime/machine.json`, daemon restarted in machine role — which is retried three times over a minute and otherwise finished by `crtr sys signin`. A machine import signs the person in first when this computer has no stored sign-in. `crtr sys signin` normally starts a computer\'s move itself. With `--run`, hosting has already opened the run: the exporter uses it and reads that run\'s import token from the environment variable `CRTR_IMPORT_TOKEN`.',
+        params: [
+            { kind: 'flag', name: 'kind', type: 'enum', choices: ['machine', 'hosted'], required: true, constraint: '`machine` for a person\'s computer, `hosted` for a hosted runtime (also archives running nodes\' files).' },
+            { kind: 'flag', name: 'api-url', type: 'string', required: false, constraint: 'Control plane base URL (http or https). Required with `--kind hosted`; with `--kind machine` the default is the control plane the person\'s sign-in is for.' },
+            { kind: 'flag', name: 'run', type: 'string', required: false, constraint: 'An import run hosting opened for this runtime (only with `--kind hosted`); its import token is read from `CRTR_IMPORT_TOKEN`.' },
+            { kind: 'flag', name: 'directory-url', type: 'string', required: false, constraint: 'Directory base URL (http or https) the person signs in against, with `--kind machine`. Default: the one in `runtime/machine.json`, else the stored sign-in\'s, else Northlight\'s.' },
+            { kind: 'flag', name: 'notify', type: 'string', required: false, constraint: 'With `--kind machine`: a node id told by message when the move fails or finishes.' },
+        ],
+        output: [
+            { name: 'run_id', type: 'string', required: true, constraint: 'The import run.' },
+            { name: 'state', type: 'string', required: true, constraint: 'Final state of the run, `done`.' },
+            { name: 'timings', type: 'string', required: true, constraint: 'Per-step seconds.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Drains the local daemon (no new wake or cron fire); the drain is a `runtime_state` row, so it survives a daemon restart. Ended on a failure before `done`; kept after `done`.',
+            'Machine: writes `runtime/import/move.json` (0600) from the run\'s start until the switch-over, then deletes it. On `done`: writes `runtime/machine.json` and `runtime/secrets/machine-credential` (0600) and restarts the daemon in machine role. On a failure before `done`: revokes and deletes the stored sign-in.',
+            'Machine with `--notify`: sends that node one message when the move fails or finishes.',
+            'Opens a temporary directory holding the opened file stores (0600), removed before the command ends.',
+        ],
+    },
+    run: async (input) => {
+        const kind = input['kind'];
+        const existingRun = input['run'] === undefined ? undefined : String(input['run']);
+        const apiUrl = input.apiUrl === undefined ? undefined : String(input.apiUrl);
+        const notify = input['notify'] === undefined ? null : String(input['notify']);
+        if (kind === 'hosted') {
+            if (apiUrl === undefined)
+                throw usage('--kind hosted needs --api-url: the control plane hosting opened the run on');
+            if (notify !== null)
+                throw usage('--notify names the node that asked for a computer\'s move: use it only with --kind machine');
+        }
+        else if (existingRun !== undefined) {
+            throw usage('--run takes an existing run, which only a hosted import has: use --kind hosted');
+        }
+        const waitFor = Number(process.env[WAIT_FOR_PID_ENV] ?? '');
+        if (Number.isInteger(waitFor) && waitFor > 0)
+            await waitForExit(waitFor);
+        if (insideBroker())
+            throw general('import_inside_node: run this from a plain terminal; a node\'s broker ends with the daemon restart', { code: 'import_inside_node' });
+        if (kind === 'machine') {
+            const earlier = await settleEarlierMove(showSignIn);
+            if (earlier !== undefined) {
+                await finishMove(earlier);
+                return { run_id: earlier.runId, state: 'done', timings: '' };
+            }
+            const directoryUrl = input.directoryUrl === undefined ? defaultDirectoryUrl() : String(input.directoryUrl);
+            await ensureSignedIn(directoryUrl, showSignIn);
+            const moved = await runMove({ directoryUrl, ...(apiUrl === undefined ? {} : { apiUrl }), notify });
+            return { run_id: moved.runId, state: 'done', timings: moved.timings };
+        }
+        const token = (existingRun === undefined ? await ensureSignedIn(defaultDirectoryUrl(), showSignIn) : process.env['CRTR_IMPORT_TOKEN'] ?? '').trim();
+        if (token === '')
+            throw usage('set CRTR_IMPORT_TOKEN to the run\'s import token');
+        const step = { name: 'start', timings: [] };
+        const runId = await exportRun('hosted', new ImportCloud(apiUrl, token), existingRun, step);
+        return { run_id: runId, state: 'done', timings: step.timings.join(' ') };
+    },
+    render: (r) => `<import run="${r['run_id']}" state="${r['state']}" timings="${r['timings']}"/>`,
+});
+export const sysImportBranch = defineBranch({
+    name: 'import',
+    description: 'move this runtime into the person\'s Northlight account',
+    whenToUse: 'importing this computer or hosted runtime into Northlight',
+    help: { name: 'sys import', summary: 'export this runtime to Northlight', model: 'The exporter pauses the local daemon, uploads a bundle the control plane loads into the shared database, and on a computer switches it to the machine role.' },
+    children: [start, resume],
+});

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

@@ -0,0 +1,3 @@
+/** Whether a broker (a node's engine) is an ancestor of this process, or cannot be ruled out. Stopping the daemon kills every broker, so a join run from one would die mid-way. */
+export declare function insideBroker(): boolean;
+export declare const sysJoinLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/sys/join.js

@@ -0,0 +1,85 @@
+// `crtr sys join` registers this runtime with its directory before the daemon starts.
+import { defineLeaf } from '../../core/command.js';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { pluginsDir } from '../../core/scope.js';
+import { joinDirectory } from '../../core/directory/join.js';
+import { apiSocketPath } from '../../core/canvas/paths.js';
+import { listProcessTable } from '../../core/canvas/pid.js';
+import { daemonAnswers } from '../../core/layout-migrate/index.js';
+import { envNodeId } from '../../shared/env.js';
+import { isDaemonRunning } from '../../daemon/pidfile.js';
+import { findDaemonPids, spawnDaemon, stopAllDaemons } from '../../daemon/manage.js';
+/** Whether a broker (a node's engine) is an ancestor of this process, or cannot be ruled out. Stopping the daemon kills every broker, so a join run from one would die mid-way. */
+export function insideBroker() {
+    const table = listProcessTable();
+    // Fail closed: if ancestry cannot be established, assume a node, because a wrong "no" kills the caller mid-join.
+    if (table === null)
+        return true;
+    if ((envNodeId() ?? '') !== '')
+        return true;
+    const byPid = new Map(table.map((row) => [row.pid, row]));
+    const seen = new Set();
+    for (let pid = process.ppid; pid > 1 && !seen.has(pid); pid = byPid.get(pid)?.ppid ?? 0) {
+        seen.add(pid);
+        if (byPid.get(pid)?.command.includes('broker-cli'))
+            return true;
+    }
+    return false;
+}
+/** Daemon control for a person's computer. A container whose daemon is the launcher's PID 1 keeps the offline contract. */
+function daemonControl() {
+    if (process.platform === 'linux' && existsSync('/run/crtr/launcher.sock'))
+        return undefined;
+    return {
+        // The process table too: a successor spawned just before the join took its lock has no pidfile or socket yet, but boots on the settings the join is about to replace.
+        running: async () => isDaemonRunning() || findDaemonPids().length > 0 || await daemonAnswers(apiSocketPath()),
+        stop: async () => { await stopAllDaemons(); },
+        start: async () => { await spawnDaemon(); },
+        // A bare `crtr cloud …` is an unknown command until a daemon's grant sync has installed the `cloud` plugin.
+        firstSync: async () => {
+            const dir = pluginsDir('user');
+            const deadline = Date.now() + 20_000;
+            while (dir && Date.now() < deadline && !existsSync(join(dir, 'cloud', 'commands.json')))
+                await new Promise((resolve) => setTimeout(resolve, 250));
+        },
+        insideNode: insideBroker,
+    };
+}
+export const sysJoinLeaf = defineLeaf({
+    name: 'join',
+    description: 'register this runtime with its directory using an enrollment token, offline',
+    whenToUse: 'on your own computer, with a token from `<issuer>/account/machines`: run it from a plain terminal, with any viewers open. It stops the daemon, joins, and starts it again. Also at a hosted runtime\'s first boot, before the daemon starts, with the enrollment token provisioning passed in.',
+    help: {
+        name: 'sys join',
+        summary: 'exchange a directory enrollment token for a new runtime client key and record the returned identity',
+        guide: 'Generates a new ES256 client key, sends only its public key to `PUT <directory>/v1/runtimes/registration` with the token as bearer, and learns the runtime id, client id, issuer, owner and URL from the answer. Only after that answer does it write the key file. It writes no settings and touches no canvas.db: the daemon\'s next start replaces this install\'s person with the owner everywhere in canvas.db, sets the user settings `runtime.issuer` and `runtime.audience` from the key file, and rewrites the legacy local person\'s profile grantees to `app:terminal`, all before it serves anything. On your own computer a running daemon is no obstacle: join takes a `join.lock` in the runtime directory (so no open viewer\'s redial can autostart a daemon while it works), registers with the directory while the daemon still serves, stops the daemon, writes the identity, and starts the daemon again, whose start applies the change. Run it from a plain terminal, not from inside a node: a node\'s broker dies with the daemon, so join refuses `join_inside_node` instead. Where the launcher owns the daemon (a hosted container) join keeps the offline contract and refuses `daemon_running`. Presenting the token of the stored successful registration again finishes those local writes without calling the directory. Any other token generates a new key and registers again.',
+        params: [
+            { kind: 'flag', name: 'directory', type: 'string', required: true, constraint: 'Directory base URL (http or https) that minted the token.' },
+            { kind: 'flag', name: 'token', type: 'string', required: true, sensitive: true, constraint: 'Single-use enrollment token. Sensitive: never echoed in output or errors.' },
+            { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Label shown for this machine on the account page. Default: this computer\'s hostname.' },
+        ],
+        output: [
+            { name: 'runtime', type: 'string', required: true, constraint: 'Runtime principal from the directory, `runtime:<id>`.' },
+            { name: 'client_id', type: 'string', required: true, constraint: 'OAuth client id registered for the new key.' },
+            { name: 'issuer', type: 'string', required: true, constraint: 'Canonical issuer, written to `runtime.issuer`.' },
+            { name: 'owner', type: 'string', required: true, constraint: 'Owner principal, `user:<id>`, that replaces this install\'s own person at the next daemon start.' },
+            { name: 'canvas_rewrite', type: 'string', required: true, constraint: 'Always `next daemon start`: when canvas.db identity fields are rewritten.' },
+            { name: 'url', type: 'string', required: true, constraint: 'Runtime URL, written to `runtime.audience`.' },
+            { name: 'registered', type: 'boolean', required: true, constraint: 'False when the token matched the stored registration and the directory was not called.' },
+            { name: 'daemon', type: 'string', required: true, constraint: '`restarted` (a daemon was stopped and started on the joined settings), `started` (none was running; join started one and waited, up to 20s, for its first grant sync to install the account\'s provider plugins, so `crtr cloud …` resolves), `not_running` (none was started: a hosted container\'s launcher owns its daemon), or `restart_failed` (joined, but the new daemon did not start: see `daemon_error`, then run `crtr sys daemon start`).' },
+            { name: 'daemon_error', type: 'string', required: false, constraint: 'Why the new daemon did not start, with `daemon: restart_failed`.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Holds `<runtime>/join.lock` (its pid) from the start until the daemon is back; `ensureDaemon` and `sys daemon start` (without `--force`) decline to start a daemon while a live process holds it (including a start already in flight when the join began). A lock whose holder died is reclaimed.',
+            'A running daemon is stopped (SIGTERM, then SIGKILL, plus strays) after the directory accepts the registration and before the local writes, then started again. Every broker dies with it and is revived by the new daemon. If the join fails after the stop, the daemon is started again anyway. With no daemon running join starts one anyway, because a bare `crtr cloud …` is an unknown command (it never autostarts a daemon) until a daemon\'s grant sync has installed the provider plugins. Refuses `join_inside_node` when run from inside a node and a daemon is running; refuses `daemon_running` where a container launcher owns the daemon.',
+            'On a new token: calls the directory once; on success writes `<runtime>/secrets/runtime-client.json` (mode 0600) with the private key, registration and the token\'s SHA-256, replacing any earlier key file. A refused or failed call writes nothing.',
+            'Sends name, platform, crtr version, installed plugin ids and sandbox state with the public key. Before the request it writes `runtime-client.pending.json` (mode 0600); a rerun with the same token and directory reuses that key, so a lost reply is retried safely. The file is deleted on success or a refusal.',
+            'Sets `runtime.issuer` and `runtime.audience` in user settings. When the directory says this machine is not the account\'s default (`is_default: false`) it replaces the whole `runtime` setting with `{issuer, audience, unsandboxed: true}`: no app listener, and only `app:terminal` nodes run.',
+            'Rewrites the legacy local person\'s profile grantees to `app:terminal`.',
+            'At the next daemon start, before any listener, the person this install minted (or still the legacy local person) is replaced by the owner in every canvas.db column that holds a person: node, token, grant, cron, audit and usage subjects and grantees, the person\'s identity, and queued cron births. References to the install\'s local terminal grant are cleared and that local grant mirror is deleted so grant sync installs the directory\'s. Free text is unchanged. The start after that changes nothing.',
+        ],
+    },
+    run: async (input) => ({ ...(await joinDirectory(input['directory'], input['token'], input['name'] || undefined, daemonControl())), canvas_rewrite: 'next daemon start' }),
+});

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

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