@platless/axom-cli 0.3.13 → 0.6.36

package/dist/workstation/update/rdRollback.js

@@ -0,0 +1,145 @@
+import { constants, promises as fs } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { assertLockOwnership, withPrivateLock } from '../control/locks.js';
+import { privateDirectory } from '../keepers/kit/paths.js';
+import { rdStateSchema } from '../rd/state.js';
+export function rdStateDigest(value) { return createHash('sha256').update(value).digest('hex'); }
+function snapshotPath(directory, commandId) { return path.join(directory, 'update', `rd-rollback-${rdStateDigest(commandId)}.json`); }
+export async function readPrivateRdFile(file, maxBytes = 131072) {
+    let handle;
+    try {
+        handle = await fs.open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    try {
+        const info = await handle.stat();
+        if (!info.isFile() || info.uid !== process.getuid?.() || info.mode & 0o077 || info.size > maxBytes)
+            throw new Error('Unsafe RD rollback state');
+        return await handle.readFile('utf8');
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function writePrivate(file, contents) {
+    await privateDirectory(path.dirname(file));
+    const staging = path.join(path.dirname(file), `.rd-rollback-${randomUUID()}`);
+    try {
+        await fs.writeFile(staging, contents, { mode: 0o600, flag: 'wx' });
+        assertLockOwnership();
+        await fs.rename(staging, file);
+    }
+    finally {
+        await fs.rm(staging, { force: true });
+    }
+}
+export async function snapshotRdForRollback(directory, command) {
+    return withPrivateLock(path.join(directory, 'rd', 'install'), async () => {
+        const previous = await readPrivateRdFile(path.join(directory, 'rd', 'state.json'), 32768);
+        const snapshot = snapshotPath(directory, command.commandId);
+        const value = { schemaVersion: 1, commandId: command.commandId, targetVersion: command.release.version,
+            releaseSha512: command.release.sha512, previous };
+        await writePrivate(snapshot, JSON.stringify(value));
+        return { directory, snapshot };
+    });
+}
+async function pendingUpdate(directory) {
+    const contents = await readPrivateRdFile(path.join(directory, 'update-state.json'));
+    return contents === null ? null : JSON.parse(contents);
+}
+export async function guardRdActivation(directory, cliVersion, next) {
+    const update = await pendingUpdate(directory);
+    if (!update || update.version !== cliVersion || !update.commandId)
+        return;
+    if (update.phase === 'ROLLED_BACK')
+        throw new Error('The CLI update was already rolled back before RD activation');
+    if (!update.releaseSha512)
+        return;
+    const planFile = path.join(directory, 'update', `watchdog-${rdStateDigest(update.commandId)}.json`);
+    const planContents = await readPrivateRdFile(planFile);
+    if (planContents === null)
+        return;
+    const plan = JSON.parse(planContents);
+    if (plan.commandId !== update.commandId || plan.targetVersion !== update.version)
+        throw new Error('RD watchdog plan does not match the pending CLI update');
+    const current = await readPrivateRdFile(path.join(directory, 'rd', 'state.json'), 32768);
+    if (current === null)
+        throw new Error('RD state disappeared before activation');
+    const guard = { commandId: update.commandId, targetVersion: update.version, releaseSha512: update.releaseSha512, previousSha256: rdStateDigest(current) };
+    if (!plan.rdRollback)
+        return await authenticatedRdActivation(directory, guard) ? undefined : guard;
+    const expected = snapshotPath(directory, update.commandId);
+    if (plan.rdRollback.directory !== directory || plan.rdRollback.snapshot !== expected)
+        throw new Error('RD rollback snapshot path does not match this update');
+    const contents = await readPrivateRdFile(expected);
+    if (contents === null)
+        throw new Error('RD rollback snapshot is missing');
+    const saved = JSON.parse(contents);
+    if (saved.schemaVersion !== 1 || saved.commandId !== update.commandId || saved.targetVersion !== update.version || saved.releaseSha512 !== update.releaseSha512)
+        throw new Error('RD rollback snapshot belongs to another CLI update');
+    const nextDigest = rdStateDigest(JSON.stringify(rdStateSchema.parse(next)));
+    if (saved.previous !== current && saved.activatedSha256 !== rdStateDigest(current))
+        return guard;
+    await writePrivate(expected, JSON.stringify({ ...saved, activatedSha256: nextDigest, activatedIdentity: undefined }));
+}
+async function stateIdentity(directory) {
+    const info = await fs.lstat(path.join(directory, 'rd', 'state.json'), { bigint: true });
+    return `${info.dev}:${info.ino}:${info.birthtimeNs}:${info.mtimeNs}`;
+}
+export async function completeRdActivation(directory, cliVersion) {
+    const update = await pendingUpdate(directory);
+    if (!update?.commandId || update.version !== cliVersion)
+        return;
+    const file = snapshotPath(directory, update.commandId);
+    const contents = await readPrivateRdFile(file);
+    if (contents === null)
+        return;
+    const saved = JSON.parse(contents);
+    if (saved.commandId !== update.commandId || saved.targetVersion !== update.version || saved.releaseSha512 !== update.releaseSha512 || !saved.activatedSha256)
+        return;
+    const active = await readPrivateRdFile(path.join(directory, 'rd', 'state.json'), 32768);
+    if (active === null || rdStateDigest(active) !== saved.activatedSha256)
+        return;
+    await writePrivate(file, JSON.stringify({ ...saved, activatedIdentity: await stateIdentity(directory) }));
+}
+export async function authenticatedRdActivation(directory, guard) {
+    const update = await pendingUpdate(directory);
+    if (update?.phase !== 'SUCCEEDED' || update.commandId !== guard.commandId || update.version !== guard.targetVersion || update.releaseSha512 !== guard.releaseSha512)
+        return false;
+    const contents = await readPrivateRdFile(path.join(directory, 'update', 'restart-ready.json'));
+    if (contents === null)
+        return false;
+    const marker = JSON.parse(contents);
+    return marker.commandId === guard.commandId && marker.version === guard.targetVersion && typeof marker.generation === 'string' && marker.generation.length > 0;
+}
+export async function restoreRdAfterRollback(reference, commandId, targetVersion) {
+    const directory = reference.directory;
+    if (reference.snapshot !== snapshotPath(directory, commandId))
+        throw new Error('RD rollback snapshot path does not match this update');
+    await withPrivateLock(path.join(directory, 'rd', 'install'), async () => {
+        const update = await pendingUpdate(directory);
+        if (update?.commandId !== commandId || update.version !== targetVersion)
+            return;
+        const contents = await readPrivateRdFile(reference.snapshot);
+        if (contents === null)
+            throw new Error('RD rollback snapshot is missing');
+        const saved = JSON.parse(contents);
+        if (saved.schemaVersion !== 1 || saved.commandId !== commandId || saved.targetVersion !== targetVersion || saved.releaseSha512 !== update.releaseSha512)
+            throw new Error('RD rollback snapshot belongs to another CLI update');
+        if (!saved.activatedSha256)
+            return;
+        const active = await readPrivateRdFile(path.join(directory, 'rd', 'state.json'), 32768);
+        if (active === null || rdStateDigest(active) !== saved.activatedSha256)
+            return;
+        if (saved.activatedIdentity && await stateIdentity(directory) !== saved.activatedIdentity)
+            return;
+        if (saved.previous === null)
+            throw new Error('RD activation has no previous state to restore');
+        await writePrivate(path.join(directory, 'rd', 'state.json'), saved.previous);
+    });
+}

package/dist/workstation/update/runUpdate.js

@@ -124,7 +124,7 @@ export function lifecyclePolicy(lifecycle) {
 export function createUpdateCoordinator(deps) {
     const policy = lifecyclePolicy(deps.serviceLifecycle);
     const updateContext = updateServiceContext(deps.dir);
-    const npm = new NpmInstaller(updateContext);
+    const npm = new NpmInstaller({ ...updateContext, installationLockHeld: deps.installationLockHeld });
     // This cache also resumes the restart handshake after service supervision starts a new daemon.
     const releaseCache = new LastKnownGoodCache({
         ...updateContext, runningVersion: CLIENT_VERSION, pack: (root, destination) => npm.pack(root, destination),
@@ -180,7 +180,8 @@ export function createUpdateCoordinator(deps) {
             const log = openSync(`${deps.dir}/daemon.log`, 'a');
             let child;
             try {
-                child = spawn(process.execPath, [deps.cliPath, ...PROVISION_SERVICE_ARGV], {
+                child = spawn(updateContext.nodePath, [deps.cliPath, ...PROVISION_SERVICE_ARGV], {
+                    ...(updateContext.env ? { env: updateContext.env } : {}),
                     detached: true,
                     stdio: ['ignore', log, log],
                 });

package/dist/workstation/update/taskRegistry.js

@@ -10,6 +10,14 @@ export class TaskRegistry {
     idleWaiters = new Set();
     stopping = null;
     accepting = true;
+    /** Keeper-terminal execs also counted in `activeShellTasks` right now (see {@link countKeeperExec}). */
+    keeperExecsCounted = 0;
+    /**
+     * Work owned by another process that a daemon restart would interrupt (the files host's in-progress uploads plus
+     * running media encodes), sampled **now** on every snapshot — never an edge counter. Its owner calls
+     * [externalActivityChanged] when the level may have dropped, so a drain waiting on it wakes.
+     */
+    externalActivity = () => 0;
     /**
      * 忙碌是**现在采出来的**，不是攒出来的。
      *
@@ -24,6 +32,11 @@ export class TaskRegistry {
     snapshot() {
         const activeAgentRefs = new Set();
         for (const [sessionRef, session] of this.agentSessions) {
+            // Spec §8.2: `activeAgentTasks` counts only agent work a daemon restart would cut. A keeper-hosted (durable) session is not
+            // such work — its turn goes on in keeper-acp and the next daemon adopts it — so a busy one neither holds a graceful drain nor
+            // blocks an automatic patch. Fallback sessions (in this process) and in-flight open reservations are counted.
+            if (session.durable)
+                continue;
             // 一个抛异常的采样器不得让心跳和更新准入一起垮掉；读不出来就当它不主张忙碌，
             // 与未知 vendor 值的处置同一条推理。
             let busy = false;
@@ -38,7 +51,16 @@ export class TaskRegistry {
         }
         for (const sessionRef of this.agentOpenReservations.keys())
             activeAgentRefs.add(sessionRef);
-        return { activeShellTasks: this.shellTasks.size, activeAgentTasks: activeAgentRefs.size };
+        let external = 0;
+        // Same rule as the session sampler above: a failing sampler claims nothing rather than taking the heartbeat down.
+        try {
+            const sampled = this.externalActivity();
+            external = Number.isSafeInteger(sampled) && sampled > 0 ? sampled : 0;
+        }
+        catch {
+            external = 0;
+        }
+        return { activeShellTasks: this.shellTasks.size + external, activeAgentTasks: activeAgentRefs.size };
     }
     canUpdate() {
         const snapshot = this.snapshot();
@@ -79,7 +101,11 @@ export class TaskRegistry {
         for (const waiter of [...this.idleWaiters])
             waiter();
     }
-    /** Run one computer task under an abort signal which force-update owns. The method name preserves old callers. */
+    /**
+     * Run one computer task under an abort signal which force-update owns. The method name preserves old callers.
+     * `release()` stops counting the task before it ends (work a daemon restart would no longer interrupt, spec §8.2): from then on it
+     * is not in `activeShellTasks`, a drain does not wait for it and `stopAll()` does not abort it. Idempotent.
+     */
     async withShellTask(run) {
         if (!this.accepting)
             throw new Error('Workstation is not accepting new work');
@@ -87,18 +113,61 @@ export class TaskRegistry {
         let complete;
         const cleanedUp = new Promise((resolve) => { complete = resolve; });
         this.shellTasks.set(controller, cleanedUp);
+        let counted = true;
+        const release = () => {
+            if (!counted)
+                return;
+            counted = false;
+            this.shellTasks.delete(controller);
+            complete();
+            this.notifyIfIdle();
+        };
         try {
-            return await run(controller.signal);
+            return await run(controller.signal, release);
         }
         finally {
+            release();
+        }
+    }
+    /**
+     * Counts a short window of work in `activeShellTasks` WITHOUT the admission gate and without being stoppable: a drain (graceful
+     * or forced) waits for it, nothing aborts it. For work admitted while draining that a restart must not cut in half (a wire v5
+     * exec between `exec.start` and its first checkpoint, spec §8.2). Returns the release (idempotent).
+     */
+    holdShellTask() {
+        const controller = new AbortController();
+        let complete;
+        this.shellTasks.set(controller, new Promise((resolve) => { complete = resolve; }));
+        let held = true;
+        return () => {
+            if (!held)
+                return;
+            held = false;
             this.shellTasks.delete(controller);
             complete();
             this.notifyIfIdle();
-        }
+        };
     }
-    /** Register a live native agent for force-stop, plus how to ask whether it is busy right now. */
-    registerAgentSession(sessionRef, close, busy) {
-        this.agentSessions.set(sessionRef, { close, busy });
+    /**
+     * Marks one exec that runs in keeper-terminal AND is counted in `activeShellTasks` right now — a wire ≤ 4 exec (a shell task for
+     * its whole run) or a wire v5 exec before its first checkpoint (held). keeper-terminal's `execRunning` counts it too: the heartbeat
+     * reports this number (`execCounted`) so the Workstations page does not count it twice (final review minor 7). Returns the
+     * release (idempotent).
+     */
+    countKeeperExec() {
+        this.keeperExecsCounted += 1;
+        let counted = true;
+        return () => { if (!counted)
+            return; counted = false; this.keeperExecsCounted -= 1; };
+    }
+    /** How many keeper-terminal execs `activeShellTasks` includes now (see {@link countKeeperExec}). */
+    get countedKeeperExecs() { return this.keeperExecsCounted; }
+    /**
+     * Register a live native agent for force-stop, plus how to ask whether it is busy right now. A durable session's `close` must be
+     * its detach (see {@link AgentSessionRegistration}).
+     */
+    registerAgentSession(sessionRef, close, busy, registration = {}) {
+        this.agentSessions.set(sessionRef, { close, busy, durable: registration.durable === true });
     }
     /**
      * 采样式判据没有"变空闲"这个事件可以挂钩，所以持有者在可能变空闲时喊一声。
@@ -107,6 +176,10 @@ export class TaskRegistry {
     sessionBusyChanged() {
         this.notifyIfIdle();
     }
+    /** The external activity level may have changed (see [externalActivity]). */
+    externalActivityChanged() {
+        this.notifyIfIdle();
+    }
     /** Atomically admits and counts an asynchronous open before any journal or subprocess await. */
     tryReserveAgentOpen(sessionRef) {
         if (!this.accepting)
@@ -126,6 +199,10 @@ export class TaskRegistry {
     isForceStopping() {
         return this.stopping !== null;
     }
+    /** Whether `sessionRef` is registered as a keeper-hosted (durable) session: a force stop leaves it admitted (see {@link stopAll}). */
+    isDurableSession(sessionRef) {
+        return this.agentSessions.get(sessionRef)?.durable === true;
+    }
     unregisterAgentSession(sessionRef) {
         this.agentSessions.delete(sessionRef);
         this.notifyIfIdle();
@@ -134,12 +211,29 @@ export class TaskRegistry {
      * 排干期间拒收新回合。**只管准入**——它不再登记任何东西，忙碌由 [snapshot] 现场采样。
      * 这两件事以前挤在一个方法里，删计数时极易把准入一起删掉，那会让 drain 期间照收新活。
      */
-    tryAdmitTurn(_sessionRef) {
-        return this.accepting;
+    tryAdmitTurn(sessionRef) {
+        // Spec §8.2: a keeper-hosted session's prompt is admitted while draining — it enters keeper-acp's log first and a restart
+        // continues it; a fallback session's would be cut by the restart.
+        return this.accepting || this.agentSessions.get(sessionRef)?.durable === true;
+    }
+    /**
+     * The restart path of an update (Task 21, spec §5.5.5): every durable session is detached (its registered close), so the next daemon
+     * adopts it with a head checkpoint; fallback sessions are left as they are (they end with this process, their outboxes kept).
+     * Bounded by `timeoutMs`: a restart never waits on a session longer than that. All are attempted even when one fails.
+     */
+    async detachDurableSessions(timeoutMs = 5_000) {
+        const durable = [...this.agentSessions.values()].filter((session) => session.durable);
+        const all = Promise.allSettled(durable.map(async (session) => session.close()));
+        let timer;
+        await Promise.race([all, new Promise((resolve) => { timer = setTimeout(resolve, timeoutMs); })]);
+        clearTimeout(timer);
     }
     /**
      * Atomically refuse future work, signal every shell process group through its owning executor,
-     * and close every native agent. All closes are attempted even when one bridge fails.
+     * and close every native agent that runs in this process. A durable (keeper-hosted) session is left alone: it stays registered,
+     * attached and admitted (spec §8.2, the same as a graceful drain) — the restart path detaches it right before the hand-off
+     * ({@link detachDurableSessions}), and a forced update that fails before that leaves it exactly as it was. All closes are
+     * attempted even when one bridge fails.
      */
     async stopAll() {
         if (this.stopping)
@@ -154,7 +248,7 @@ export class TaskRegistry {
             this.agentOpenReservations.clear();
             this.notifyIfIdle();
             const [outcomes] = await Promise.all([
-                Promise.allSettled([...this.agentSessions.values()].map(async (session) => session.close())),
+                Promise.allSettled([...this.agentSessions.values()].filter((session) => !session.durable).map(async (session) => session.close())),
                 Promise.all(shells.map(([, cleanedUp]) => cleanedUp)),
             ]);
             const failures = outcomes.filter((outcome) => outcome.status === 'rejected');