@aragon-agent/cli 0.5.9 → 0.5.11

package/dist/ui/frame-differ.js

@@ -0,0 +1,230 @@
+/**
+ * Frame differ — F1 of tui-input-flicker-fix (§3.2).
+ *
+ * Ink 5.2.1 has exactly one repaint strategy: on every commit it serialises the
+ * WHOLE frame and hands it to `log-update`, which writes
+ * `eraseLines(previousLineCount) + frame` in a single `stdout.write`
+ * (`ink/build/log-update.js:17`). `ansiEscapes.eraseLines` walks BOTTOM-UP, so
+ * the composer — the last row of the frame — is erased near the start of every
+ * repaint and rewritten at the very end of it. During a run that happens 15–30
+ * times a second with the composer's bytes unchanged, and the user sees the
+ * bottom of their screen flicker while they type (§2 R1/R2).
+ *
+ * This module recognises that write shape, diffs the new frame against the
+ * previous one line by line, and emits only the rows that actually changed, each
+ * addressed absolutely. It is PURE: no I/O, no Node globals, no event emitter —
+ * `stdout-frame-writer.ts` is what binds it to a real stream. That is what keeps
+ * it unit-testable with plain string literals and no TTY.
+ *
+ * THREE INVARIANTS LIVE HERE AND EACH ONE FAILS SILENTLY IF DROPPED:
+ *
+ *  - I-4 · An emitted line is `CUP · SGR0 · text · SGR0 · CSI K`, IN THAT ORDER,
+ *    and it never contains `CSI 2K`. Erasing first would blank the row and refill
+ *    it, which is R1's defect at 1/H the scale but on the one row the user is
+ *    watching. Overwriting in place means no cell is ever presentably empty; the
+ *    trailing `CSI K` removes only the residue a longer previous line left, and
+ *    the trailing SGR reset before it stops a BCE terminal painting that residue
+ *    in whatever background colour the line ended inside.
+ *  - I-5 · Every emitted batch ends parked on row `H+1`. Ink's own
+ *    `previousLineCount` is computed from the string IT produced and is
+ *    unaffected by what we actually wrote, so a later pass-through's
+ *    `eraseLines(H+1)` must find the cursor exactly where log-update left it last
+ *    time. Drop this and one fallback shifts the frame up a row for the rest of
+ *    the session.
+ *  - I-6 · Any unrecognised write invalidates the cache. Absolute addressing is
+ *    valid only while nothing else writes to stdout. Full-screen mode already
+ *    forbids that, but "forbidden" is not "impossible", and the failure mode of
+ *    the guard being absent is a permanently misaligned screen while the failure
+ *    mode of it firing spuriously is one extra full repaint.
+ */
+import { MIN_FULLSCREEN_ROWS } from './layout/frame.js';
+// ---------------------------------------------------------------------------
+// Constants — exact, so no call site ever re-derives an escape sequence.
+// ---------------------------------------------------------------------------
+/** Control Sequence Introducer. Spelled out once; nothing below re-escapes it. */
+const CSI = '\x1b[';
+/** Erase the WHOLE line. Ink uses it on every repaint; this module never emits it (I-4). */
+const ERASE_LINE = `${CSI}2K`;
+/** Erase cursor → end of line. This is what an emitted line ends with. */
+const ERASE_TO_EOL = `${CSI}K`;
+const CURSOR_UP_1 = `${CSI}1A`;
+const CURSOR_LEFT = `${CSI}G`;
+const SGR_RESET = `${CSI}0m`;
+/** Erase cursor → end of screen. One sequence instead of H+1 line erases. */
+const ERASE_DOWN = `${CSI}J`;
+/** DEC private mode 2026 — begin/end synchronized update (F2, §3.3). */
+const SYNC_BEGIN = `${CSI}?2026h`;
+const SYNC_END = `${CSI}?2026l`;
+/**
+ * `eraseLines(n)` for any n ≥ 1, anchored at the start of the chunk.
+ *
+ * FALLBACK ONLY (P2-3). Whenever `prev !== null` the differ already knows the
+ * exact prefix it expects — `eraseLinesPrefix(prev.length + 1)` is a
+ * deterministic string — so the hot path is `chunk.startsWith(expected)`:
+ * linear, unambiguous, and it collapses step 7's `erased !== prev.length + 1`
+ * test into the same comparison. This regex is reached only on the first
+ * diffable chunk after a session start or an `invalidate()`, where no
+ * expectation exists yet.
+ */
+const ERASE_PREFIX_RE = /^(?:\x1b\[2K(?:\x1b\[1A)?)+\x1b\[G/;
+function cursorTo(row) {
+    return `${CSI}${row};1H`;
+}
+/**
+ * Rebuild `ansiEscapes.eraseLines(count)` byte for byte.
+ *
+ * Exported for the upgrade tripwire (`frame-differ-ink-shape.test.ts`), which
+ * drives the real `ink/build/log-update.js` and asserts this reconstruction is
+ * byte-equal to what it produced. If a future Ink changes the shape, that test
+ * fails loudly instead of this module silently degrading to pass-through for the
+ * rest of the package's life (K-2).
+ */
+export function eraseLinesPrefix(count) {
+    if (count <= 0)
+        return '';
+    let out = '';
+    for (let i = 0; i < count; i += 1) {
+        out += ERASE_LINE + (i < count - 1 ? CURSOR_UP_1 : '');
+    }
+    return out + CURSOR_LEFT;
+}
+function countErases(prefix) {
+    return prefix.split(ERASE_LINE).length - 1;
+}
+export function createFrameDiffer(options) {
+    /** Last frame, one entry per row. `null` = no cache, next frame is a full repaint. */
+    let prev = null;
+    /**
+     * Whether any chunk has been seen at all.
+     *
+     * The session's FIRST write has `previousLineCount === 0`, so `eraseLines(0)`
+     * is the empty string and the chunk carries no erase prefix (§3.2.1). That is
+     * expected, not a desync, so it must not raise the §5.6 notice on every launch.
+     * After it, every chunk Ink produces carries a prefix, so a prefix-less chunk
+     * from then on really is foreign.
+     */
+    let seenAnyChunk = false;
+    const counters = {
+        framesTotal: 0,
+        framesDiffed: 0,
+        framesFull: 0,
+        linesWritten: 0,
+        bytesWritten: 0,
+        fallbacks: 0,
+    };
+    const invalidate = () => {
+        prev = null;
+    };
+    /**
+     * Write `chunk` verbatim — today's behaviour, and the only failure mode.
+     *
+     * `counted` is false for the two cases the differ inflicts on itself and knows
+     * are harmless (the seed write, degenerate geometry); true means a foreign
+     * write desynced absolute addressing, which is what `fallbacks` reports.
+     */
+    const passThrough = (counted) => {
+        invalidate();
+        if (counted) {
+            counters.fallbacks += 1;
+            if (counters.fallbacks === 1)
+                options.onFirstFallback?.();
+        }
+        return null;
+    };
+    const wrapSync = (payload) => options.sync ? SYNC_BEGIN + payload + SYNC_END : payload;
+    const emit = (payload, lines, addressed, full) => {
+        prev = lines;
+        counters.framesTotal += 1;
+        if (full)
+            counters.framesFull += 1;
+        else
+            counters.framesDiffed += 1;
+        counters.linesWritten += addressed;
+        counters.bytesWritten += payload.length;
+        return payload;
+    };
+    /** `undefined` ⇒ the I-9 stand-down: a viewport too small to address safely. */
+    const usableRows = () => {
+        const rows = options.rows();
+        if (rows === undefined || !Number.isFinite(rows))
+            return undefined;
+        return rows < MIN_FULLSCREEN_ROWS ? undefined : rows;
+    };
+    const matchErasePrefix = (chunk) => {
+        if (prev !== null) {
+            const expected = eraseLinesPrefix(prev.length + 1);
+            if (chunk.startsWith(expected))
+                return { prefix: expected, erased: prev.length + 1 };
+        }
+        const m = ERASE_PREFIX_RE.exec(chunk);
+        if (m === null)
+            return null;
+        return { prefix: m[0], erased: countErases(m[0]) };
+    };
+    /**
+     * Full repaint — the first diffable frame of a session, every invalidation
+     * (including the resize invalidation of I-8), and any line-count change.
+     *
+     * `CSI J` replaces the H+1 individual line erases with one sequence, and the
+     * alternate screen is exactly the region being erased. `\r\n` rather than `\n`
+     * is deliberate: Ink relies on the tty's `ONLCR` post-processing to turn `\n`
+     * into CRLF, and that dependency is invisible until it is not there.
+     *
+     * P0-1's blank-then-paint objection does not apply here and the asymmetry with
+     * the per-line path is deliberate: a full repaint rewrites every row, so there
+     * is no unchanged content that has to survive, and full repaints are rare by
+     * construction — one per session, one per resize, one per invalidation.
+     */
+    const fullRepaint = (lines) => {
+        const payload = cursorTo(1) +
+            SGR_RESET +
+            ERASE_DOWN +
+            lines.join('\r\n') +
+            '\r\n' +
+            cursorTo(lines.length + 1);
+        return emit(wrapSync(payload), lines, lines.length, true);
+    };
+    const diffRepaint = (lines, previous) => {
+        const out = [];
+        for (let i = 0; i < lines.length; i += 1) {
+            // I-4: paint, THEN clear the tail. Never `ERASE_LINE` first.
+            if (lines[i] !== previous[i]) {
+                out.push(cursorTo(i + 1) + SGR_RESET + lines[i] + SGR_RESET + ERASE_TO_EOL);
+            }
+        }
+        // DEFENSIVE ONLY, not a live path (P2-4). `log-update.js:13-15` returns early
+        // on an identical frame, so a chunk that reaches here differs by at least one
+        // line; the only way to observe zero is a cache that disagrees with the
+        // screen, which is the state `invalidate()` exists to prevent.
+        if (out.length === 0)
+            return emit('', lines, 0, false);
+        out.push(cursorTo(lines.length + 1)); // I-5
+        return emit(wrapSync(out.join('')), lines, out.length - 1, false);
+    };
+    const transform = (chunk) => {
+        const firstChunk = !seenAnyChunk;
+        seenAnyChunk = true;
+        const rows = usableRows();
+        if (rows === undefined)
+            return passThrough(false); // I-9
+        const matched = matchErasePrefix(chunk);
+        // A prefix-less chunk is the session's seed write (P1-1) or a foreign one.
+        if (matched === null)
+            return passThrough(!firstChunk);
+        const body = chunk.slice(matched.prefix.length);
+        if (!body.endsWith('\n'))
+            return passThrough(true); // `log.clear()` and friends
+        const lines = body.slice(0, -1).split('\n');
+        if (lines.length + 1 > rows)
+            return passThrough(false); // I-9
+        if (prev === null || prev.length !== lines.length || matched.erased !== prev.length + 1) {
+            return fullRepaint(lines);
+        }
+        return diffRepaint(lines, prev);
+    };
+    return {
+        transform,
+        invalidate,
+        stats: () => ({ ...counters }),
+    };
+}

package/dist/ui/stdout-frame-writer.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Stdout frame writer — the `Proxy` that binds `frame-differ.ts` to a real
+ * stream (tui-input-flicker-fix §3.2 / §5.5).
+ *
+ * Ink offers no hook for "how to write a frame": `Ink#log` is constructed
+ * internally and `log-update` is a private module. It DOES accept a `stdout` in
+ * `render()`'s options, so the whole interposition is one `Proxy` whose only
+ * trapped behaviour is `write` — everything else is the real stream.
+ *
+ * THREE THINGS IN HERE ARE LOAD-BEARING:
+ *
+ *  - The `get` trap MUST bind non-`write` function members to the REAL stream.
+ *    Without the bind, `stdout.on('resize', …)` executes with `this === proxy`,
+ *    and `useTerminalSize` registers and removes its listener against a
+ *    different `_events` object than the one Node emits on — the frame stops
+ *    resizing and nothing reports why.
+ *  - The UNTYPED BOUNDARY LIVES HERE, not in the differ (P1-4). A `Uint8Array`
+ *    chunk, and any `write` whose `encoding` is present and is not UTF-8, is
+ *    passed straight through after `invalidate()`: in both cases the bytes on
+ *    the wire are not the string a differ could reason about, and diffing one
+ *    encoding while writing another is the kind of bug that only shows up on
+ *    someone else's machine.
+ *  - The `'resize'` SUBSCRIPTION (I-8 / P0-2). Ink renders SYNCHRONOUSLY from its
+ *    own `'resize'` handler while the frame's height is still the pre-resize one
+ *    — `useTerminalSize` debounces by 50 ms — so the line count is unchanged
+ *    across that window and the differ's line-count guard cannot see the resize.
+ *    Meanwhile the emulator has re-flowed the alternate screen, so every row the
+ *    differ believes unchanged is a row it will not repaint, for the rest of the
+ *    drag. It goes on the REAL stream, not the `Proxy`, and `dispose()` removes
+ *    it.
+ */
+import type { FrameDiffer, FrameWriterStats } from './frame-differ.js';
+export interface FrameWriterHandle {
+    /** Hand this to `render(…, { stdout })`. */
+    stdout: NodeJS.WriteStream;
+    /** Hand this to `setFrameStatsProvider`. */
+    stats(): FrameWriterStats;
+    /** Removes the `'resize'` subscription of I-8. Idempotent. */
+    dispose(): void;
+}
+export declare function wrapStdoutForFrames(stdout: NodeJS.WriteStream, differ: FrameDiffer): FrameWriterHandle;

package/dist/ui/stdout-frame-writer.js

@@ -0,0 +1,102 @@
+/**
+ * Stdout frame writer — the `Proxy` that binds `frame-differ.ts` to a real
+ * stream (tui-input-flicker-fix §3.2 / §5.5).
+ *
+ * Ink offers no hook for "how to write a frame": `Ink#log` is constructed
+ * internally and `log-update` is a private module. It DOES accept a `stdout` in
+ * `render()`'s options, so the whole interposition is one `Proxy` whose only
+ * trapped behaviour is `write` — everything else is the real stream.
+ *
+ * THREE THINGS IN HERE ARE LOAD-BEARING:
+ *
+ *  - The `get` trap MUST bind non-`write` function members to the REAL stream.
+ *    Without the bind, `stdout.on('resize', …)` executes with `this === proxy`,
+ *    and `useTerminalSize` registers and removes its listener against a
+ *    different `_events` object than the one Node emits on — the frame stops
+ *    resizing and nothing reports why.
+ *  - The UNTYPED BOUNDARY LIVES HERE, not in the differ (P1-4). A `Uint8Array`
+ *    chunk, and any `write` whose `encoding` is present and is not UTF-8, is
+ *    passed straight through after `invalidate()`: in both cases the bytes on
+ *    the wire are not the string a differ could reason about, and diffing one
+ *    encoding while writing another is the kind of bug that only shows up on
+ *    someone else's machine.
+ *  - The `'resize'` SUBSCRIPTION (I-8 / P0-2). Ink renders SYNCHRONOUSLY from its
+ *    own `'resize'` handler while the frame's height is still the pre-resize one
+ *    — `useTerminalSize` debounces by 50 ms — so the line count is unchanged
+ *    across that window and the differ's line-count guard cannot see the resize.
+ *    Meanwhile the emulator has re-flowed the alternate screen, so every row the
+ *    differ believes unchanged is a row it will not repaint, for the rest of the
+ *    drag. It goes on the REAL stream, not the `Proxy`, and `dispose()` removes
+ *    it.
+ */
+/** The only encodings for which the chunk string IS the bytes on the wire. */
+function isUtf8Encoding(encoding) {
+    const e = encoding.toLowerCase();
+    return e === 'utf8' || e === 'utf-8';
+}
+export function wrapStdoutForFrames(stdout, differ) {
+    const bound = new Map();
+    const writeReal = (chunk, encoding, cb) => {
+        if (encoding !== undefined)
+            return stdout.write(chunk, encoding, cb);
+        return stdout.write(chunk, cb);
+    };
+    /**
+     * All three Node overloads: `write(chunk)`, `write(chunk, cb)`,
+     * `write(chunk, encoding, cb)`.
+     */
+    const write = (chunk, encodingOrCb, maybeCb) => {
+        const encoding = typeof encodingOrCb === 'string' ? encodingOrCb : undefined;
+        const cb = typeof encodingOrCb === 'function'
+            ? encodingOrCb
+            : typeof maybeCb === 'function'
+                ? maybeCb
+                : undefined;
+        // Foreign by construction: Ink never writes Buffers, and a non-UTF-8
+        // encoding means the string is not the bytes (P1-4).
+        if (typeof chunk !== 'string' || (encoding !== undefined && !isUtf8Encoding(encoding))) {
+            differ.invalidate();
+            return writeReal(chunk, encoding, cb);
+        }
+        const out = differ.transform(chunk);
+        if (out === null)
+            return writeReal(chunk, encoding, cb);
+        // Nothing to write, but the callback is still part of the contract — a
+        // skipped `cb` strands whatever was waiting on the drain.
+        if (out.length === 0) {
+            cb?.();
+            return true;
+        }
+        return writeReal(out, encoding, cb);
+    };
+    const onResize = () => differ.invalidate();
+    stdout.on('resize', onResize);
+    let disposed = false;
+    const proxy = new Proxy(stdout, {
+        get(target, prop) {
+            if (prop === 'write')
+                return write;
+            const value = Reflect.get(target, prop, target);
+            if (typeof value !== 'function')
+                return value;
+            // Cached so repeated property access does not allocate a new bound
+            // function on a hot path (K-9).
+            let fn = bound.get(prop);
+            if (fn === undefined) {
+                fn = value.bind(target);
+                bound.set(prop, fn);
+            }
+            return fn;
+        },
+    });
+    return {
+        stdout: proxy,
+        stats: () => differ.stats(),
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            stdout.off('resize', onResize);
+        },
+    };
+}

package/dist/update/classify-failure.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Turning a tail of npm output into a reason (cli-auto-update-hardening H2 /
+ * section 5.3).
+ *
+ * ASCII ONLY - this tree is inside the glyph scanner's scope (C-2 / C-3).
+ *
+ * PURE, AND THE ONLY IMPORT IS A TYPE. The interesting half of H2 is not this
+ * table, it is the REPORTING rule that decides which of the resulting reasons
+ * may break the three-strike silence - and that lives in `types.ts` beside
+ * `shouldRenderUpdateLine`, as `IMMEDIATE_NOTICE_REASONS`.
+ *
+ * WHY THIS EXISTS AT ALL. The one line a user is ever allowed to see on the
+ * failure path reads `update failed <dot> npm i -g @aragon-agent/cli` for EVERY
+ * cause. For `EPERM` / `EBUSY` - the Windows self-replacement case, R-3 - that
+ * advice hits the same held handle and fails identically, so the single visible
+ * failure is also a wrong instruction.
+ */
+import type { UpdateReason } from './types.js';
+/**
+ * Classify an install failure from the bounded stderr tail `runNpmInstall`
+ * already returns.
+ *
+ * ONE PARAMETER, NOT TWO. An earlier draft took `exitCode` and never read it:
+ * npm exits `1` for every one of these, so the code carries no information the
+ * tail does not, and a parameter that no branch and no test consumes is a
+ * maintenance liability that reads like a promise (P2-2).
+ *
+ * An absent or unrecognised tail is `install-failed` - the pre-H2 behaviour, so
+ * a machine whose npm says something we have never seen degrades to exactly what
+ * it did before rather than to a confident wrong answer.
+ */
+export declare function classifyInstallFailure(tail: string | undefined): UpdateReason;

package/dist/update/classify-failure.js

@@ -0,0 +1,60 @@
+/**
+ * Turning a tail of npm output into a reason (cli-auto-update-hardening H2 /
+ * section 5.3).
+ *
+ * ASCII ONLY - this tree is inside the glyph scanner's scope (C-2 / C-3).
+ *
+ * PURE, AND THE ONLY IMPORT IS A TYPE. The interesting half of H2 is not this
+ * table, it is the REPORTING rule that decides which of the resulting reasons
+ * may break the three-strike silence - and that lives in `types.ts` beside
+ * `shouldRenderUpdateLine`, as `IMMEDIATE_NOTICE_REASONS`.
+ *
+ * WHY THIS EXISTS AT ALL. The one line a user is ever allowed to see on the
+ * failure path reads `update failed <dot> npm i -g @aragon-agent/cli` for EVERY
+ * cause. For `EPERM` / `EBUSY` - the Windows self-replacement case, R-3 - that
+ * advice hits the same held handle and fails identically, so the single visible
+ * failure is also a wrong instruction.
+ */
+/**
+ * FIRST MATCH WINS, AND THE ORDER IS NOT ALPHABETICAL.
+ *
+ * `EPERM` is tested before `EACCES` because npm's Windows output frequently
+ * carries BOTH - the `EPERM` on the shim rename plus an `EACCES` from a retry -
+ * and the actionable one is the first. `network` is last because "proxy" and
+ * "network" appear inside unrelated npm advisory text often enough that an
+ * earlier position would swallow the three specific cases above it.
+ */
+const TABLE = [
+    [
+        /\bEPERM\b|\bEBUSY\b|\bETXTBSY\b|operation not permitted|resource busy or locked/i,
+        'blocked-by-os',
+    ],
+    [/\bEACCES\b|permission denied/i, 'not-writable'],
+    [/\bENOSPC\b|no space left/i, 'no-space'],
+    [
+        /\bENOTFOUND\b|\bEAI_AGAIN\b|\bECONNRESET\b|\bETIMEDOUT\b|network|proxy|tunneling socket/i,
+        'network',
+    ],
+];
+/**
+ * Classify an install failure from the bounded stderr tail `runNpmInstall`
+ * already returns.
+ *
+ * ONE PARAMETER, NOT TWO. An earlier draft took `exitCode` and never read it:
+ * npm exits `1` for every one of these, so the code carries no information the
+ * tail does not, and a parameter that no branch and no test consumes is a
+ * maintenance liability that reads like a promise (P2-2).
+ *
+ * An absent or unrecognised tail is `install-failed` - the pre-H2 behaviour, so
+ * a machine whose npm says something we have never seen degrades to exactly what
+ * it did before rather than to a confident wrong answer.
+ */
+export function classifyInstallFailure(tail) {
+    if (!tail)
+        return 'install-failed';
+    for (const [re, reason] of TABLE) {
+        if (re.test(tail))
+            return reason;
+    }
+    return 'install-failed';
+}

package/dist/update/install-lock.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The cross-process install lock (cli-auto-update section 3.7).
+ *
+ * ASCII ONLY - this tree is inside the glyph scanner's scope (C-2 / C-3).
+ *
+ * INHERITS `skills/lock.ts`'s PAYLOAD DISCIPLINE, NOT ITS ACQUISITION LOOP
+ * (C-9). The payload shape, the TTL, the liveness probe, the
+ * `LOCK_UNREADABLE_CONFIRMATIONS` rule and the uuid-guarded release are all the
+ * same and are imported rather than restated. The retry loop is NOT:
+ *
+ * INVARIANT U-5b - ACQUISITION IS A SINGLE NON-BLOCKING ATTEMPT.
+ * `acquireRootLock` busy-waits SYNCHRONOUSLY through `Atomics.wait` for up to
+ * `LOCK_MAX_WAIT_MS = 5_000` and then THROWS. That is right for `aragon skills
+ * install`, where a human typed the command and there is nothing else to do.
+ * Here it would freeze the Ink render loop for five seconds, from a background
+ * timer, in the feature whose entire requirement is that it is invisible. So:
+ * one `wx` attempt, no sleep, no retry, no throw - `tryAcquireInstallLock()`
+ * returns `null` on `EEXIST` after the staleness check, and the caller treats
+ * that as INFORMATION (someone else is already installing) rather than failure.
+ */
+export interface InstallLockHandle {
+    /**
+     * Phase two of U-4: rewrite the payload in place with the CHILD's pid.
+     *
+     * `uuid` and `startedAt` are preserved - the uuid is what `release()` matches
+     * on, and `startedAt` is what the TTL measures, so replacing either here would
+     * silently break one of the two recovery paths.
+     */
+    adoptChild(pid: number): void;
+    release(): void;
+}
+export interface InstallLockOptions {
+    now?: () => number;
+    /** Injected for tests; defaults to `process.kill(pid, 0)` liveness probing. */
+    isProcessAlive?: (pid: number) => boolean;
+    /** Injected for tests; defaults to `<home>/update-install.lock`. */
+    path?: string;
+}
+/**
+ * Take the install lock, or report that someone else has it. NEVER SLEEPS,
+ * NEVER THROWS (U-5b / AC-27).
+ *
+ * The payload written here carries the PARENT's pid, and that is not a mistake:
+ * INVARIANT U-4 says the lock must name the CHILD, but the lock has to be held
+ * BEFORE the spawn (or the race it exists to close is wide open) and `child.pid`
+ * does not exist UNTIL AFTER it. `skills/lock.ts::tryCreate` writes its payload
+ * at create time, so a literal mirror can only ever write the parent's. Hence
+ * two phases: this call, then `adoptChild(child.pid)` the moment `execFile`
+ * returns.
+ *
+ * The window between them is SAFE rather than merely narrow: a crash inside it
+ * leaves a lock naming a DEAD PARENT, which is exactly the case the liveness
+ * probe below already reclaims.
+ */
+export declare function tryAcquireInstallLock(opts?: InstallLockOptions): InstallLockHandle | null;