@crewhaus/tool-desktop 0.7.0

package/dist/lib/power.d.ts

@@ -0,0 +1,150 @@
+/**
+ * `PowerAssertion` — keeping a machine awake for a long step, and giving it
+ * back afterwards.
+ *
+ * THE ASSERTION IS THE LIFETIME OF A CHILD PROCESS, NOT A CALL. The tool has
+ * to return while the holder keeps running, which makes three things true
+ * that an ordinary tool never has to think about:
+ *
+ * 1. **A DEADLINE IS MANDATORY, AND THE KERNEL ENFORCES IT.** An unbounded
+ *    inhibitor is a laptop that never sleeps again because a harness crashed
+ *    three days ago. So the bound is not a reaper in this process — a reaper
+ *    dies with the harness that crashed — it is an argument to the holder
+ *    itself. `caffeinate -t <seconds>` exits on its own; `systemd-inhibit …
+ *    sleep <seconds>` releases when `sleep` returns; the PowerShell holder
+ *    parks for a fixed `Start-Sleep`. Kill the whole harness and every one of
+ *    them still ends on time. The result reports `expiresAt` because a
+ *    caller that cannot see when its own inhibitor lapses will hold another.
+ * 2. **A PID IS NOT AN IDENTITY.** Pids are reused, and `release` reading a
+ *    stale state file would otherwise send SIGTERM to whatever now owns that
+ *    number. So the state file records the backend program, and `release` and
+ *    `status` VERIFY the live process's command line before signalling
+ *    anything. A mismatch is reported as `stale` and the file is cleared —
+ *    nothing is killed.
+ * 3. **WINDOWS CANNOT DO THIS IN A ONE-LINER.** `SetThreadExecutionState` is
+ *    THREAD-scoped and its effect dies with the thread, so a PowerShell
+ *    one-liner that sets the flag and exits does precisely nothing — the
+ *    naive port's failure is silent and total. The holder must stay alive
+ *    with the flag set, which is what `Start-Sleep` inside the script is for.
+ *
+ * Nothing here escalates privilege: `caffeinate`, `systemd-inhibit` and
+ * `SetThreadExecutionState` are all available to an ordinary user, and
+ * `run.ts`'s `assertArgv` refuses an escalation program structurally.
+ */
+import type { HostPlatform } from "../host";
+import type { RunRequest } from "../run";
+import { type Unavailable } from "./outcome";
+/** What the assertion covers. `display` also implies `system`. */
+export type AssertionScope = "system" | "display";
+/** The ceiling, and the reason there is one. Eight hours is a working day. */
+export declare const MAX_HOLD_MINUTES = 480;
+export declare const DEFAULT_HOLD_MINUTES = 30;
+/** Where the held assertion is remembered, relative to the workspace root. */
+export declare const STATE_RELATIVE_PATH = ".crewhaus/power-assertion.json";
+export declare const WINDOWS_INHIBIT: import("./escape").PowerShellScript;
+export declare const WINDOWS_PROCESS_PROBE: import("./escape").PowerShellScript;
+/**
+ * The reason string a caller may attach to a Linux inhibitor.
+ *
+ * Printable ASCII only, and no newline. It becomes one argv ELEMENT of the
+ * form `--why=<text>`, so getopt reads the whole tail as the option's value
+ * whatever it contains — but `systemd-inhibit --list` prints it to an
+ * operator later, and a control character there corrupts a terminal rather
+ * than the command.
+ */
+export declare const SAFE_REASON: RegExp;
+/**
+ * Is this parsed JSON a state record every field of which can be used?
+ *
+ * ADVERSARIAL REVIEW FOUND A CRASH HERE. The first version checked `pid` and
+ * `marker` and nothing else, so a record carrying those two and a missing or
+ * non-numeric `startedAt`/`expiresAt` — an interrupted write, a file from an
+ * older layout, an operator who edited it — was accepted, and then
+ * `new Date(undefined).toISOString()` threw `RangeError: Invalid time value`
+ * straight out of `execute`. Both `status` and `release` did it, which is to
+ * say the tool crashed on exactly the path a caller reaches when the recorded
+ * assertion is the thing that has gone wrong. `hold` had the quieter half of
+ * the same bug: `now() < state.expiresAt` against a non-number is `false`, so
+ * it silently overwrote a record it should have refused to replace.
+ *
+ * Every field is checked, because every field is used: the dates are
+ * formatted, the pid is signalled, the marker is matched and the scope and
+ * backend are echoed.
+ */
+export declare function isAssertionState(value: unknown): value is AssertionState;
+/** What is remembered between calls. Written atomically; see ./fsseam.ts. */
+export type AssertionState = {
+    readonly pid: number;
+    readonly platform: HostPlatform;
+    readonly backend: string;
+    /** The program the live process must still be running to be OURS. */
+    readonly marker: string;
+    readonly scope: AssertionScope;
+    readonly startedAt: number;
+    readonly expiresAt: number;
+    readonly reason: string | null;
+};
+export type HoldPlan = {
+    readonly ok: true;
+    readonly backend: string;
+    /** The program name `release` matches against a live command line. */
+    readonly marker: string;
+    readonly request: Omit<RunRequest, "timeoutMs">;
+} | {
+    readonly ok: false;
+    readonly unavailable: Unavailable;
+};
+/** Build the holder's argv for `seconds` of inhibition. */
+export declare function planHold(platform: HostPlatform, scope: AssertionScope, seconds: number, reason: string | null): HoldPlan;
+/**
+ * Ask the host what `pid` is actually running.
+ *
+ * Not `process.kill(pid, 0)`: that answers "some process has this number",
+ * which after a pid rollover is exactly the wrong question. The command line
+ * is what distinguishes our holder from whatever inherited its number.
+ */
+export declare function planProcessProbe(platform: HostPlatform, pid: number): Omit<RunRequest, "timeoutMs"> | undefined;
+/** The signal that ends a verified holder. */
+export declare function planRelease(platform: HostPlatform, pid: number): Omit<RunRequest, "timeoutMs"> | undefined;
+/**
+ * Is the recorded assertion still ours, and still running?
+ *
+ * Four answers, and the two failure cases are deliberately different: a probe
+ * that could not run at all is NOT the same as a probe that ran and found
+ * somebody else's process. The first must not cause a kill, and must not
+ * cause the state file to be discarded either — the holder may be alive and
+ * unreachable only to `ps`.
+ */
+export type Liveness = "alive" | "gone" | "reused" | "unknown";
+/**
+ * Is this command line OUR holder, rather than something that merely mentions
+ * it?
+ *
+ * ADVERSARIAL REVIEW: the first version was `line.includes(marker)`, which
+ * answers "yes" for `vim /home/max/notes/caffeinate.md` and for
+ * `node ./caffeinate-runner.js`. After a pid rollover that is `release`
+ * sending SIGTERM to the operator's editor — precisely the failure the
+ * module header promises this check prevents ("A PID IS NOT AN IDENTITY"). A
+ * substring test over a whole command line is not an identity test.
+ *
+ * So the PROGRAM is compared: the first token, unquoted, basename, `.exe`
+ * stripped. Windows is the one case where that is not enough and cannot be —
+ * the holder there genuinely IS `powershell.exe`, and what makes it ours is
+ * the generated type name inside the script it was handed — so the substring
+ * test is kept for that case alone, narrowed to a powershell host.
+ */
+export declare function commandMatchesMarker(commandLine: string, marker: string): boolean;
+export declare function classifyLiveness(marker: string, result: {
+    readonly code: number;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly timedOut: boolean;
+    readonly missing: boolean;
+    readonly refused?: boolean;
+}): Liveness;
+/** Minutes to a bounded second count, or a refusal naming the ceiling. */
+export declare function boundedSeconds(minutes: number): {
+    seconds: number;
+} | {
+    refusal: string;
+};

