summrise-agent 1.2.462 → 1.2.464

package/bin/summrise.js

@@ -70,10 +70,12 @@ exports.sha256File = sha256File;
 exports.resolveComponent = resolveComponent;
 exports.ensureElectron = ensureElectron;
 exports.statusReport = statusReport;
+exports.updateWouldNotMove = updateWouldNotMove;
 exports.isBehind = isBehind;
 exports.behindBy = behindBy;
 exports.updateReceiptPs = updateReceiptPs;
 exports.updateBusyPath = updateBusyPath;
+exports.busyMarkerPs = busyMarkerPs;
 exports.awaitReleaseMarker = awaitReleaseMarker;
 exports.releaseMarkerVerdict = releaseMarkerVerdict;
 exports.boxedVersions = boxedVersions;
@@ -353,8 +355,8 @@ function desktopStartPs(installQ) {
         "if (Get-Process electron -ErrorAction SilentlyContinue) { Write-Output 'already-running'; exit 0 }",
         "# DO NOT RE-REGISTER THE TASK TO START IT. Register-ScheduledTask needs the interactive",
         "# user's principal as DOMAIN\\user, and a shell running as a service account has no such",
-        "# mapping -- the device answered \"No mapping between account names and security IDs was",
-        "# done ... UserId\" from a PTY running as systemprofile, while the task itself was Ready.",
+        '# mapping -- the device answered "No mapping between account names and security IDs was',
+        '# done ... UserId" from a PTY running as systemprofile, while the task itself was Ready.',
         "# The task already carries the right principal -- `summrise setup` creates it -- so starting",
         "# it is all that is needed.",
         "$t = Get-ScheduledTask -TaskName SummriseDesktop -ErrorAction SilentlyContinue",
@@ -421,7 +423,12 @@ function parseTargetArg(arg) {
     const port = Number(m[2]);
     if (!Number.isInteger(port) || port < 1 || port > 65535)
         return null;
-    return { host: m[1], port, path: m[3] || "", id: `${m[1]}:${port}${m[3] || ""}` };
+    return {
+        host: m[1],
+        port,
+        path: m[3] || "",
+        id: `${m[1]}:${port}${m[3] || ""}`,
+    };
 }
 /**
  * JSON that survives the command line.
@@ -443,16 +450,31 @@ function deviceApi(method, pathname, body) {
     const dir = ETC_DIR;
     const token = deviceToken(dir);
     if (!token)
-        return { ok: false, error: "no device token in " + path.join(dir, "config.yaml") };
+        return {
+            ok: false,
+            error: "no device token in " + path.join(dir, "config.yaml"),
+        };
     const port = agentPort(dir);
-    const args = ["-sS", "-m", "15", "-X", method, "-H", "Authorization: Bearer " + token];
+    const args = [
+        "-sS",
+        "-m",
+        "15",
+        "-X",
+        method,
+        "-H",
+        "Authorization: Bearer " + token,
+    ];
     if (body !== undefined) {
         args.push("-H", "content-type: application/json", "-d", asciiJson(body));
     }
     args.push(`http://127.0.0.1:${port}${pathname}`);
     const r = (0, child_process_1.spawnSync)("curl", args, { encoding: "utf8", timeout: 20000 });
     if (r.error || r.status !== 0) {
-        return { ok: false, error: `device unreachable on 127.0.0.1:${port}` + (r.error ? ` (${r.error.message})` : "") };
+        return {
+            ok: false,
+            error: `device unreachable on 127.0.0.1:${port}` +
+                (r.error ? ` (${r.error.message})` : ""),
+        };
     }
     try {
         return { ok: true, body: JSON.parse(String(r.stdout || "").trim()) };
@@ -461,21 +483,15 @@ function deviceApi(method, pathname, body) {
         return { ok: false, error: "device sent something that is not JSON" };
     }
 }
-// `4m`, `1h 04m`, `2d 4h` — the shapes the rest of the panel uses.
-// `summrise report` — ONE block an operator can paste into a ticket, a chat or a
-// handover note, assembled from data the device already serves.
-//
-// WHY IT IS A COMMAND AND NOT A SENTENCE IN THE DOCS. Everything here exists on the
-// device: the release it runs, how long the agent has been up, what the previous boot
-// looked like, CPU/memory, the sessions open, and every watched target with its
-// outages. What was missing is a shape a person can hand to somebody else — the
-// numbers are the same, the ASSEMBLY is the feature.
-//
-// THE RENDER IS PURE (`reportText`) and the fetching is three lines of `deviceApi`, so
-// the format is testable without a device. Two rules it keeps: a server that did not
-// answer is printed as NOT READ, never as an invented value; and a target that is down
-// brings its outage log with it, because "it is down" without "since when, and how
-// often" is the half of the answer that starts an argument.
+/**
+ * A duration in the shapes the rest of the panel uses: `45s`, `4m`, `1h 04m`, `2d 4h`.
+ *
+ * IT USED TO CARRY FOURTEEN LINES ABOUT `summrise report`, a verb pruned in round 25 — including "THE
+ * RENDER IS PURE (`reportText`)", naming a function that occurs nowhere else in this file. The doc
+ * described a command an operator cannot run, on a function whose actual job went unsaid. Two rules from
+ * that block are worth keeping, and this is not the place they belong: a server that did not answer is
+ * printed as NOT READ, never as an invented value, and a target that is down brings its outage log.
+ */
 function fmtDuration(ms) {
     const s = Math.max(0, Math.floor(Number(ms || 0) / 1000));
     if (s < 60)
@@ -483,7 +499,9 @@ function fmtDuration(ms) {
     if (s < 3600)
         return `${Math.floor(s / 60)}m`;
     const h = Math.floor(s / 3600);
-    return h >= 24 ? `${Math.floor(h / 24)}d ${h % 24}h` : `${h}h ${String(Math.floor((s % 3600) / 60)).padStart(2, "0")}m`;
+    return h >= 24
+        ? `${Math.floor(h / 24)}d ${h % 24}h`
+        : `${h}h ${String(Math.floor((s % 3600) / 60)).padStart(2, "0")}m`;
 }
 function targetLine(t, nowMs, width = 30) {
     const s = t.summary || {};
@@ -491,19 +509,27 @@ function targetLine(t, nowMs, width = 30) {
     const state = up ? "up" : s.up_now === false ? "down" : "no readings";
     const id = String(t.id || "");
     const since = s.since_ms ? ` ${fmtDuration(nowMs - s.since_ms)}` : "";
-    const status = s.last_status === null || s.last_status === undefined ? "" : `  HTTP ${s.last_status}`;
+    const status = s.last_status === null || s.last_status === undefined
+        ? ""
+        : `  HTTP ${s.last_status}`;
     // A content check that did not find its text is the case a status code cannot express, so it
     // is printed as its own word next to the code.
-    const match = s.last_expect_ok === false ? "  no match" : s.last_expect_ok === true ? "  matches" : "";
+    const match = s.last_expect_ok === false
+        ? "  no match"
+        : s.last_expect_ok === true
+            ? "  matches"
+            : "";
     const lat = s.latency ? `  ${s.latency.avg}ms avg` : "";
     const pct = s.up_pct === null || s.up_pct === undefined ? "" : `  ${s.up_pct}% up`;
-    const drops = s.drops ? `  ${s.drops} ${s.drops === 1 ? "drop" : "drops"}` : "";
+    const drops = s.drops
+        ? `  ${s.drops} ${s.drops === 1 ? "drop" : "drops"}`
+        : "";
     // The operator's own words belong on the line they explain, not in a separate view.
     const note = t.note && t.note.text ? `  — ${t.note.text}` : "";
     return `${up ? "UP  " : s.up_now === false ? "DOWN" : "?   "} ${id.padEnd(width)} ${state}${since}${status}${match}${lat}${pct}${drops}${note}`;
 }
 // ── MACHINE-READABLE OUTPUT ────────────────────────────────────────────────
-// `summrise monitor list --json` and `summrise watch --once --json` print the DEVICE'S OWN ANSWER,
+// `summrise monitor list --json` prints the DEVICE'S OWN ANSWER,
 // projected rather than re-derived: the summaries, the transitions and the samples are the ones
 // `/api/monitors` returns, so a script and the panel (and the AI) can never disagree about whether
 // a target is up. The CLI adds only what the device cannot know — which device answered, and when
@@ -528,13 +554,23 @@ function monitorsJson({ device, askedAtMs, payload, only }) {
         // The device's numbers, verbatim. `up: null` means "not read yet" and is NOT false.
         up: t.summary && t.summary.up_now !== undefined ? t.summary.up_now : null,
         up_pct: t.summary && t.summary.up_pct !== undefined ? t.summary.up_pct : null,
-        since_ms: t.summary && t.summary.since_ms !== undefined ? t.summary.since_ms : null,
+        since_ms: t.summary && t.summary.since_ms !== undefined
+            ? t.summary.since_ms
+            : null,
         drops: t.summary && t.summary.drops !== undefined ? t.summary.drops : null,
         latency_ms: t.summary && t.summary.latency ? t.summary.latency.avg : null,
-        last_status: t.summary && t.summary.last_status !== undefined ? t.summary.last_status : null,
-        last_expect_ok: t.summary && t.summary.last_expect_ok !== undefined ? t.summary.last_expect_ok : null,
+        last_status: t.summary && t.summary.last_status !== undefined
+            ? t.summary.last_status
+            : null,
+        last_expect_ok: t.summary && t.summary.last_expect_ok !== undefined
+            ? t.summary.last_expect_ok
+            : null,
         probes: t.summary && t.summary.probes !== undefined ? t.summary.probes : null,
-        transitions: (t.transitions || []).map((x) => ({ at_ms: x.at_ms, up: x.up, lasted_ms: x.lasted_ms })),
+        transitions: (t.transitions || []).map((x) => ({
+            at_ms: x.at_ms,
+            up: x.up,
+            lasted_ms: x.lasted_ms,
+        })),
     }));
     return {
         device: device || "",
@@ -919,6 +955,13 @@ function sha256File(p) {
  *
  * `null` when neither source works: every component here is optional to the
  * AGENT, and a failed fetch must not fail the install.
+ *
+ * THE FIRST ARM IS A SEAM, NOT A LIVE PATH — measured, because a reader deserves to know which: no
+ * component is in `package.json`'s `files[]` or in `required-in-tgz.txt`, and `tar tzf` on the published
+ * tarball confirms none of the three is there. So today the release host is the ONLY source, and the
+ * `existsSync` above exists so that a future release which DOES box one gets it from the package without
+ * touching this function. The test beside it pins the fact, so boxing one is a deliberate act that also
+ * updates this sentence.
  */
 function resolveComponent(name, pkgPath) {
     if (fs.existsSync(pkgPath))
@@ -1069,9 +1112,22 @@ function statusReport(f) {
  *  sentence's truthiness — where "0 releases" and "-1 releases" are both TRUTHY, so it would have refused every update,
  *  including the correct one. Caught by asking the artefact before shipping it. */
 function versionTriple(v) {
-    const t = String(v || "").split(".").map(Number);
+    const t = String(v || "")
+        .split(".")
+        .map(Number);
     return t.length === 3 && t.every((n) => Number.isFinite(n)) ? t : null;
 }
+/** WOULD THIS UPDATE MOVE THE DEVICE AT ALL? The parity fact, and it needs NO NETWORK: the CLI stamps
+ *  `<install>/.summrise-release` with ITS OWN version, and the device's `agent_update` reads that file as
+ *  the local version — so when the device is already on the version this CLI carries, the stamp equals
+ *  what is there, the swap installs the same build, and nothing moves. That is round 201's measured
+ *  defect ("update requested 1.2.438 -> 1.2.438", "copy ok=True", release unchanged), which is why the
+ *  guard below exists at all. THE GUARD THAT EXISTS CANNOT SEE IT: it compares the CLI against the
+ *  RELEASE CHANNEL, and when the CDN is unreadable `latest` is empty and the whole check is skipped, so a
+ *  network blip re-opens the defect. This one compares two facts already on the machine. */
+function updateWouldNotMove(fromVersion, selfVersion) {
+    return Boolean(fromVersion) && fromVersion === selfVersion;
+}
 /** Is `latest` ahead of `device` on the SAME release line? */
 function isBehind(device, latest) {
     const a = versionTriple(device);
@@ -1131,6 +1187,21 @@ function updateReceiptPs(dataDirQ, fromVersion, toVersion) {
 function updateBusyPath() {
     return path.join(process.env.ProgramData || "C:\\ProgramData", "SummriseAgent", "update-busy");
 }
+/**
+ * The SAME marker as the PowerShell text the swap script embeds, DERIVED from `updateBusyPath()` rather
+ * than written out by hand — which is what this file did, three times, inside the generated script. The
+ * agent fixed exactly this on its own side and says why (tools.rs, above BUSY_MARKER_REL): "It used to be
+ * spelled out TWICE: the Rust acquirer built <ProgramData>\SummriseAgent\update-busy from PathBuf joins
+ * while the generated PowerShell swap script carried the same location as two hand-written string
+ * literals. A drift between the two is invisible until an update actually runs — and then the swap
+ * releases a file the agent never created, the marker survives, and every later update is refused for up
+ * to an hour." The CLI's own doc above claims ONE owner for this path; this is what makes that true.
+ */
+function busyMarkerPs() {
+    const root = process.env.ProgramData || "C:\\ProgramData";
+    const rel = path.relative(root, updateBusyPath()).split(path.sep).join("\\");
+    return `(Join-Path $env:ProgramData '${rel}')`;
+}
 /**
  * Poll `etc\.summrise-release` until it shows `want`, or the budget expires.
  *
@@ -1167,11 +1238,17 @@ async function awaitReleaseMarker(o) {
  * misreporting its own version and refusing the update that would fix it.
  */
 function releaseMarkerVerdict(c) {
+    // WHOSE FAILURE IS THIS? The message is printed by TWO callers — `rollback`, which staged a release in
+    // order to PIN it, and `update`, which staged one to INSTALL it — and it said "rollback:" with
+    // "re-run `summrise rollback <want>`" for both. On the update path that advice is worse than useless:
+    // it names the version that just failed to install, so following it asks the device to pin a release
+    // it is not running. The verb decides the sentence now.
+    const verb = c.verb ?? "rollback";
     if (c.ok) {
         return {
             writePin: true,
             exitCode: 0,
-            message: `rollback: pinned to ${c.want} -- auto-upgrade refused until 'summrise rollback --clear' or a forced agent_update`,
+            message: `${verb}: pinned to ${c.want} -- auto-upgrade refused until 'summrise rollback --clear' or a forced agent_update`,
         };
     }
     return {
@@ -1181,12 +1258,17 @@ function releaseMarkerVerdict(c) {
         // failed, or it is still running (it kills and restarts the agent), or the marker
         // could not be read at all — and `saw === null` is the weakest of the three. The old
         // wording asserted "the swap did NOT take" for all of them.
-        message: `rollback: no release marker showing ${c.want} within ${Number.isFinite(c.waitedMs)
+        message: `${verb}: no release marker showing ${c.want} within ${Number.isFinite(c.waitedMs)
             ? Math.round(c.waitedMs / 1000) + "s"
             : "the read-back window"} ` +
             `(last read: ${c.saw ?? "empty or unreadable"}). ` +
             `NOT pinned (a pin would claim a version this device may not be running) and no release ` +
-            `marker written. Check the update log and \`summrise status\`, then re-run 'summrise rollback ${c.want}'.`,
+            `marker written. ` +
+            (verb === "update"
+                ? `Check the update log and \`summrise status\`, then re-run \`summrise update\`. If it fails ` +
+                    `the same way, \`summrise rollback ${c.from ?? "<the version it was on>"}\` pins the release ` +
+                    `this device is ACTUALLY running — which is not the one that failed to install.`
+                : `Check the update log and \`summrise status\`, then re-run 'summrise rollback ${c.want}'.`),
     };
 }
 function boxedVersions(installDir, pkgDir) {
@@ -1367,6 +1449,28 @@ function svc(action) {
     // silent either way. `autostart` already checks; this is the same pattern.
     return sh(`schtasks /${action} /TN ${TASK}`, { stdio: "inherit" });
 }
+/**
+ * The scheduled task's State (`Running`, `Ready`, `Disabled`, …) or **null when it could not be read**.
+ *
+ * THREE STATES, NOT ONE. `autostart` states the rule and names the shape — "a failed READ reported as
+ * evidence of ABSENCE" — which it calls the THIRD instance, after `statusReport` and `rollback status`.
+ * Here `null` means "I could not ask", and callers report that as itself instead of as a verdict.
+ *
+ * `LOCALE` is why this asks `Get-ScheduledTask` rather than parsing `schtasks /Query`: the latter's headers
+ * are localized, which is the reason `autostart` uses this call too.
+ */
+function taskState(name) {
+    const r = (0, child_process_1.spawnSync)("powershell", [
+        "-NoProfile",
+        "-Command",
+        `(Get-ScheduledTask -TaskName '${name}' -ErrorAction SilentlyContinue | Select-Object -ExpandProperty State)`,
+    ], { encoding: "utf8" });
+    const err = r && r.error;
+    if (!r || err || r.status !== 0)
+        return null; // spawn failed, or the read itself failed
+    const s = String(r.stdout || "").trim();
+    return s === "" ? null : s; // empty = the task is not there, which is also "no answer to Running?"
+}
 // Shared tunnel bootstrap: login (token or interactive) → create tunnel →
 // DNS route → write tunnel.yml. Used by `summrise setup --tunnel` and
 // `summrise tunnel install`.
@@ -1375,7 +1479,12 @@ function initTunnel(hostname, regKey) {
     const cfg = path.join(ETC_DIR, "tunnel.yml");
     if (!fs.existsSync(cf)) {
         console.error("tunnel: cloudflared.exe not staged at", cf);
-        console.error("  reinstall the package (npm i -g summrise-agent) to stage it.");
+        // NOT "REINSTALL THE PACKAGE". The npm package carries NO boxed components BY DESIGN (that is what
+        // keeps it ~6.7 MB), so a reinstall cannot stage this and the advice sent the operator in a circle.
+        // `setup` is what stages it: resolveComponent fetches it from the RELEASE HOST and the agent's own
+        // sha256 pin checks it again on the path it uses. Its doc records what this costs when nobody does —
+        // "a device with no tunnel is INVISIBLE TO THE CONSOLE while looking perfectly healthy from inside."
+        console.error("  run 'summrise setup' to stage it -- the component comes from the release host, not from the npm package.");
         process.exit(1);
     }
     const host = hostname || "d1.agent.saisi.online";
@@ -1613,7 +1722,13 @@ const commands = {
         // `regOk` is collected here and summarised at the end of setup: best-effort, but the
         // operator should be told once, with the consequence, rather than not at all.
         regOk.push(regWrite("InstallDir", DIR));
-        regOk.push(regWrite("DataDir", path.join(process.env.ProgramData || "C:\\ProgramData", "Summrise")));
+        // ...AND ECHO THE RESOLVED ONE, NOT THE DEFAULT. `resolveDataDir()` is registry-first and
+        // `DATA_DIR` is its answer, so a device whose data dir was remapped has that path here. This used to
+        // WRITE THE LITERAL DEFAULT back to the registry — while the tree below was created at `DATA_DIR` —
+        // so the new tree landed at the remapped path and the registry then named the default, which is the
+        // path the AGENT reads. The comment two lines up says "DataDir defaults to %ProgramData%\Summrise",
+        // i.e. exactly what the code did not do: a default applies when nothing is set, not over a remap.
+        regOk.push(regWrite("DataDir", DATA_DIR));
         // Pre-create the data dir tree (sessions/memory/logs — C1 separation).
         const DATA = DATA_DIR;
         for (const sub of ["sessions", "memory", "logs"]) {
@@ -1760,7 +1875,10 @@ const commands = {
         // shims rather than hand-written ones; when npm cannot, say the command.
         {
             const selfVer = String(require("../package.json").version || "");
-            const pfx = (0, child_process_1.spawnSync)("npm", ["prefix", "-g"], { encoding: "utf8", shell: true });
+            const pfx = (0, child_process_1.spawnSync)("npm", ["prefix", "-g"], {
+                encoding: "utf8",
+                shell: true,
+            });
             const pre = pfx.status === 0 ? String(pfx.stdout || "").trim() : "";
             if (selfVer && pre) {
                 const inst = (0, child_process_1.spawnSync)("npm", [
@@ -1793,12 +1911,25 @@ const commands = {
         try {
             const reg = path.join(SCRIPTS_DIR, "register-desktop-task.ps1");
             fs.writeFileSync(reg, desktopTaskPs(DIR).join("\r\n") + "\r\n");
-            sh(
-            // DOUBLE quotes — a cmd-layer argument. The single-quoted version this shipped with
-            // reached PowerShell with the quotes included and died on the device with "unsupported
-            // path format" for a path that was perfectly valid.
-            `powershell -NoProfile -ExecutionPolicy Bypass -File "${reg}"`);
-            console.log("setup: SummriseDesktop registered (logon + a 5-minute watchdog) and started");
+            // THE STATUS WAS DISCARDED AND THE SUCCESS LINE WAS UNCONDITIONAL, which is the defect the AGENT
+            // task's check ten lines below names in its own comment: "audit #7: used to claim success
+            // regardless". Worse, the `catch` below could not fire for this — `sh()` RETURNS, it does not
+            // throw — so the only thing it ever caught was `writeFileSync`.
+            //
+            // ONE CALL, and its status is READ. DOUBLE quotes in the command: a cmd-layer argument, because the
+            // single-quoted version this shipped with reached PowerShell with the quotes included and died on
+            // the device with "unsupported path format" for a path that was perfectly valid.
+            //
+            // A WARNING, NOT FATAL, unlike the agent task: headless installs have no SummriseDesktop, and the
+            // registration script itself exits quietly when electron is already alive.
+            const reg302 = sh(`powershell -NoProfile -ExecutionPolicy Bypass -File "${reg}"`, { stdio: "pipe" });
+            if (reg302 && reg302.status === 0) {
+                console.log("setup: SummriseDesktop registered (logon + a 5-minute watchdog) and started");
+            }
+            else {
+                console.log(`setup: WARNING -- registering SummriseDesktop failed (status ${reg302 ? reg302.status : "spawn error"}); ` +
+                    `run: powershell -File "${SCRIPTS_DIR}\\register-desktop-task.ps1"`);
+            }
         }
         catch {
             console.log(`setup: WARNING -- could not register SummriseDesktop; run: powershell -File "${SCRIPTS_DIR}\\register-desktop-task.ps1"`);
@@ -1890,10 +2021,10 @@ const commands = {
             console.log("setup: no tunnel configured (local mode). Enable later with `summrise tunnel install <hostname>`.");
         }
     },
-    // ── monitor / watch ─────────────────────────────────────────────────────
+    // ── monitor ────────────────────────────────────────────────────────────
     // The device's reachability instrument, in the terminal the operator already
     // works in. The panel draws the same numbers; this runs where the ssh session
-    // is, needs no browser, and `summrise watch` keeps it live on screen.
+    // is, needs no browser, and runs its live view until Ctrl+C.
     // async: `wait` blocks on probes (the dispatcher already awaits every command).
     async monitor(args) {
         const sub = String(args[0] || "list").toLowerCase();
@@ -1903,7 +2034,7 @@ const commands = {
         const expect = expectAt >= 0 ? String(args[expectAt + 1] || "") : "";
         const positional = args.filter((a, i) => i > 0 && a !== "--expect" && i !== expectAt + 1);
         if (expectAt >= 0 && !expect) {
-            console.error("usage: summrise monitor add <host:port[/path]> --expect \"<text>\"");
+            console.error('usage: summrise monitor add <host:port[/path]> --expect "<text>"');
             process.exit(1);
         }
         if (sub === "add" || sub === "rm" || sub === "remove") {
@@ -1913,7 +2044,12 @@ const commands = {
                 process.exit(1);
             }
             if (sub === "add") {
-                const r = deviceApi("POST", "/api/monitors/add", { host: t.host, port: t.port, path: t.path, expect });
+                const r = deviceApi("POST", "/api/monitors/add", {
+                    host: t.host,
+                    port: t.port,
+                    path: t.path,
+                    expect,
+                });
                 if (!r.ok) {
                     console.error(`monitor add: ${r.error}`);
                     process.exit(1);
@@ -1934,7 +2070,9 @@ const commands = {
                 console.error(`monitor rm: ${r.error}`);
                 process.exit(1);
             }
-            console.log(r.body && r.body.removed ? `stopped watching ${t.id}` : `monitor rm: ${t.id} was not being watched`);
+            console.log(r.body && r.body.removed
+                ? `stopped watching ${t.id}`
+                : `monitor rm: ${t.id} was not being watched`);
             return;
         }
         if (sub === "probe") {
@@ -1964,7 +2102,10 @@ const commands = {
             const probe = payload.result && payload.result.probe;
             // The device sends the CRITERION with the answer (`expect`), so "no match" can name the
             // text it looked for — an unreadable verdict is a verdict nobody can act on.
-            console.log(probeLine({ id: t.id, expect: (payload.result && payload.result.expect) || null }, probe, Date.now()));
+            console.log(probeLine({
+                id: t.id,
+                expect: (payload.result && payload.result.expect) || null,
+            }, probe, Date.now()));
             return;
         }
         if (sub !== "list") {
@@ -1985,7 +2126,12 @@ const commands = {
             // encoding boundary too. PowerShell decodes a child's output with the console code page
             // (CP936 on d1), so raw UTF-8 through a pipe came back as mojibake while the same text
             // printed directly read fine — the second face of this bug.
-            console.log(asciiJson(monitorsJson({ device: os.hostname(), askedAtMs: Date.now(), payload: r.body, only: null }), 2));
+            console.log(asciiJson(monitorsJson({
+                device: os.hostname(),
+                askedAtMs: Date.now(),
+                payload: r.body,
+                only: null,
+            }), 2));
             return;
         }
         const targets = (r.body && r.body.targets) || [];
@@ -1999,7 +2145,7 @@ const commands = {
         for (const t of targets)
             console.log(targetLine(t, now));
     },
-    // Live view: redraw in place every few seconds until Ctrl+C. `summrise watch
+    // Live view: redraw in place every few seconds until Ctrl+C. `summrise monitor
     // <host:port[/path]>` narrows it to one target and adds its outage log.
     // `summrise desktop` = put the window back, or say it is already there.
     //
@@ -2045,6 +2191,17 @@ const commands = {
         process.exit(1);
     },
     status() {
+        // THE EXIT CODE IS 0 EVEN WHEN THE REPORT SAYS "UNKNOWN", AND THAT IS THE CONVENTION.
+        //
+        // `status` is asked for a REPORT; it produces one, and the verdict lives in the text. `tunnel`
+        // exits 1 on the same unreadable process list (`:3655-3662`) because the thing IT was asked for —
+        // a running tunnel — did not happen. The two are not inconsistent; they answer different
+        // questions, and the difference is what the caller asked for rather than how bad the news is.
+        //
+        // A script that needs a VERDICT must not read this exit code. `monitor list --json` states its own
+        // contract at `:2424-2426`: "A device that could not be reached is a NON-ZERO EXIT with the reason
+        // on stderr, never a JSON body pretending everything is fine."
+        //
         // NOT via shell: `shell: true` concatenates argv into one cmd.exe string,
         // so the unquoted filter "IMAGENAME eq …" was split at its spaces, tasklist
         // rejected it, and this ALWAYS printed STOPPED even with the agent running.
@@ -2109,23 +2266,59 @@ const commands = {
         }
     },
     start() {
-        svc("Run");
+        // CHECK IT, LIKE `stop` DOES. The comment on `svc` above says the return value exists because
+        // discarding it made `start`/`restart` "silent either way" — and two of the four call sites still
+        // discarded it, including this one, which is step 2 of every documented journey. An operator whose
+        // agent never came up got exit 0 and no sentence at all.
+        const r = svc("Run");
+        if (r && r.status !== 0) {
+            console.error(`summrise start: schtasks /Run failed (status ${r.status}) -- the agent is NOT running`);
+            process.exit(1);
+        }
     },
     stop() {
         // Say WHY before the process goes: see markDeliberateStop.
         markDeliberateStop();
         const r = svc("End");
         if (r && r.status !== 0) {
-            console.error(`summrise stop: schtasks /End failed (status ${r.status}) -- the agent may still be running`);
-            process.exit(1);
+            // A NON-ZERO `/End` IS NOT EVIDENCE THE AGENT IS STILL RUNNING, and the mirror of this mistake is
+            // already documented twice in this file. `restart` says it about the identical condition: "a task
+            // that was not running has nothing to end, so a non-zero /End is the ordinary case". `svc`'s own
+            // comment records the ORIGINAL bug, which was the opposite — "`stop` printed 'stopped' and exited 0
+            // for a missing task or an access-denied". So the exit code answers neither question.
+            //
+            // ASK INSTEAD. `autostart` reads `Get-ScheduledTask ... -ExpandProperty State` and its comment names
+            // this exact shape — "a failed READ reported as evidence of ABSENCE" — which it calls the THIRD
+            // instance. This is the fourth, from the other side: an ordinary read taken as evidence of PRESENCE,
+            // with "the agent may still be running" printed for a task that had already stopped.
+            const st = taskState(TASK);
+            if (st === null) {
+                // Could not read it — say that, rather than guessing either way (the three-state rule).
+                console.error(`summrise stop: schtasks /End failed (status ${r.status}) and the task's state could not be read`);
+                process.exit(1);
+            }
+            if (st === "Running") {
+                console.error(`summrise stop: schtasks /End failed (status ${r.status}) and the task is still Running`);
+                process.exit(1);
+            }
+            console.error(`summrise stop: schtasks /End returned ${r.status}, but the task is not Running -- nothing to stop`);
         }
         console.log("stopped -- revives via 'summrise start' or the 5-min watchdog ('summrise autostart off' opts out of autostart)");
     },
     restart() {
         markDeliberateStop();
-        svc("End");
+        // THE STOP IS REPORTED BUT NOT FATAL: a task that was not running has nothing to end, so a non-zero
+        // `/End` is the ordinary case for "restart a stopped agent", and the operator asked for the START.
+        const end = svc("End");
+        if (end && end.status !== 0) {
+            console.error(`summrise restart: schtasks /End failed (status ${end.status}) -- the old process may still be running`);
+        }
         sh("timeout /t 2 >nul");
-        svc("Run");
+        const run = svc("Run");
+        if (run && run.status !== 0) {
+            console.error(`summrise restart: schtasks /Run failed (status ${run.status}) -- the agent is NOT running`);
+            process.exit(1);
+        }
     },
     // Boot switch: `summrise autostart on|off|status` (default status). Flips the
     // ENABLED flag on BOTH boot tasks (service + desktop shell) — this is the
@@ -2225,6 +2418,28 @@ const commands = {
                 "\n    summrise update");
             process.exit(1);
         }
+        // AND THE SAME REFUSAL WITHOUT THE NETWORK. The guard above cannot fire when the CDN is
+        // unreadable, and the defect it exists for is exactly what happens then: an update that stamps the
+        // install with a version it already has, swaps in the same build, and reports success while
+        // `status` keeps saying the device is behind.
+        let deviceNow = "";
+        try {
+            deviceNow = fs
+                .readFileSync(path.join(ETC_DIR, ".summrise-release"), "utf8")
+                .trim();
+        }
+        catch {
+            // No marker is not a no-op; the update below writes one.
+        }
+        if (updateWouldNotMove(deviceNow, selfVersion)) {
+            console.error(`update: this CLI is ${selfVersion} and the device is ALREADY on ${deviceNow}.` +
+                "\n  Updating from here would stamp the device with the version it already has and change nothing," +
+                "\n  because the device reads <install>/.summrise-release (written by this package) as its version." +
+                "\n  If the device is meant to be newer, this CLI is too old to deliver it: install the new one first." +
+                "\n    npm i -g summrise-agent" +
+                "\n    summrise update");
+            process.exit(1);
+        }
         // npm audit #10: no mutual exclusion — two updates (or setup racing a
         // swap) interleave Copy-Item on *.new, leaving a half-written exe "ok".
         // setup REMOVES the marker; update now CREATES it (refuse if <10 min
@@ -2410,7 +2625,7 @@ const commands = {
             // BEFORE touching anything (fail-closed — a config-path argument boots
             // old AND new agents alike, so aborting here leaves the old version
             // running untouched). Without this the moved config strands the boot.
-            `try { ${bootTaskPs(`${q}\\summrise-agent.exe`, `${q}\\etc\\config.yaml`, false).join("; ")} } catch { "[$(Get-Date -Format o)] task repoint FAILED: $($_.Exception.Message)" | ${log}; try { Remove-Item -Force (Join-Path $env:ProgramData 'SummriseAgent\\update-busy') } catch {}; exit 1 }`,
+            `try { ${bootTaskPs(`${q}\\summrise-agent.exe`, `${q}\\etc\\config.yaml`, false).join("; ")} } catch { "[$(Get-Date -Format o)] task repoint FAILED: $($_.Exception.Message)" | ${log}; try { Remove-Item -Force (${busyMarkerPs()}) } catch {}; exit 1 }`,
             `"[$(Get-Date -Format o)] task repointed at etc\\config.yaml" | ${log}`,
             // Layout-v2 migration (ADR 0008): move pre-v2 root paths into their
             // v2 homes. Best-effort per item; the gate below is fail-closed.
@@ -2418,7 +2633,7 @@ const commands = {
             // Fail-closed gate: the new agent reads ONLY the v2 homes. A missing
             // config/hostname here means migration failed — do NOT swap (the old
             // exe keeps running the old layout until the next update).
-            `if ((-not (Test-Path '${q}\\etc\\config.yaml')) -or (-not (Test-Path '${q}\\etc\\summrise-agent.hostname'))) { "[$(Get-Date -Format o)] migration gate FAILED (etc\\config.yaml/hostname missing) -- aborting, old version keeps running" | ${log}; try { Remove-Item -Force (Join-Path $env:ProgramData 'SummriseAgent\\update-busy') } catch {}; exit 1 }`,
+            `if ((-not (Test-Path '${q}\\etc\\config.yaml')) -or (-not (Test-Path '${q}\\etc\\summrise-agent.hostname'))) { "[$(Get-Date -Format o)] migration gate FAILED (etc\\config.yaml/hostname missing) -- aborting, old version keeps running" | ${log}; try { Remove-Item -Force (${busyMarkerPs()}) } catch {}; exit 1 }`,
             // A running exe cannot be overwritten on Windows — stop the service
             // first (task end + process kill), THEN swap with retry.
             "try { Stop-ScheduledTask SummriseAgent -ErrorAction Stop } catch {}",
@@ -2442,7 +2657,7 @@ const commands = {
             // back up (it will run the old exe until the next update).
             `try { Start-ScheduledTask SummriseAgent -ErrorAction Stop } catch { schtasks /Run /TN SummriseAgent }`,
             `"[$(Get-Date -Format o)] task restarted" | ${log}`,
-            `try { Remove-Item -Force (Join-Path $env:ProgramData 'SummriseAgent\\update-busy') } catch {}`,
+            `try { Remove-Item -Force (${busyMarkerPs()}) } catch {}`,
             // Custom-port installs: the firewall rule must track the configured
             // bind port (baked at update time from the live config.yaml — the
             // swap itself runs from a static file and cannot read it).
@@ -2605,7 +2820,14 @@ const commands = {
             sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
             now: () => Date.now(),
         });
-        const verdict = releaseMarkerVerdict({ ...check, want: toVersion });
+        const verdict = releaseMarkerVerdict({
+            ...check,
+            want: toVersion,
+            // THE VERB MATTERS: this is an INSTALL that failed, so the advice names the previous version as
+            // the thing to pin — not the one that just failed to install.
+            verb: "update",
+            from: fromVersion,
+        });
         if (verdict.writePin) {
             console.log(`update: ${fromVersion || "?"} -> ${toVersion} COMPLETE (the device reported the new release)`);
         }
@@ -2878,8 +3100,17 @@ const commands = {
         if (regLeft.status === 0)
             survivors.push("registry key HKLM\\SOFTWARE\\Summrise\\Agent");
         if (survivors.length) {
-            console.log("uninstall: WARNING -- still present after removal:", survivors.join(", "));
-            console.log("uninstall: a locked file or a permission problem; re-run after stopping the agent.");
+            // ONE FAILURE CLASS, ONE TREATMENT. The data-dir twin forty lines below exits 1 for exactly this
+            // ("FAILED to purge the data dir -- … is still present"), and this branch warned and exited 0 —
+            // while the comment directly above states the rule it was breaking: `sh()` discards its result
+            // "at every one of its call sites", so a locked file, an AV hold or a denied HKLM write "produced
+            // 'removed' with the thing still there, AND EXIT 0".
+            //
+            // The program dir and the registry key are what `uninstall` was asked to remove. A warning that
+            // exits 0 is the same false verdict the data-dir branch already refuses.
+            console.error("uninstall: FAILED -- still present after removal:", survivors.join(", "));
+            console.error("uninstall: a locked file or a permission problem; re-run after stopping the agent.");
+            process.exitCode = 1;
         }
         else {
             console.log("uninstall: program dir + registry removed");
@@ -3023,11 +3254,22 @@ const commands = {
 // WITHOUT tripping the usage print + process.exit at module load.
 if (require.main === module) {
     const [cmd, ...rest] = process.argv.slice(2);
+    // `--version` ANSWERS THE CHECK THE INSTALLER'S OWN CHECKLIST MAKES, and it used to fail it. It is not
+    // a verb, so it fell through to the usage branch below, printed the verb list and exited 1 — while
+    // step 4 of `deploy/README-installer.md` BEGINS with "`summrise --version` / the panel opens". A fresh
+    // install that worked therefore reported a failure in the one place the operator is told to look,
+    // which is the same defect as a comment promising more than the code does.
+    if (cmd === "--version" || cmd === "-v" || cmd === "version") {
+        console.log(String(require("../package.json").version || ""));
+        process.exit(0);
+    }
     if (!cmd || !commands[cmd]) {
         // The list is DERIVED from `commands`, so the help cannot promise a verb that was pruned
         // (`report` and `watch` were still advertised after their round-25 removal — a usage line is a
         // contract, and one that lies is worse than none).
-        console.log("summrise <" + Object.keys(commands).join("|") + "> -- Summrise Agent control");
+        console.log("summrise <" +
+            Object.keys(commands).join("|") +
+            "> -- Summrise Agent control");
         Object.keys(commands).forEach((k) => console.log(" ", k));
         process.exit(cmd ? 1 : 0);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "summrise-agent",
-  "version": "1.2.462",
+  "version": "1.2.464",
   "description": "Summrise Agent — Windows device MCP server (terminal/SSH/serial) + panel. Self-hosted npm distribution.",
   "//build": "唯一构建路径：在本目录执行 npm run build。它是自包含的：经 npm exec 按需拉取 typescript@5，无需预装任何 node_modules（干净检出可跑；旧脚本引用 ../summrise-desktop-electron/node_modules/.bin/tsc，干净检出必 ENOENT）。必须用 npm exec --package … -- tsc 的形式：npx 会吃掉传给 tsc 的 -p/--outDir 等参数（round-435：npx 写法从未真正跑通过）。先编 electron TS（--noCheck 纯 emit，与 release.yml 一致）同步两处 src/*.js，再编 src/summrise.ts 到 bin/summrise.js 并校验 round-298 标记（弱 oracle，只证某次构建发生，新鲜性由 publish-release.sh 的 tsc 重编 + cmp 门保证）。",
   "bin": {
@@ -24,7 +24,7 @@
   ],
   "license": "MIT",
   "scripts": {
-    "build": "npm exec --yes --package typescript@5 -- tsc -p ../summrise-desktop-electron/tsconfig.json --outDir /tmp/summrise-electron-fresh --noCheck && cp /tmp/summrise-electron-fresh/main.js ../summrise-desktop-electron/src/main.js && cp /tmp/summrise-electron-fresh/preload.js ../summrise-desktop-electron/src/preload.js && cp /tmp/summrise-electron-fresh/url-policy.js ../summrise-desktop-electron/src/url-policy.js && cp ../summrise-desktop-electron/src/main.js ../summrise-desktop-electron/src/preload.js ../summrise-desktop-electron/src/url-policy.js ./summrise-desktop-electron/src/ && npm exec --yes --package typescript@5 -- tsc -p tsconfig.json --outDir /tmp/summrise-fresh-bin && cp /tmp/summrise-fresh-bin/summrise.js bin/summrise.js && grep -q \"summrise-release\" bin/summrise.js && rm -rf /tmp/summrise-electron-fresh /tmp/summrise-fresh-bin",
+    "build": "npm exec --yes --package typescript@5.9.3 -- tsc -p ../summrise-desktop-electron/tsconfig.json --outDir /tmp/summrise-electron-fresh --noCheck && cp /tmp/summrise-electron-fresh/main.js ../summrise-desktop-electron/src/main.js && cp /tmp/summrise-electron-fresh/preload.js ../summrise-desktop-electron/src/preload.js && cp /tmp/summrise-electron-fresh/url-policy.js ../summrise-desktop-electron/src/url-policy.js && cp ../summrise-desktop-electron/src/main.js ../summrise-desktop-electron/src/preload.js ../summrise-desktop-electron/src/url-policy.js ./summrise-desktop-electron/src/ && npm exec --yes --package typescript@5.9.3 -- tsc -p tsconfig.json --outDir /tmp/summrise-fresh-bin && cp /tmp/summrise-fresh-bin/summrise.js bin/summrise.js && grep -q \"summrise-release\" bin/summrise.js && rm -rf /tmp/summrise-electron-fresh /tmp/summrise-fresh-bin",
     "test": "node --test"
   }
 }