@ctrl-spc/cs 0.7.14 → 0.7.15

package/dist/daemon-lifecycle.js

@@ -0,0 +1,548 @@
+import { createServer } from 'node:http';
+import { randomUUID, timingSafeEqual, createHash } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync, openSync, closeSync, mkdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { configDir, getMachineIdentity, lifecycleToken, readLifecycleToken, readMcpToken, readSession, machineHostname } from './config.js';
+import { entryPath, ensureAutostart, prepareAutostart, autostartDisabled, autostartEnabled, loadedStartupJob, unloadStoppedStartupJob } from './autostart.js';
+import { CLI_VERSION } from './package-version.js';
+import { TOOLS_SERVER_PORT } from './env.js';
+import { claimLifecycleOperation, publishRuntime, readMigration, readOperation, readRuntime, removeOperation, removeRuntime, updateOperation, updateRuntime, writeMigration } from './daemon-lock.js';
+import { inspectProcess, processIdentityMatches, osBootIdentity, loopbackListenerPid, terminateOwnedRoot } from './win-shell.js';
+import { initializeOwnedWork, snapshotOwnedWork, interruptOwnedWork, markOwnedWorkInterrupted, ownedWorkInstanceNonces } from './daemon-processes.js';
+import { startPresence, stopPresence, liveClient, suspendPresenceWork, resumePresenceWork, presenceCloudState } from './presence.js';
+import { NotLoggedIn } from './supabase.js';
+import { launchWindowsService, windowsJobExecutable } from './windows-job.js';
+const MAX_COMMAND_MS = 30_000;
+const installationCheckpoint = join(dirname(dirname(fileURLToPath(import.meta.url))), '.lifecycle-install.json');
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function milliseconds(deadline) {
+    const left = deadline - Date.now();
+    if (left <= 0)
+        throw new Error('Service operation did not finish within 30 seconds. Run cs status before retrying.');
+    return left;
+}
+function assertOperationOwned(id) {
+    if (readOperation()?.id !== id)
+        throw new Error('Another service command now owns recovery. Run cs status before retrying.');
+}
+async function bounded(promise, deadline) {
+    let timer;
+    try {
+        return await Promise.race([promise, new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error('Service operation did not finish within 30 seconds. Run cs status before retrying.')), milliseconds(deadline));
+            })]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+function sessionFingerprint() {
+    const session = readSession();
+    return session ? createHash('sha256').update(JSON.stringify(session)).digest('hex') : 'none';
+}
+function pendingExecution(work) {
+    const claims = new Set((work.claimPending ?? []).map((item) => item.id));
+    return work.pending.filter((item) => !claims.has(item.id));
+}
+async function control(record, action, deadline, body) {
+    const token = readLifecycleToken();
+    if (!token)
+        throw new Error('The local service control credential is unavailable. No process was changed.');
+    const res = await fetch('http://127.0.0.1:' + record.port + '/' + action, {
+        method: action === 'status' ? 'GET' : 'POST',
+        headers: { authorization: 'Bearer ' + token, ...(body ? { 'content-type': 'application/json' } : {}) },
+        body: body ? JSON.stringify(body) : undefined,
+        signal: AbortSignal.timeout(Math.min(milliseconds(deadline), action === 'status' ? 10_000 : MAX_COMMAND_MS)),
+    });
+    const data = await res.json();
+    if (!res.ok)
+        throw new Error(typeof data?.error === 'string' ? data.error : 'Local service control failed.');
+    const status = data;
+    if (!status || status.nonce !== record.nonce || status.pid !== record.process.pid || status.version !== record.version || typeof status.local !== 'string' || typeof status.cloud !== 'string' || !status.work || !Array.isArray(status.work.active) || !Array.isArray(status.work.unknown) || !Array.isArray(status.work.pending)) {
+        throw new Error('The local service returned an invalid identity. No replacement will start.');
+    }
+    return status;
+}
+export async function inspectLocalRuntime(deadline = Date.now() + 10_000) {
+    const record = readRuntime();
+    if (!record)
+        return null;
+    const actual = await inspectProcess(record.process.pid, deadline);
+    if (!actual || !processIdentityMatches(record.process, actual))
+        return null;
+    try {
+        return { record, status: await control(record, 'status', deadline) };
+    }
+    catch {
+        return { record, status: null };
+    } // Verified local owner is alive; readiness remains unknown.
+}
+async function verifiedLegacyOwner(deadline) {
+    const token = readMcpToken();
+    if (!token)
+        return false;
+    const listener = await loopbackListenerPid(TOOLS_SERVER_PORT, deadline);
+    if (!listener)
+        return false;
+    const owner = await inspectProcess(listener, deadline);
+    const caller = await inspectProcess(process.pid, deadline);
+    if (!owner || !caller || owner.owner !== caller.owner)
+        throw new Error('The tools listener belongs to an unverified user. No process was changed.');
+    const client = new Client({ name: 'cs-lifecycle-inspection', version: CLI_VERSION });
+    try {
+        await bounded(client.connect(new StreamableHTTPClientTransport(new URL('http://127.0.0.1:' + TOOLS_SERVER_PORT + '/mcp?token=' + encodeURIComponent(token)), {
+            requestInit: { signal: AbortSignal.timeout(Math.min(2500, milliseconds(deadline))) },
+        })), deadline);
+        return true;
+    }
+    catch {
+        throw new Error('The existing tools listener cannot be verified. No process was changed. Check this instance with cs status.');
+    }
+    finally {
+        await client.close().catch(() => { });
+    }
+}
+export async function writeInstallationCheckpoint() {
+    const boot = await osBootIdentity();
+    writeFileSync(installationCheckpoint, JSON.stringify({ schema: 1, boot, entry: entryPath(), version: CLI_VERSION }), { mode: 0o600 });
+}
+function checkpointBoot() {
+    try {
+        const data = JSON.parse(readFileSync(installationCheckpoint, 'utf8'));
+        const record = data;
+        return record.schema === 1 && record.entry === entryPath() && record.version === CLI_VERSION && typeof record.boot === 'string' ? record.boot : null;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT' || error instanceof SyntaxError)
+            return null;
+        throw error;
+    }
+}
+function upgradeMessage() {
+    return 'Computer restart required — one-time upgrade on ' + machineHostname() + '.\n' +
+        'The older service may still be running work. No replacement was started.\n' +
+        'Save your work, then restart this computer. After signing back in, run cs status.\n' +
+        (autostartDisabled() ? 'Automatic startup is off; run cs start first.\n' : '') +
+        'Saved files and conversations remain. Open interrupted cards and send a message to continue.\n' +
+        'Later service stop and restart will not require a computer restart.';
+}
+/** Returns true when the ledger must perform its first post-upgrade reconciliation. */
+async function prepareLegacyUpgrade(deadline) {
+    const prior = readMigration();
+    if (prior?.completed) {
+        // A later invocation of an obsolete install can reintroduce an untracked
+        // owner even after migration. Never treat its responding tools as ours.
+        const boot = await osBootIdentity(deadline);
+        if (await verifiedLegacyOwner(deadline)) {
+            // The old service can disappear while its agents survive. Persist this
+            // boot's hold before reporting it, so its later absence cannot admit work.
+            writeMigration({ ...prior, boot, prepared: false, completed: false });
+            throw new Error('An older service is running again on ' + machineHostname() + '. No replacement was started. Correct its obsolete startup entry, then restart this computer and run cs start from the current installation.');
+        }
+        return false;
+    }
+    const runtime = readRuntime();
+    const evidence = prior || (!runtime && (existsSync(join(configDir(), 'daemon.pid')) || readMcpToken() || autostartEnabled()));
+    if (!evidence)
+        return false;
+    const machine = getMachineIdentity();
+    const boot = await osBootIdentity(deadline);
+    const checkpoint = prior?.boot ?? checkpointBoot() ?? boot;
+    const record = prior ?? { schema: 1, boot: checkpoint, installation: entryPath(), prepared: false, completed: false, machineId: machine.id, accountId: null };
+    if (record.machineId !== machine.id)
+        throw new Error('The pending upgrade belongs to a different local instance.');
+    // Preserve the previous checkpoint while preparing the invoking installation.
+    prepareAutostart();
+    record.prepared = true;
+    record.installation = entryPath();
+    writeMigration(record);
+    if (checkpoint === boot)
+        throw new Error(upgradeMessage());
+    if (await verifiedLegacyOwner(deadline)) {
+        writeMigration({ ...record, boot, completed: false });
+        throw new Error('An older service started again on ' + machine.name + ' after the computer restart. Its obsolete launcher must be corrected before retrying; no replacement was started.');
+    }
+    return true;
+}
+/** Explicit cs open against an older resident companion uses the same upgrade. */
+export async function checkLegacyUpgrade() {
+    const deadline = Date.now() + MAX_COMMAND_MS;
+    const operation = await claimLifecycleOperation('start', deadline);
+    try {
+        await prepareLegacyUpgrade(deadline);
+    }
+    finally {
+        removeOperation(operation.id);
+    }
+}
+let runtime = null;
+let shutdownPromise = null;
+let connecting = null;
+let rejectedSession = null;
+let signalController = null;
+async function runtimeStatus(deadline = Date.now() + 8000) {
+    if (!runtime)
+        throw new Error('This process does not own the local service.');
+    return { nonce: runtime.record.nonce, pid: process.pid, version: CLI_VERSION, local: runtime.record.state, cloud: presenceCloudState(), work: await snapshotOwnedWork(deadline) };
+}
+async function connectCloud() {
+    if (!runtime || runtime.record.state === 'stopping' || connecting || liveClient())
+        return;
+    if (rejectedSession === sessionFingerprint())
+        return;
+    connecting = (async () => {
+        try {
+            await startPresence();
+            rejectedSession = null;
+        }
+        catch (error) {
+            if (error instanceof NotLoggedIn)
+                rejectedSession = sessionFingerprint();
+            console.warn(error instanceof NotLoggedIn ? 'Cloud sign-in is required. Local service controls remain available.' : 'Cloud connection is unavailable. Local service controls remain available.');
+        }
+    })();
+    try {
+        await connecting;
+    }
+    finally {
+        connecting = null;
+    }
+}
+export function localRuntimeOwned() { return runtime !== null; }
+async function shutdown(force, operationId, deadline) {
+    if (shutdownPromise)
+        return shutdownPromise;
+    shutdownPromise = (async () => {
+        if (!runtime)
+            throw new Error('This process does not own the service.');
+        const current = runtime;
+        current.record.state = 'stopping';
+        updateRuntime(current.record);
+        await bounded(suspendPresenceWork({ waitForClaims: !force }), deadline);
+        const work = await snapshotOwnedWork(deadline);
+        assertOperationOwned(operationId);
+        if (work.unknown.length || (!force && (work.active.length || work.pending.length))) {
+            current.record.state = 'running';
+            updateRuntime(current.record);
+            resumePresenceWork();
+            const names = [...work.active, ...work.pending, ...work.unknown].map((w) => (w.cardId ?? w.workId ?? 'Card identity unavailable') + ' — ' + (w.harness ?? 'harness unknown')).join('\n  ');
+            throw new Error('Not stopped: owned work is ' + (work.unknown.length ? 'not fully verified' : 'still running') + '.\n  ' + names + '\nWait for it to finish' + (work.unknown.length ? ' and run cs status.' : ', or interrupt it explicitly with cs stop --force or cs restart --force. Saved work will need continuation.'));
+        }
+        if (force)
+            await interruptOwnedWork(operationId, deadline);
+        const after = await snapshotOwnedWork(deadline);
+        if (after.active.length || (force ? pendingExecution(after) : after.pending).length || after.unknown.length)
+            throw new Error('Owned execution remains. No replacement can start.');
+        assertOperationOwned(operationId);
+        clearInterval(current.timer);
+        // Once local execution is proven closed, cloud acknowledgements and open
+        // Companion requests cannot veto stopping this process. Deferred claim
+        // journals and the instance interruption intent survive the local exit.
+        let cleanupConfirmed = true;
+        try {
+            await bounded(stopPresence(), Math.min(deadline, Date.now() + 5000));
+        }
+        catch {
+            cleanupConfirmed = false;
+        }
+        if (current.onStop) {
+            try {
+                await bounded(current.onStop(), Math.min(deadline, Date.now() + 1000));
+            }
+            catch {
+                cleanupConfirmed = false;
+            }
+        }
+        if (!cleanupConfirmed)
+            console.warn('Local execution ended. Cloud or Companion cleanup could not be acknowledged; remote status will update after reconnecting or its freshness window.');
+        const result = await runtimeStatus(deadline);
+        result.local = 'stopped';
+        if (force)
+            result.interruptedWork = [...work.active, ...work.pending];
+        removeRuntime(current.record.nonce);
+        return result;
+    })();
+    try {
+        return await shutdownPromise;
+    }
+    catch (error) {
+        if (runtime && runtime.record.state === 'stopping') {
+            runtime.record.state = 'degraded';
+            updateRuntime(runtime.record);
+        }
+        if (!force && error instanceof Error && /deadline|30 seconds/.test(error.message)) {
+            throw new Error(error.message + ' To explicitly interrupt owned work, use cs stop --force or cs restart --force.', { cause: error });
+        }
+        throw error;
+    }
+    finally {
+        shutdownPromise = null;
+    }
+}
+async function readBody(req) {
+    const chunks = [];
+    let bytes = 0;
+    for await (const chunk of req) {
+        bytes += chunk.length;
+        if (bytes > 2048)
+            throw new Error('Local control request is too large.');
+        chunks.push(chunk);
+    }
+    const value = JSON.parse(Buffer.concat(chunks).toString());
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Invalid local control request.');
+    return value;
+}
+/** CLI and Companion share this owner, which is available before cloud sign-in. */
+export async function startLocalRuntime({ onStop } = {}) {
+    if (runtime)
+        return true;
+    const deadline = Date.now() + MAX_COMMAND_MS;
+    const existing = await inspectLocalRuntime(deadline);
+    if (existing)
+        return false;
+    const handover = process.env.CTRL_SPC_LIFECYCLE_HANDOVER;
+    let operation;
+    if (handover) {
+        const reserved = readOperation();
+        if (!reserved || reserved.successor !== handover || reserved.entry !== entryPath() || !process.argv.includes('--lifecycle-handover=' + handover))
+            throw new Error('The service handover is not owned by this installation.');
+        operation = reserved;
+    }
+    else
+        operation = await claimLifecycleOperation('start', deadline);
+    let published = false;
+    try {
+        const old = readRuntime();
+        if (old) {
+            const live = await inspectProcess(old.process.pid, deadline);
+            if (live && processIdentityMatches(old.process, live))
+                return false;
+            removeRuntime(old.nonce);
+        }
+        const legacyUpgrade = await prepareLegacyUpgrade(deadline);
+        const machine = getMachineIdentity();
+        const nonce = handover ?? randomUUID();
+        initializeOwnedWork({ instanceNonce: nonce, accountId: null, machineId: machine.id, legacyUpgrade });
+        const remainingWork = await snapshotOwnedWork(deadline);
+        if (remainingWork.active.length || remainingWork.pending.length || remainingWork.unknown.length)
+            throw new Error('A prior owned assignment still needs recovery. Run cs status before starting another service.');
+        ensureAutostart();
+        const token = lifecycleToken();
+        const self = await inspectProcess(process.pid, deadline);
+        if (!self)
+            throw new Error('The service could not verify its own process identity.');
+        const server = createServer((req, res) => {
+            void (async () => {
+                const auth = Buffer.from(req.headers.authorization ?? '');
+                const expected = Buffer.from('Bearer ' + token);
+                const port = server.address().port;
+                const valid = !req.headers.origin && req.headers.host === '127.0.0.1:' + port && auth.length === expected.length && timingSafeEqual(auth, expected);
+                res.setHeader('content-type', 'application/json');
+                res.setHeader('cache-control', 'no-store');
+                if (!valid) {
+                    res.writeHead(403);
+                    res.end(JSON.stringify({ error: 'Local control is not authorized.' }));
+                    return;
+                }
+                if (req.url === '/status' && req.method === 'GET') {
+                    res.end(JSON.stringify(await runtimeStatus()));
+                    return;
+                }
+                if (req.url !== '/stop' || req.method !== 'POST' || req.headers['content-type'] !== 'application/json') {
+                    res.writeHead(405);
+                    res.end(JSON.stringify({ error: 'Unsupported local control action.' }));
+                    return;
+                }
+                const body = await readBody(req);
+                const op = readOperation();
+                if (typeof body.force !== 'boolean' || typeof body.deadline !== 'number' || !op || op.id !== body.operationId)
+                    throw new Error('Invalid lifecycle operation.');
+                const result = await shutdown(body.force, op.id, Math.min(body.deadline, Date.now() + MAX_COMMAND_MS));
+                const exitStoppedOwner = () => { server.close(); process.exit(0); };
+                res.once('finish', exitStoppedOwner);
+                res.once('close', exitStoppedOwner);
+                // A cancelled controller may have closed the socket during cleanup.
+                // Ownership is already released; that socket must not keep us alive.
+                setTimeout(exitStoppedOwner, 250).unref();
+                res.end(JSON.stringify(result));
+            })().catch((error) => {
+                if (!res.headersSent)
+                    res.writeHead(409);
+                res.end(JSON.stringify({ error: error instanceof Error ? error.message : 'Local control failed.' }));
+            });
+        });
+        server.requestTimeout = 5000;
+        server.headersTimeout = 5000;
+        await bounded(new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', resolve); }), deadline);
+        const record = { schema: 1, nonce, config: resolve(configDir()), machineId: machine.id, process: self, entry: entryPath(), version: CLI_VERSION, port: server.address().port, state: 'running' };
+        try {
+            publishRuntime(record);
+        }
+        catch (error) {
+            server.close();
+            throw error;
+        }
+        published = true;
+        const timer = setInterval(() => void connectCloud(), 3000);
+        runtime = { record, server, timer, onStop };
+        const upgrade = readMigration();
+        if (upgrade && legacyUpgrade)
+            writeMigration({ ...upgrade, completed: true });
+        if (!upgrade)
+            writeMigration({ schema: 1, boot: await osBootIdentity(deadline), installation: entryPath(), prepared: true, completed: true, machineId: machine.id, accountId: null });
+        if (!handover)
+            removeOperation(operation.id);
+        void connectCloud();
+        return true;
+    }
+    finally {
+        if (!handover && !published && !operation.successor)
+            removeOperation(operation.id);
+    }
+}
+export async function stopLocalOwnerForSignal() {
+    if (signalController)
+        return;
+    // An external controller can unload our verified launchd job after draining,
+    // including an old unconditional KeepAlive job still loaded at this login.
+    signalController = spawn(process.execPath, [entryPath(), 'stop'], {
+        windowsHide: true, stdio: ['ignore', 'inherit', 'inherit'], env: { ...process.env, CTRL_SPC_LIFECYCLE_HANDOVER: undefined },
+    });
+    const controller = signalController;
+    try {
+        await new Promise((resolve, reject) => { controller.once('error', reject); controller.once('exit', () => resolve()); });
+    }
+    finally {
+        signalController = null;
+    }
+}
+async function waitForExit(record, deadline) {
+    while (Date.now() < deadline) {
+        const actual = await inspectProcess(record.process.pid, deadline);
+        if (!actual || !processIdentityMatches(record.process, actual))
+            return;
+        await wait(50);
+    }
+    throw new Error('The previous service has not exited. No replacement was started.');
+}
+export async function runLifecycleCommand(action, force = false) {
+    const deadline = Date.now() + MAX_COMMAND_MS;
+    const operation = await claimLifecycleOperation(action, deadline);
+    let affected = [];
+    try {
+        const current = await inspectLocalRuntime(deadline);
+        assertOperationOwned(operation.id);
+        if (current) {
+            const job = await loadedStartupJob(current.record.process.pid, deadline);
+            if (!current.status) {
+                if (!force)
+                    throw new Error('The verified service is not answering local control. Run cs restart --force to interrupt verified owned work and recover this service.');
+                initializeOwnedWork({ instanceNonce: current.record.nonce, accountId: null, machineId: current.record.machineId });
+                const work = await snapshotOwnedWork(deadline);
+                affected = [...work.active, ...work.pending];
+                if (work.unknown.length || pendingExecution(work).length)
+                    throw new Error('Some owned execution could not be verified. No replacement was started. Run cs status to inspect the pending work.');
+                assertOperationOwned(operation.id);
+                await markOwnedWorkInterrupted(operation.id);
+                assertOperationOwned(operation.id);
+                await terminateOwnedRoot(current.record.process, deadline);
+                await waitForExit(current.record, deadline);
+                assertOperationOwned(operation.id);
+                await interruptOwnedWork(operation.id, deadline);
+                removeRuntime(current.record.nonce);
+            }
+            else {
+                const stopped = await control(current.record, 'stop', deadline, { force, operationId: operation.id, deadline });
+                affected = stopped.interruptedWork ?? [...current.status.work.active, ...current.status.work.pending];
+            }
+            assertOperationOwned(operation.id);
+            await unloadStoppedStartupJob(job, deadline);
+            await waitForExit(current.record, deadline);
+        }
+        else {
+            await prepareLegacyUpgrade(deadline);
+            const stale = readRuntime();
+            if (stale)
+                removeRuntime(stale.nonce);
+            const orphanScope = ownedWorkInstanceNonces();
+            initializeOwnedWork({ instanceNonce: randomUUID(), accountId: null, machineId: getMachineIdentity().id });
+            const remaining = await snapshotOwnedWork(deadline);
+            affected = [...remaining.active, ...remaining.pending];
+            if (remaining.unknown.length || (!force && (remaining.active.length || remaining.pending.length)))
+                throw new Error('Prior owned execution needs recovery. Wait, or use the explicit force command when ownership is verified.');
+            assertOperationOwned(operation.id);
+            if (force)
+                await interruptOwnedWork(operation.id, deadline, orphanScope);
+        }
+        if (force && affected.length) {
+            console.log('Interrupted work on ' + machineHostname() + ':');
+            for (const item of affected)
+                console.log('  ' + (item.cardId ?? item.workId ?? 'Card identity unavailable') + ' — ' + (item.harness ?? 'harness unknown'));
+            console.log('Open each interrupted card and send a new message to continue from saved progress.');
+        }
+        if (action === 'stop') {
+            console.log('CTRL+SPC is ' + (!current && !affected.length ? 'already stopped' : 'stopped') + ' on ' + machineHostname() + '. Start again: cs start. Future-login preference is unchanged.');
+            return;
+        }
+        assertOperationOwned(operation.id);
+        prepareAutostart();
+        operation.successor = randomUUID();
+        operation.entry = entryPath();
+        updateOperation(operation);
+        mkdirSync(configDir(), { recursive: true });
+        let child;
+        if (process.platform === 'win32') {
+            const executable = windowsJobExecutable(deadline);
+            assertOperationOwned(operation.id);
+            operation.successorPid = await launchWindowsService(executable, entryPath(), operation.successor, join(configDir(), 'daemon.log'), deadline);
+            updateOperation(operation);
+        }
+        else {
+            const log = openSync(join(configDir(), 'daemon.log'), 'a', 0o600);
+            try {
+                child = spawn(process.execPath, [entryPath(), 'start', '--lifecycle-handover=' + operation.successor], {
+                    detached: true, windowsHide: true, stdio: ['ignore', log, log],
+                    env: { ...process.env, CTRL_SPC_LIFECYCLE_HANDOVER: operation.successor },
+                });
+                await new Promise((resolve, reject) => { child.once('spawn', resolve); child.once('error', reject); });
+                operation.successorPid = child.pid;
+                updateOperation(operation);
+                child.unref();
+            }
+            finally {
+                closeSync(log);
+            }
+        }
+        while (Date.now() < deadline) {
+            const next = await inspectLocalRuntime(deadline);
+            if (next?.status && next.record.nonce === operation.successor && next.record.version === CLI_VERSION) {
+                console.log('Restarted CTRL+SPC on ' + machineHostname() + '.\nRunning version: ' + CLI_VERSION + ' — verified\nCloud connection: ' + next.status.cloud + '\nThe service stays running when this terminal closes.\nInterrupted cards need a new message to continue.');
+                if (next.status.cloud === 'sign-in-required')
+                    console.log('Sign in on ' + machineHostname() + ': cs login. Local restart succeeded.');
+                else if (next.status.cloud !== 'online')
+                    console.log('Run cs status to check cloud readiness and installed harnesses. If the connection remains unavailable, check this computer’s network.');
+                removeOperation(operation.id);
+                return;
+            }
+            if ((child && child.exitCode !== null) || (!child && !await inspectProcess(operation.successorPid, deadline)))
+                throw new Error('The installed replacement exited before verification. Check this instance with cs status; saved work remains.');
+            await wait(100);
+        }
+        throw new Error('The installed replacement could not be verified within 30 seconds. Run cs status; no second replacement was started.');
+    }
+    finally {
+        if (!operation.successor)
+            removeOperation(operation.id);
+    }
+}
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url) && process.argv[2] === '--installation-checkpoint') {
+    writeInstallationCheckpoint().catch(() => {
+        console.warn('CTRL+SPC could not record this installation’s boot checkpoint. Its first command will prepare the one-time upgrade if needed.');
+    });
+}