package/dist/lib/power.js

@@ -0,0 +1,224 @@
+import { powershellArgv, registerPowerShellScript } from "./escape";
+import { unsupportedPlatform } from "./outcome";
+/** The ceiling, and the reason there is one. Eight hours is a working day. */
+export const MAX_HOLD_MINUTES = 480;
+export const DEFAULT_HOLD_MINUTES = 30;
+/** Where the held assertion is remembered, relative to the workspace root. */
+export const STATE_RELATIVE_PATH = ".crewhaus/power-assertion.json";
+export const WINDOWS_INHIBIT = registerPowerShellScript({
+    name: "power-inhibit",
+    // DOCUMENTED, NOT RECORDED. The flags are ES_CONTINUOUS (0x80000000) |
+    // ES_SYSTEM_REQUIRED (0x00000001), plus ES_DISPLAY_REQUIRED (0x00000002)
+    // when the caller asked for the display — passed as a NUMBER in the
+    // environment, never interpolated into this source. `Start-Sleep` is what
+    // keeps the thread alive; without it the state is discarded the instant the
+    // process exits and the whole call is a no-op.
+    script: [
+        "$src = 'using System;using System.Runtime.InteropServices;public class CHPwr{[DllImport(\"kernel32.dll\")]public static extern uint SetThreadExecutionState(uint f);}'",
+        "Add-Type -TypeDefinition $src -ErrorAction Stop",
+        "[void][CHPwr]::SetThreadExecutionState([uint32]$env:CREWHAUS_INHIBIT_FLAGS)",
+        "Start-Sleep -Seconds ([int]$env:CREWHAUS_INHIBIT_SECONDS)",
+    ].join("; "),
+    reads: ["CREWHAUS_INHIBIT_FLAGS", "CREWHAUS_INHIBIT_SECONDS"],
+});
+export const WINDOWS_PROCESS_PROBE = registerPowerShellScript({
+    name: "process-probe",
+    script: '$p = Get-CimInstance Win32_Process -Filter "ProcessId=$env:CREWHAUS_PID" -ErrorAction SilentlyContinue; if ($p) { [Console]::Out.Write($p.CommandLine) }',
+    reads: ["CREWHAUS_PID"],
+});
+/**
+ * The reason string a caller may attach to a Linux inhibitor.
+ *
+ * Printable ASCII only, and no newline. It becomes one argv ELEMENT of the
+ * form `--why=<text>`, so getopt reads the whole tail as the option's value
+ * whatever it contains — but `systemd-inhibit --list` prints it to an
+ * operator later, and a control character there corrupts a terminal rather
+ * than the command.
+ */
+export const SAFE_REASON = /^[ -~]{1,120}$/;
+/**
+ * Is this parsed JSON a state record every field of which can be used?
+ *
+ * ADVERSARIAL REVIEW FOUND A CRASH HERE. The first version checked `pid` and
+ * `marker` and nothing else, so a record carrying those two and a missing or
+ * non-numeric `startedAt`/`expiresAt` — an interrupted write, a file from an
+ * older layout, an operator who edited it — was accepted, and then
+ * `new Date(undefined).toISOString()` threw `RangeError: Invalid time value`
+ * straight out of `execute`. Both `status` and `release` did it, which is to
+ * say the tool crashed on exactly the path a caller reaches when the recorded
+ * assertion is the thing that has gone wrong. `hold` had the quieter half of
+ * the same bug: `now() < state.expiresAt` against a non-number is `false`, so
+ * it silently overwrote a record it should have refused to replace.
+ *
+ * Every field is checked, because every field is used: the dates are
+ * formatted, the pid is signalled, the marker is matched and the scope and
+ * backend are echoed.
+ */
+export function isAssertionState(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    const finite = (x) => typeof x === "number" && Number.isFinite(x);
+    return (finite(v["pid"]) &&
+        Number.isInteger(v["pid"]) &&
+        v["pid"] > 0 &&
+        typeof v["marker"] === "string" &&
+        v["marker"] !== "" &&
+        typeof v["backend"] === "string" &&
+        typeof v["platform"] === "string" &&
+        (v["scope"] === "system" || v["scope"] === "display") &&
+        finite(v["startedAt"]) &&
+        finite(v["expiresAt"]) &&
+        (v["reason"] === null || typeof v["reason"] === "string"));
+}
+/** Build the holder's argv for `seconds` of inhibition. */
+export function planHold(platform, scope, seconds, reason) {
+    switch (platform) {
+        case "darwin": {
+            // `-i` idle sleep, `-m` disk idle, `-s` only while on AC — omitted on
+            // purpose, a laptop on battery still needs the step to finish. `-d`
+            // additionally keeps the display awake. `-t` is the deadline, enforced
+            // by caffeinate rather than by this process.
+            const argv = ["caffeinate", "-i", "-m"];
+            if (scope === "display")
+                argv.push("-d");
+            argv.push("-t", String(seconds));
+            return { ok: true, backend: "caffeinate", marker: "caffeinate", request: { argv } };
+        }
+        case "linux": {
+            const what = scope === "display" ? "idle:sleep:handle-lid-switch" : "idle:sleep";
+            const argv = [
+                "systemd-inhibit",
+                `--what=${what}`,
+                "--who=crewhaus",
+                `--why=${reason ?? "crewhaus PowerAssertion"}`,
+                "--mode=block",
+                // The inhibitor lives exactly as long as this command. `sleep` is a
+                // program, not a shell — `assertArgv` would refuse an interpreter.
+                "sleep",
+                String(seconds),
+            ];
+            return {
+                ok: true,
+                backend: "systemd-inhibit",
+                marker: "systemd-inhibit",
+                request: { argv },
+            };
+        }
+        case "win32": {
+            const flags = scope === "display" ? 0x8000_0003 : 0x8000_0001;
+            const built = powershellArgv(WINDOWS_INHIBIT, {
+                CREWHAUS_INHIBIT_FLAGS: String(flags),
+                CREWHAUS_INHIBIT_SECONDS: String(seconds),
+            });
+            return {
+                ok: true,
+                backend: "powershell SetThreadExecutionState",
+                marker: "CHPwr",
+                request: { argv: built.argv, env: built.env },
+            };
+        }
+        default:
+            return { ok: false, unavailable: unsupportedPlatform(platform, "power-assertion") };
+    }
+}
+/**
+ * Ask the host what `pid` is actually running.
+ *
+ * Not `process.kill(pid, 0)`: that answers "some process has this number",
+ * which after a pid rollover is exactly the wrong question. The command line
+ * is what distinguishes our holder from whatever inherited its number.
+ */
+export function planProcessProbe(platform, pid) {
+    switch (platform) {
+        case "darwin":
+        case "linux":
+            // `-o command=` prints the command line with no header, and nothing
+            // else. The pid is a number this package produced, not caller input.
+            return { argv: ["ps", "-o", "command=", "-p", String(pid)] };
+        case "win32":
+            return { argv: powershellArgv(WINDOWS_PROCESS_PROBE, { CREWHAUS_PID: String(pid) }).argv };
+        default:
+            return undefined;
+    }
+}
+/** The signal that ends a verified holder. */
+export function planRelease(platform, pid) {
+    switch (platform) {
+        case "darwin":
+        case "linux":
+            // SIGTERM, not SIGKILL: `systemd-inhibit` must run its own teardown to
+            // drop the logind lock, and a SIGKILLed inhibitor leaves the lock held
+            // until logind notices the process is gone.
+            return { argv: ["kill", "-TERM", String(pid)] };
+        case "win32":
+            // `/T` takes the child `Start-Sleep` with it; `/F` because a PowerShell
+            // host parked in Start-Sleep does not process a polite close.
+            return { argv: ["taskkill", "/PID", String(pid), "/T", "/F"] };
+        default:
+            return undefined;
+    }
+}
+/**
+ * Is this command line OUR holder, rather than something that merely mentions
+ * it?
+ *
+ * ADVERSARIAL REVIEW: the first version was `line.includes(marker)`, which
+ * answers "yes" for `vim /home/max/notes/caffeinate.md` and for
+ * `node ./caffeinate-runner.js`. After a pid rollover that is `release`
+ * sending SIGTERM to the operator's editor — precisely the failure the
+ * module header promises this check prevents ("A PID IS NOT AN IDENTITY"). A
+ * substring test over a whole command line is not an identity test.
+ *
+ * So the PROGRAM is compared: the first token, unquoted, basename, `.exe`
+ * stripped. Windows is the one case where that is not enough and cannot be —
+ * the holder there genuinely IS `powershell.exe`, and what makes it ours is
+ * the generated type name inside the script it was handed — so the substring
+ * test is kept for that case alone, narrowed to a powershell host.
+ */
+export function commandMatchesMarker(commandLine, marker) {
+    const first = commandLine.trim().split(/\s+/)[0] ?? "";
+    const unquoted = first.replace(/^"+|"+$/g, "");
+    const base = (unquoted.split(/[\\/]/).pop() ?? unquoted).replace(/\.exe$/i, "");
+    if (base === marker)
+        return true;
+    return /^powershell$/i.test(base) && commandLine.includes(marker);
+}
+export function classifyLiveness(marker, result) {
+    if (result.refused === true || result.missing || result.timedOut)
+        return "unknown";
+    // `ps -p <pid>` exits 1 with no output when nothing has that pid. That is a
+    // definite answer, not a failure — but ONLY when `ps` itself said nothing.
+    //
+    // ADVERSARIAL REVIEW: the first version read every non-zero exit with empty
+    // stdout as "gone", and `ps` has other ways to exit non-zero with an empty
+    // stdout, all of them loud on stderr. Recorded on macOS 26.6.2:
+    //   $ ps -o command= -p 999999 ; echo $?
+    //   ps: process id too large
+    //   1
+    // Reading that as "gone" makes `release` delete the state file and report
+    // `expired` for a holder that may still be running — the exact "could not
+    // determine is not no" inversion rule 6 names, on the one path where the
+    // consequence is an inhibitor nobody can release before its deadline.
+    if (result.code !== 0) {
+        if (result.stderr.trim() !== "")
+            return "unknown";
+        return result.stdout.trim() === "" ? "gone" : "unknown";
+    }
+    const line = result.stdout.trim();
+    if (line === "")
+        return "gone";
+    return commandMatchesMarker(line, marker) ? "alive" : "reused";
+}
+/** Minutes to a bounded second count, or a refusal naming the ceiling. */
+export function boundedSeconds(minutes) {
+    if (!Number.isFinite(minutes) || minutes <= 0) {
+        return { refusal: "maxMinutes must be a positive number of minutes" };
+    }
+    if (minutes > MAX_HOLD_MINUTES) {
+        return {
+            refusal: `maxMinutes must be at most ${MAX_HOLD_MINUTES} (8 hours) — an assertion held longer than a working day is one nobody is waiting for any more`,
+        };
+    }
+    return { seconds: Math.max(1, Math.round(minutes * 60)) };
+}

