@north-light/api 0.3.580 → 0.3.587

package/dist/commands/sys/daemon.js

@@ -0,0 +1,334 @@
+// `crtr sys daemon` — thin supervisor daemon management.
+//
+// The daemon (crtrd) polls active+idle nodes and handles engine-container exit
+// (a tmux pane or a headless broker process):
+//   • crash (container gone, no intent) → mark 'dead'
+//   • refresh-yield (intent=refresh) → fresh respawn
+//
+// This subtree starts, checks, and stops the daemon process.
+import { defineLeaf, defineBranch } from '../../core/command.js';
+import { InputError } from '../../core/io.js';
+import { parseDurationMs } from '../../core/wake.js';
+import { DaemonNotPreparedError, probeDaemonHealth, probeErrorMessage, spawnDaemon, stopDaemonProcess, sweepStrayDaemons } from '../../daemon/manage.js';
+import { isDaemonRunning, readPidfile, isPidAlive } from '../../daemon/pidfile.js';
+import { cliClient } from '../api-client.js';
+import { localClient } from '../../api/node-transport.js';
+import { defineSysBranch } from './branch.js';
+import { selectedGeneration } from './shared.js';
+// daemon start
+const daemonStart = defineLeaf({
+    name: 'start',
+    description: 'start the daemon in the background',
+    whenToUse: 'bringing the crtrd supervisor up for the first time in a session so node window-exits get handled (no-op only when its Unix API socket already serves)',
+    help: {
+        name: 'sys daemon start',
+        summary: 'start the crtrd supervisor daemon in the background (no-op only if its Unix API socket serves)',
+        params: [
+            { kind: 'flag', name: 'prepare', type: 'bool', required: false, constraint: 'Hold normal daemon work after storage preparation until `sys daemon admit`; omit for ordinary startup.' },
+            { kind: 'flag', name: 'force', type: 'bool', required: false, default: false, constraint: 'Start even while `crtr sys join` holds the daemon down. Joining then fails `daemon_running`; use only to clear a join that is stuck.' },
+        ],
+        output: [
+            { name: 'started', type: 'boolean', required: true, constraint: 'True when a new daemon process was spawned; false when one was already running.' },
+            { name: 'pid', type: 'number', required: false, constraint: 'PID of the newly spawned daemon.' },
+            { name: 'existing_pid', type: 'number', required: false, constraint: 'PID of the already-running daemon (when started=false).' },
+            { name: 'running', type: 'boolean', required: false, constraint: 'True only when a live pidfile owner does not serve its Unix API socket.' },
+            { name: 'serving', type: 'boolean', required: false, constraint: 'False only when a live pidfile owner does not answer /healthz.' },
+            { name: 'probe_error', type: 'string', required: false, constraint: 'The final /healthz probe failure when a live owner missed readiness.' },
+            { name: 'startup_phase', type: 'string', required: false, constraint: 'The observed daemon phase when it was reachable.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Refuses `join_in_progress` while a live `crtr sys join` holds the daemon down, unless `--force`. `sys daemon restart` and `ensureDaemon` stand down the same way.',
+            'Spawns dist/daemon/crtrd-cli.js detached + unref\'d; it outlives this process.',
+            'Writes a pidfile at CRTR_PIDFILE if set, otherwise crtrHome()/crtrd.pid.'
+        ],
+    },
+    run: async (input) => {
+        try {
+            const result = await spawnDaemon({ targetPhase: input.prepare === true ? 'prepared' : 'ready', ignoreJoinLock: input.force === true });
+            return result;
+        }
+        catch (error) {
+            if (error instanceof DaemonNotPreparedError) {
+                throw new InputError({
+                    error: 'daemon_not_prepared',
+                    message: error.message,
+                    next: 'Stop the live daemon, then start a new one with `crtr sys daemon start --prepare` before setup.',
+                });
+            }
+            throw error;
+        }
+    },
+});
+// daemon await / admit
+const DAEMON_AWAIT_POLL_MS = 100;
+async function awaitDaemonPhase(phase, timeoutMs) {
+    const startedAt = Date.now();
+    const deadline = startedAt + timeoutMs;
+    let lastPhase = 'initializing';
+    let lastObservation = 'the daemon socket was not reachable';
+    while (Date.now() < deadline) {
+        try {
+            const health = await probeDaemonHealth(Math.min(1_000, Math.max(1, deadline - Date.now())));
+            lastPhase = health.startup_phase;
+            lastObservation = health.startup_blocked ?? `daemon is ${health.startup_phase}`;
+            if (health.startup_phase === 'blocked') {
+                throw new InputError({
+                    error: 'startup_blocked',
+                    message: health.startup_blocked ?? 'daemon startup is blocked',
+                    received: health.startup_phase,
+                    field: 'phase',
+                    next: 'Repair the reported blocker paths with `crtr sys migrate`, then retry the await.',
+                });
+            }
+            if (health.startup_phase === phase)
+                return { startup_phase: phase, waited_ms: Date.now() - startedAt };
+            if (phase === 'prepared' && health.startup_phase === 'ready') {
+                throw new InputError({
+                    error: 'await_missed_phase',
+                    message: 'daemon is already ready and cannot return to prepared in this process',
+                    received: health.startup_phase,
+                    field: 'phase',
+                    next: 'Start a new daemon with `crtr sys daemon start --prepare` before awaiting prepared.',
+                });
+            }
+        }
+        catch (error) {
+            if (error instanceof InputError)
+                throw error;
+            lastObservation = error instanceof Error ? error.message : String(error);
+        }
+        await new Promise((resolve) => setTimeout(resolve, Math.min(DAEMON_AWAIT_POLL_MS, Math.max(0, deadline - Date.now()))));
+    }
+    throw new InputError({
+        error: 'await_timeout',
+        message: `daemon did not reach ${phase} within ${timeoutMs}ms (last phase: ${lastPhase}; last observation: ${lastObservation})`,
+        received: lastPhase,
+        field: 'phase',
+        next: 'Inspect `crtr sys daemon status` and resolve any reported startup blocker before retrying.',
+    });
+}
+const daemonAwait = defineLeaf({
+    name: 'await',
+    description: 'wait for a daemon startup phase',
+    whenToUse: 'a caller started or was given a daemon that must reach prepared or ready before its next step.',
+    help: {
+        name: 'sys daemon await',
+        summary: 'wait for the running daemon to report one startup phase',
+        params: [
+            { kind: 'flag', name: 'phase', type: 'enum', choices: ['prepared', 'ready'], required: true, constraint: 'The phase that permits the caller’s next step.' },
+            { kind: 'flag', name: 'timeout', type: 'string', required: false, default: '5m', constraint: 'Maximum wait as a positive duration such as 90s, 5m, or 1h30m.' },
+        ],
+        output: [
+            { name: 'startup_phase', type: 'string', required: true, constraint: 'The requested phase.' },
+            { name: 'waited_ms', type: 'number', required: true, constraint: 'Elapsed wall-clock time before the phase was observed.' },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only: polls /healthz until the requested phase is observed or the caller-bounded timeout expires.'],
+    },
+    run: async (input) => {
+        const rawTimeout = input.timeout;
+        const timeoutMs = parseDurationMs(rawTimeout);
+        if (timeoutMs === null || timeoutMs <= 0) {
+            throw new InputError({ error: 'invalid_duration', message: `not a positive duration: ${rawTimeout}`, received: rawTimeout, field: 'timeout', next: 'Use a positive duration such as 90s, 5m, or 1h30m.' });
+        }
+        return awaitDaemonPhase(input.phase, timeoutMs);
+    },
+});
+const daemonAdmit = defineLeaf({
+    name: 'admit',
+    description: 'admit normal work after daemon preparation',
+    whenToUse: 'the caller has completed its setup against a prepared daemon and is ready for normal daemon work to start.',
+    help: {
+        name: 'sys daemon admit',
+        summary: 'ask a prepared daemon to start normal services',
+        params: [],
+        output: [
+            { name: 'admitted', type: 'boolean', required: true, constraint: 'True only when this request began admission.' },
+            { name: 'already_admitted', type: 'boolean', required: true, constraint: 'True when admission had already begun or completed.' },
+            { name: 'startup_phase', type: 'string', required: true, constraint: 'The phase after admission settles.' },
+        ],
+        outputKind: 'object',
+        effects: ['Starts normal daemon services when the daemon is prepared.'],
+    },
+    run: async (_input) => {
+        return await localClient({ autostart: false }).admitDaemon();
+    },
+});
+// daemon status
+/** The generation id the live daemon reports on `/v1/status`; undefined when it reports none or cannot be asked. */
+async function servingGenerationId() {
+    try {
+        const status = await localClient({ autostart: false }).status();
+        return status.generation_id ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+const daemonStatus = defineLeaf({
+    name: 'status',
+    description: 'check whether the daemon is running',
+    whenToUse: 'operator/dev diagnostic — probing whether the crtrd supervisor process is alive while troubleshooting revive/supervision behavior',
+    help: {
+        name: 'sys daemon status',
+        summary: 'check whether the crtrd supervisor daemon is currently running',
+        params: [],
+        output: [
+            { name: 'running', type: 'boolean', required: true, constraint: 'True when the daemon pidfile owner is alive.' },
+            { name: 'serving', type: 'boolean', required: false, constraint: 'True when the live daemon answers /healthz; false when one probe does not.' },
+            { name: 'pid', type: 'number', required: false, constraint: 'PID of the running daemon.' },
+            { name: 'probe_error', type: 'string', required: false, constraint: 'The failed /healthz observation when the live owner did not answer.' },
+            { name: 'startup_phase', type: 'string', required: false, constraint: 'The observed daemon startup phase when the socket answered.' },
+            { name: 'serving_generation', type: 'string', required: false, constraint: 'Id of the runtime generation the daemon process was launched from. Absent when the daemon reports none (it predates the field, or runs from a development checkout) or its status could not be read.' },
+            { name: 'selected_generation', type: 'string', required: false, constraint: 'Id of the selected runtime generation. Absent when none is selected or it cannot be read.' },
+            { name: 'generation_drift', type: 'string', required: false, constraint: '`none` when the serving and selected generation ids are equal; `differs` when they are not, meaning the daemon runs older bytes than the install selected until `sys daemon restart`; `unknown` when either id is absent. Never `none` on missing evidence.' },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only: reads the pidfile, probes the pid, and requests /healthz and /v1/status without autostart.'],
+    },
+    run: async (_input) => {
+        const pid = readPidfile();
+        const running = pid !== null && isPidAlive(pid);
+        if (!running)
+            return { running: false };
+        try {
+            const health = await probeDaemonHealth();
+            const serving = await servingGenerationId();
+            const selected = selectedGeneration().generation?.id;
+            return {
+                running: true,
+                serving: health.ok,
+                pid,
+                ...(health.startup_phase === undefined ? {} : { startup_phase: health.startup_phase }),
+                ...(serving === undefined ? {} : { serving_generation: serving }),
+                ...(selected === undefined ? {} : { selected_generation: selected }),
+                generation_drift: serving === undefined || selected === undefined ? 'unknown' : serving === selected ? 'none' : 'differs',
+            };
+        }
+        catch (error) {
+            return { running: true, serving: false, pid, probe_error: probeErrorMessage(error) };
+        }
+    },
+});
+// daemon restart
+const daemonRestart = defineLeaf({
+    name: 'restart',
+    description: 'put the selected runtime generation in service via a daemon-owned handover',
+    whenToUse: 'adopting a newly installed runtime generation — the routine restart. Use this instead of stop+start: the daemon answers before it hands over, so a caller running inside a node (whose broker the handover tears down) still gets a settled result and is resumed automatically.',
+    help: {
+        name: 'sys daemon restart',
+        summary: 'ask the running daemon to replace itself with a successor on the selected runtime generation',
+        params: [],
+        output: [
+            { name: 'restarted', type: 'boolean', required: true, constraint: 'True when a running daemon accepted the handover. False when none was running — one was started instead.' },
+            { name: 'started', type: 'boolean', required: false, constraint: 'True when no daemon was running and this call started one (restarted=false).' },
+            { name: 'pid', type: 'number', required: false, constraint: 'The daemon that accepted the handover, or the one just started.' },
+            { name: 'grace_ms', type: 'number', required: false, constraint: 'How long the daemon waits after answering before teardown begins.' },
+            { name: 'note', type: 'string', required: false, constraint: 'What happens next to the calling node. Read it before acting on an interrupted turn.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'The daemon acknowledges immediately, then after a short grace tears its whole broker fleet down, releases its claim, spawns a successor on the runtime generation currently selected, and exits.',
+            'Each torn-down broker hands its foreground bash commands to the file-backed background job system; they keep running and report completion by urgent inbox message.',
+            'Every node it tore down — including the caller — is resolved by the successor through the ordinary row-driven supervision tick.',
+            'The calling process is killed as part of that teardown, AFTER this result is returned.',
+        ],
+    },
+    run: async (_input) => {
+        if (!isDaemonRunning()) {
+            const spawned = await spawnDaemon();
+            return {
+                restarted: false,
+                started: spawned.started,
+                ...(spawned.pid !== undefined ? { pid: spawned.pid } : {}),
+                ...(spawned.existing_pid !== undefined ? { pid: spawned.existing_pid } : {}),
+                note: 'No daemon was running, so there was nothing to hand over; one was started on the selected runtime generation.',
+            };
+        }
+        try {
+            const ack = await cliClient({ local: true }).restartDaemon();
+            return {
+                restarted: ack.accepted,
+                pid: ack.predecessor_pid,
+                grace_ms: ack.grace_ms,
+                note: 'Handover accepted. If you are running inside a node, your broker is about to be torn down and resumed on the new generation — THIS RESTART ALREADY SUCCEEDED. When your turn resumes with this result in the transcript, do not re-run it.',
+            };
+        }
+        catch (err) {
+            throw new InputError({
+                error: 'daemon_restart_failed',
+                message: `the daemon did not accept a handover: ${err.message}`,
+                next: 'Run `crtr sys daemon status` to inspect the daemon.',
+            });
+        }
+    },
+});
+// daemon stop
+const daemonStop = defineLeaf({
+    name: 'stop',
+    description: 'stop the running daemon',
+    whenToUse: 'shutting the crtrd supervisor down for good, ending auto-revival of nodes on window exit. Not the way to pick up a new runtime generation — `restart` is, because stopping kills every broker of this epoch, including the caller\'s own, so this command cannot report its result to an agent that runs it.',
+    help: {
+        name: 'sys daemon stop',
+        summary: 'stop the crtrd supervisor daemon and confirm it exited',
+        params: [],
+        output: [
+            { name: 'stopped', type: 'boolean', required: true, constraint: 'True when a daemon (recorded or stray) was found and killed. False when none was running.' },
+            { name: 'pid', type: 'number', required: false, constraint: 'The recorded pidfile pid that exited (when one was recorded and alive).' },
+            { name: 'strays_killed', type: 'array', required: false, constraint: 'PIDs of stray crtrd daemons (alive but not in the pidfile) swept alongside the recorded one — the backstop against a daemon that survived a prior stop.' },
+            { name: 'force_killed', type: 'boolean', required: false, constraint: 'True when the recorded daemon ignored SIGTERM and had to be SIGKILLed.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Sends SIGTERM to the recorded pid and waits for it to exit and release its pidfile, escalating to SIGKILL if it does not.',
+            'Then sweeps any OTHER live crtrd daemon process (SIGTERM, escalating to SIGKILL after 2s) so a stray daemon orphaned from the pidfile cannot keep supervising.',
+        ],
+    },
+    run: async (_input) => {
+        const pid = readPidfile();
+        const recorded = pid !== null && isPidAlive(pid);
+        try {
+            let forceKilled = false;
+            if (recorded) {
+                forceKilled = (await stopDaemonProcess(pid)) === 'killed';
+            }
+            // Backstop: kill any daemon NOT covered by the pidfile signal above. When
+            // the recorded daemon exited cleanly it is already gone, so keepPid=null
+            // sweeps every remaining crtrd process; a stray that survived its own
+            // prior stop is exactly what this reaches.
+            const straysKilled = sweepStrayDaemons(null);
+            if (!recorded && straysKilled.length === 0)
+                return { stopped: false };
+            return {
+                stopped: true,
+                ...(recorded ? { pid } : {}),
+                ...(straysKilled.length > 0 ? { strays_killed: straysKilled } : {}),
+                ...(forceKilled ? { force_killed: true } : {}),
+            };
+        }
+        catch (err) {
+            throw new InputError({
+                error: 'daemon_stop_failed',
+                message: `failed to stop daemon${recorded ? ` pid ${pid}` : ''}: ${err.message}`,
+                next: 'Run `crtr sys daemon status` to inspect the daemon before retrying.',
+            });
+        }
+    },
+});
+// Export — mounted under `crtr sys`
+export const daemonBranch = defineBranch({
+    name: 'daemon',
+    description: 'manage the crtrd supervisor process',
+    whenToUse: 'managing the crtrd supervisor that auto-revives nodes on window exit — start it, restart it onto a new runtime generation, check its status, or stop it',
+    help: {
+        name: 'sys daemon',
+        summary: 'manage the crtrd canvas supervisor daemon',
+        model: 'crtrd is a thin background daemon that polls active+idle nodes and acts on window exit: crashed windows become dead; refresh-yield windows get a fresh respawn. It holds no orchestration logic — just process supervision. These are operator/dev self-management, not something a normal agent turn needs to check. Picking up a newly installed runtime generation is `restart` (a handover the daemon performs on itself); `stop` is the terminal one, and it kills the caller along with the rest of the fleet.',
+    },
+    children: [daemonStart, daemonAwait, daemonAdmit, daemonRestart, daemonStatus, daemonStop],
+});
+/** The daemon-only `sys` subtree used before scoped user state is available. */
+export function registerDaemonControlSys() {
+    return defineSysBranch([daemonBranch]);
+}

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

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

package/dist/commands/sys/db.js

@@ -0,0 +1,69 @@
+// `crtr sys db`: offline operations on the canvas database. Today one leaf: the rollback export to SQLite.
+import { existsSync } from 'node:fs';
+import { defineBranch, defineLeaf } from '../../core/command.js';
+import { general } from '../../core/errors.js';
+import { canvasDbPath } from '../../core/canvas/paths.js';
+import { isDaemonRunning } from '../../daemon/pidfile.js';
+import { runDaemonExportSqlite } from '../../daemon/manage.js';
+const sysDbExportSqliteLeaf = defineLeaf({
+    name: 'export-sqlite',
+    description: 'write the Postgres canvas database back into a SQLite canvas.db, for rolling back to a generation that predates Postgres',
+    whenToUse: 'rolling back to a runtime generation that still uses SQLite, after `crtr sys daemon stop`. Not part of normal operation; the Postgres generation never needs it.',
+    help: {
+        name: 'sys db export-sqlite',
+        summary: 'copy the Postgres canvas database into a new runtime/canvas.db at the SQLite schema version the previous generation expects',
+        guide: 'Rollback sequence: `crtr sys daemon stop` (drains the daemon, releases its claim, stops the supervised Postgres), `crtr sys db export-sqlite` (this command starts the supervised Postgres by itself, copies every table with object ids mapped back to rowids, verifies row counts, and renames the result into place as runtime/canvas.db), select the previous runtime generation, `crtr sys daemon start`. If the export fails before publishing, canvas.db is not created and the Postgres data is untouched (only the export mark may be left, which keeps a later Postgres boot from importing a restored canvas.db over newer data): rename `runtime/canvas.db.imported` back to `runtime/canvas.db` to start the previous generation from the database as it was before the first Postgres boot, which loses every write made since. This command does not do that rename for you.',
+        params: [],
+        output: [
+            { name: 'path', type: 'string', required: true, constraint: 'The canvas.db that was written.' },
+            { name: 'rows', type: 'number', required: true, constraint: 'Rows copied across all tables.' },
+            { name: 'user_version', type: 'number', required: true, constraint: 'The SQLite schema version of the written file.' },
+            { name: 'ms', type: 'number', required: true, constraint: 'Wall time of the copy.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Starts the supervised Postgres if it is not running (or uses CRTR_DATABASE_URL), reads it in one read-only transaction, and writes runtime/canvas.db.exporting-<pid>, then renames it to runtime/canvas.db. Stops the Postgres again afterwards if this command started it.',
+            'Records an exported_to_sqlite mark in the Postgres canvas_meta before publishing runtime/canvas.db, so a later boot of the Postgres generation refuses to import this canvas.db over newer Postgres data.',
+            'Refuses while a daemon is running, and when runtime/canvas.db already exists.',
+        ],
+    },
+    run: async () => {
+        if (isDaemonRunning()) {
+            throw general('a daemon is running; an export taken under it would miss writes made after the copy', {
+                next: 'Run `crtr sys daemon stop`, then `crtr sys db export-sqlite`.',
+            });
+        }
+        const target = canvasDbPath();
+        if (existsSync(target)) {
+            throw general(`${target} already exists`, {
+                next: `Move it aside (or delete it if it is a leftover) before exporting; ${target}.imported is the pre-Postgres database kept by the import.`,
+            });
+        }
+        try {
+            const result = await runDaemonExportSqlite();
+            return { path: result.path, rows: result.rows, user_version: result.userVersion, ms: result.ms };
+        }
+        catch (error) {
+            const message = `export failed: ${error.message}`;
+            if (existsSync(target)) {
+                throw general(`${message}; ${target} was published before the failure`, {
+                    next: `${target} may be complete: inspect it before using it, or move it aside and rerun the export.`,
+                });
+            }
+            throw general(message, {
+                next: `Nothing was written to ${target}. To start the previous generation from the pre-Postgres database instead, rename ${target}.imported to ${target}; every write made since the Postgres import is lost.`,
+            });
+        }
+    },
+});
+export const sysDbBranch = defineBranch({
+    name: 'db',
+    description: 'offline operations on the canvas database',
+    whenToUse: 'rolling the canvas database back to SQLite after a Postgres soak fails',
+    help: {
+        name: 'sys db',
+        summary: 'offline canvas database operations',
+        model: 'The canvas lives in a supervised Postgres. These commands run with the daemon stopped and are for migration and rollback only.',
+    },
+    children: [sysDbExportSqliteLeaf],
+});

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

@@ -0,0 +1,5 @@
+export declare const DESKTOP_DMG_URL = "https://downloads.northlight.ai/desktop/mac/Northlight-Desktop.dmg";
+/** Northlight Desktop's Developer ID team (Vallum Security Inc.). */
+export declare const DESKTOP_TEAM_ID = "BRL7SHLNLU";
+export declare const sysDesktopInstallLeaf: import("../../core/command.js").LeafDef;
+export declare const sysDesktopBranch: import("../../core/command.js").BranchDef;

package/dist/commands/sys/desktop.js

@@ -0,0 +1,201 @@
+// `crtr sys desktop install`: download Northlight Desktop, install it in Applications and open it. Installing needs no crtr sign-in: the person signs in inside Desktop.
+// On a Mac that is signed in and moved, it also pairs Desktop to that account. Pairing is the pre-confirmed enrollment of design D12: the directory mints a confirmed device code for Desktop's install id, crtr hands it to
+// Desktop in `pairing.json` in Desktop's own data folder, and Desktop redeems it through its existing poll, with no code shown and no Allow click.
+import { execFile } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { defineBranch, defineLeaf } from '../../core/command.js';
+import { CrtrError, general, usage } from '../../core/errors.js';
+import { atomicWriteJson } from '../../core/fs-utils.js';
+import { northlightUnreachable } from '../../core/directory/reach.js';
+import { readPersonCredential, personAccount } from '../../core/directory/person-credential.js';
+import { readMachineConfig } from '../../daemon/machine-link/config.js';
+import { ExitCode } from '../../types.js';
+const run = promisify(execFile);
+export const DESKTOP_DMG_URL = 'https://downloads.northlight.ai/desktop/mac/Northlight-Desktop.dmg';
+/** Northlight Desktop's Developer ID team (Vallum Security Inc.). */
+export const DESKTOP_TEAM_ID = 'BRL7SHLNLU';
+const APP_NAME = 'Northlight Desktop.app';
+const APPLICATIONS = '/Applications';
+const DATA_DIR = join(homedir(), 'Library', 'Application Support', 'Northlight Desktop');
+const INSTALL_WAIT_MS = 30_000;
+const PAIR_WAIT_MS = 120_000;
+const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const appPath = () => join(APPLICATIONS, APP_NAME);
+const sh = async (command, args) => (await run(command, args, { maxBuffer: 16 * 1024 * 1024 })).stdout;
+async function desktopRunning() {
+    try {
+        await sh('pgrep', ['-f', `${appPath()}/Contents/MacOS/`]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Whether this Mac's Desktop is registered to `owner`: Desktop writes `machine.json` in its own data folder once the directory has registered it, and its `owner` is the
+ *  account it belongs to. Nothing is asked of the directory or the account's other Macs, so a Desktop on another Mac never counts. */
+function desktopPaired(owner) {
+    try {
+        return JSON.parse(readFileSync(join(DATA_DIR, 'machine.json'), 'utf8'))?.owner === owner;
+    }
+    catch {
+        return false;
+    }
+}
+async function download(dir) {
+    const dmg = join(dir, 'Northlight-Desktop.dmg');
+    try {
+        await sh('curl', ['-fsSL', '--max-time', '600', '-o', dmg, DESKTOP_DMG_URL]);
+    }
+    catch (error) {
+        const stderr = String(error.stderr ?? '');
+        if (/Could not resolve|Failed to connect|timed out|SSL|Connection|resolve host/i.test(stderr))
+            throw northlightUnreachable(error, DESKTOP_DMG_URL);
+        throw general(`the Desktop download failed: ${stderr.trim() || error.message}`);
+    }
+    return dmg;
+}
+/** Mount the image, verify the app inside is signed by Northlight, copy it into Applications, unmount. */
+async function installFrom(dmg, mount) {
+    await sh('hdiutil', ['attach', '-nobrowse', '-readonly', '-mountpoint', mount, dmg]);
+    try {
+        const source = join(mount, APP_NAME);
+        try {
+            await sh('codesign', ['--verify', '--deep', '--strict', source]);
+        }
+        catch (error) {
+            throw general(`the downloaded Desktop failed its signature check, so it was not installed: ${String(error.stderr ?? error.message).trim()}`);
+        }
+        const details = (await run('codesign', ['-dv', '--verbose=4', source])).stderr;
+        const team = /^TeamIdentifier=(\S+)$/m.exec(details)?.[1];
+        if (team !== DESKTOP_TEAM_ID)
+            throw general(`the downloaded Desktop is signed by team ${team ?? 'none'}, not Northlight's ${DESKTOP_TEAM_ID}, so it was not installed`);
+        await sh('ditto', [source, appPath()]);
+    }
+    finally {
+        await sh('hdiutil', ['detach', mount, '-quiet']).catch(() => undefined);
+    }
+}
+async function waitForInstallId() {
+    const path = join(DATA_DIR, 'install.json');
+    for (const deadline = Date.now() + INSTALL_WAIT_MS; Date.now() < deadline; await sleep(500)) {
+        try {
+            const id = JSON.parse(readFileSync(path, 'utf8')).install_id;
+            if (typeof id === 'string' && UUID_V4.test(id))
+                return id;
+        }
+        catch { /* not written yet */ }
+    }
+    throw general(`Desktop opened but did not write ${path} within ${INSTALL_WAIT_MS / 1000} seconds`, { next: 'Open Northlight Desktop yourself, then run `crtr sys desktop install` again.' });
+}
+/** `POST /v1/developer/desktop-enrollment`: a confirmed device code for this install id, minted with the stored sign-in; undefined when the directory no longer accepts that sign-in. */
+async function mintPairing(directoryUrl, installId) {
+    const credential = readPersonCredential();
+    const url = `${directoryUrl.replace(/\/+$/, '')}/v1/developer/desktop-enrollment`;
+    let response;
+    try {
+        response = await fetch(url, { method: 'POST', headers: { 'content-type': 'application/json', authorization: `Bearer ${credential.secret}` }, body: JSON.stringify({ install_id: installId }), signal: AbortSignal.timeout(30_000) });
+    }
+    catch (error) {
+        throw northlightUnreachable(error, url);
+    }
+    const text = await response.text();
+    let body = {};
+    try {
+        body = text === '' ? {} : JSON.parse(text);
+    }
+    catch { /* an error page has no body */ }
+    if (response.status === 401) {
+        const code = typeof body.error === 'object' ? body.error?.code : body.error;
+        if (code === 'credential_revoked' || code === 'credential_expired' || code === 'credential_unknown')
+            return undefined; // the stored sign-in was revoked since it was checked: the person signs in inside Desktop instead
+    }
+    if (!response.ok || typeof body.device_code !== 'string' || typeof body.expires_in !== 'number') {
+        const message = typeof body.error === 'object' && typeof body.error?.message === 'string' ? body.error.message : `HTTP ${response.status}`;
+        throw general(`Northlight refused to pair Desktop: ${message}`);
+    }
+    return { device_code: body.device_code, expires_in: body.expires_in };
+}
+const openApp = () => sh('open', ['-a', appPath()]);
+const SIGN_IN_INSIDE_DESKTOP = 'Northlight Desktop is open. Tell the person to sign in inside it with their Northlight account: its window shows a code and one Allow click, or use "Connect this Mac…" in its menu-bar icon. Then retry the command that needed it.';
+/** The account this Mac is signed in to and moved under, when it is; undefined on a Mac that is signed out, not moved, or whose sign-in was revoked. Installing Desktop never needs one. */
+async function pairingAccount() {
+    const credential = readPersonCredential();
+    if (credential === undefined || readMachineConfig() === undefined)
+        return undefined;
+    try {
+        return { owner: (await personAccount(credential.directoryUrl)).id, directoryUrl: credential.directoryUrl };
+    }
+    catch (error) {
+        if (error instanceof CrtrError && error.code === 'not_signed_in')
+            return undefined;
+        throw error;
+    }
+}
+export const sysDesktopInstallLeaf = defineLeaf({
+    name: 'install',
+    description: 'download, install and open Northlight Desktop on this Mac',
+    whenToUse: 'a `device` command answered that no Northlight app is paired to this account, you are on the person\'s Mac, and the person said yes to installing it',
+    help: {
+        name: 'sys desktop install',
+        summary: 'install Northlight Desktop in Applications and open it; the person then signs in inside Desktop',
+        guide: 'macOS only; needs no crtr sign-in. Downloads Desktop from downloads.northlight.ai, checks it is signed by Northlight, installs it and opens it. A Desktop already in Applications is opened, not replaced. When crtr on this Mac is also signed in and moved to Northlight, Desktop is paired to that account with no code and no Allow click, and the command waits up to two minutes for it to register. Otherwise `follow_up` says the person signs in inside Desktop with their Northlight account (its window, or "Connect this Mac…" in the menu-bar icon). Safe to run again. macOS permission prompts (Full Disk Access, Messages) still appear when a feature needs them.',
+        params: [],
+        output: [
+            { name: 'installed', type: 'boolean', required: true, constraint: 'True when this run installed Desktop; false when it was already installed.' },
+            { name: 'paired', type: 'boolean', required: true, constraint: 'True when Desktop on this Mac is registered to the account crtr is signed in to; false when the person still has to sign in inside Desktop.' },
+            { name: 'follow_up', type: 'string', required: false, constraint: 'Present when `paired` is false: what to tell the person.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Downloads and mounts the Desktop image, then copies the app to `/Applications/Northlight Desktop.app` (a copy that is running is left as it is and only paired). Opens Desktop. Only when crtr on this Mac is signed in and moved: calls `POST /v1/developer/desktop-enrollment` with the stored sign-in and writes `~/Library/Application Support/Northlight Desktop/pairing.json` (mode 0600), which Desktop deletes when it reads it.',
+        ],
+    },
+    run: async () => {
+        if (process.platform !== 'darwin')
+            throw usage('Northlight Desktop is a Mac app: this command only runs on macOS');
+        const account = await pairingAccount();
+        if (account !== undefined && existsSync(appPath()) && desktopPaired(account.owner)) {
+            await openApp();
+            return { installed: false, paired: true };
+        }
+        // A copy already in Applications is never replaced when signed out, and a running one is never replaced; it is paired as it is.
+        const replace = account === undefined ? !existsSync(appPath()) : !(existsSync(appPath()) && await desktopRunning());
+        if (replace) {
+            const tmp = mkdtempSync(join(tmpdir(), 'crtr-desktop-'));
+            try {
+                await installFrom(await download(tmp), join(tmp, 'mnt'));
+            }
+            finally {
+                rmSync(tmp, { recursive: true, force: true });
+            }
+        }
+        if (account === undefined) {
+            await openApp();
+            return { installed: replace, paired: false, follow_up: SIGN_IN_INSIDE_DESKTOP };
+        }
+        const { owner, directoryUrl } = account;
+        await openApp();
+        const installId = await waitForInstallId();
+        const pairing = await mintPairing(directoryUrl, installId);
+        if (pairing === undefined)
+            return { installed: replace, paired: false, follow_up: SIGN_IN_INSIDE_DESKTOP };
+        atomicWriteJson(join(DATA_DIR, 'pairing.json'), { issuer: directoryUrl.replace(/\/+$/, ''), device_code: pairing.device_code }, { mode: 0o600 });
+        await openApp(); // Desktop reads the file on activate
+        for (const deadline = Date.now() + PAIR_WAIT_MS; Date.now() < deadline; await sleep(3000))
+            if (desktopPaired(owner))
+                return { installed: replace, paired: true };
+        throw new CrtrError('desktop_not_paired', 'Desktop opened but did not pair.', ExitCode.GENERAL, { next: 'If Desktop is signed in to another account, sign out there and run `crtr sys desktop install` again.' });
+    },
+    render: (r) => `<desktop installed="${r['installed']}" paired="${r['paired']}">${r['follow_up'] ?? ''}</desktop>`,
+});
+export const sysDesktopBranch = defineBranch({
+    name: 'desktop',
+    description: 'Northlight Desktop on this Mac',
+    whenToUse: 'Northlight Desktop must be installed and paired to this account',
+    help: { name: 'sys desktop', summary: 'install and pair Northlight Desktop' },
+    children: [sysDesktopInstallLeaf],
+});