package/dist/lib/presence.d.ts

@@ -0,0 +1,118 @@
+/**
+ * `UserPresence` — is there a human at this machine, and should a workflow
+ * interrupt them.
+ *
+ * THIS IS THE TOOL RULE 6 WAS WRITTEN FOR. Every field here has a tempting
+ * fallback that inverts the tool's purpose:
+ *
+ *   - "no idle signal, assume active" tells a workflow the operator is at the
+ *     keyboard when the truth is that nothing could be asked.
+ *   - "the probe failed, so idle" tells it the opposite, and a workflow that
+ *     acts on `idle: true` does things unattended.
+ *   - "screen-lock has no CLI, so not locked" claims the screen is unlocked
+ *     on every machine in the world.
+ *
+ * So every field is `number | null` or `boolean | null`, `null` always
+ * carries an entry in `unknown` naming the probe and the reason, and the
+ * derived `idle` boolean is `null` whenever `idleSeconds` is.
+ *
+ * ── WHAT EACH PLATFORM CAN ACTUALLY ANSWER ────────────────────────────────
+ *
+ * macOS     Idle comes out of an `ioreg` text dump, in NANOSECONDS. The unit
+ *           is the trap: reading it as milliseconds makes every host look
+ *           permanently active, and nothing about the number's shape gives
+ *           that away. The incantation matters too — the survey sketch's
+ *           `ioreg -c IOHIDSystem -d 1` prints NOTHING on macOS 26.6.2
+ *           (verified); `-r` is required, because `-d 1` without it bounds
+ *           the depth from the root rather than from the matched object:
+ *
+ *             $ ioreg -c IOHIDSystem -d 1 | grep HIDIdleTime      # empty
+ *             $ ioreg -r -c IOHIDSystem -d 1 | grep HIDIdleTime
+ *                   "HIDIdleTime" = 3254341351000
+ *
+ *           Lock state has no supported CLI, and the framework call
+ *           (CGSessionCopyCurrentDictionary) is a C API. But the same
+ *           registry carries it, recorded on the same machine with the screen
+ *           locked:
+ *
+ *             $ ioreg -n Root -d1
+ *                   "IOConsoleLocked" = Yes
+ *                   "IOConsoleUsers" = ({...,"CGSSessionScreenIsLocked"=Yes,...})
+ *
+ *           Both keys are read, `IOConsoleLocked` first. A dump with neither
+ *           is reported as unknown rather than as unlocked.
+ * Linux     `xprintidle` is the only idle source and is usually NOT
+ *           installed; under Wayland there is no idle query at all. Lock
+ *           state comes from logind's `LockedHint`, which is a HINT — it is
+ *           set by a screen locker that bothers to call `SetLockedHint`, and
+ *           a locker that does not leaves it `no` on a locked screen. It is
+ *           reported with that caveat attached rather than as a fact.
+ * Windows   `GetLastInputInfo` through a registered PowerShell script, and
+ *           the presence of `LogonUI` as the lock signal — that process runs
+ *           only while the lock or login screen is up.
+ *
+ * And over all of it: an SSH session. Idle time on a machine you are talking
+ * to over a wire says nothing about whether a person is sitting at it, so a
+ * remote shell reports `sessionKind: "ssh"` and does not pretend otherwise.
+ */
+import { type HostPlatform, type SessionEnv } from "../host";
+import type { RunRequest } from "../run";
+export type SessionKind = "console" | "ssh" | "headless" | "unknown";
+export declare const WINDOWS_PRESENCE: import("./escape").PowerShellScript;
+/** One probe this tool might run. Each is independently allowed to fail. */
+export type PresenceProbe = {
+    readonly field: "idleSeconds" | "screenLocked";
+    readonly request: Omit<RunRequest, "timeoutMs">;
+};
+/**
+ * Which probes to run, plus the fields this platform cannot probe at all.
+ *
+ * A platform with no probe for a field is not an error — it is a field that
+ * comes back `null` with its reason, which is the whole contract here.
+ */
+export declare function planPresence(platform: HostPlatform, env: SessionEnv): {
+    readonly probes: readonly PresenceProbe[];
+    readonly notes: ReadonlyArray<[string, string]>;
+};
+/**
+ * Parse `HIDIdleTime` out of an ioreg dump.
+ *
+ * NANOSECONDS. Recorded: `"HIDIdleTime" = 3254341351000` is 3254 seconds —
+ * about 54 minutes, which is what the machine had been idle for. Reading it
+ * as milliseconds would have reported 3254 SECONDS as 3.2 seconds and made a
+ * locked, untouched machine look freshly used.
+ *
+ * The value passes 2^53 on a host idle for more than about 104 days, so it is
+ * divided as a BigInt. A float round there is only seconds of error, but it
+ * is error with no reason to exist.
+ */
+export declare function parseIoregIdleSeconds(stdout: string): number | null;
+/**
+ * Parse macOS lock state out of an `ioreg -n Root -d1` dump.
+ *
+ * `null` when neither key is present — that is a macOS version this parser
+ * has not seen, and guessing "unlocked" for it would claim every such machine
+ * has a human looking at it.
+ */
+export declare function parseIoregLocked(stdout: string): boolean | null;
+/** `xprintidle` prints milliseconds and nothing else. */
+export declare function parseXprintidleSeconds(stdout: string): number | null;
+/** Parse `loginctl show-session -p …` key=value output. */
+export declare function parseLoginctl(stdout: string): {
+    readonly locked: boolean | null;
+    readonly type: string | null;
+    readonly active: boolean | null;
+};
+/** Parse the two lines the Windows script prints. */
+export declare function parseWindowsPresence(stdout: string): {
+    readonly idleSeconds: number | null;
+    readonly locked: boolean | null;
+};
+/**
+ * What kind of session this is.
+ *
+ * `ssh` wins over everything: a forwarded `DISPLAY` on an ssh connection is
+ * still a wire, and the idle time it would report belongs to the machine at
+ * the far end rather than to the person typing.
+ */
+export declare function sessionKind(platform: HostPlatform, env: SessionEnv): SessionKind;