@hwip/cli 0.0.1 → 0.1.0

package/dist/jsonc-doc.js

@@ -0,0 +1,354 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JsoncDoc = exports.parseJsonc = exports.JsoncEditError = exports.JsoncNotObjectError = exports.JsoncSyntaxError = void 0;
+const node_util_1 = require("node:util");
+const jsonc_parser_1 = require("jsonc-parser");
+/**
+ * An agent's settings file read as JSONC — comments and trailing commas allowed,
+ * the way the agents themselves read them — and changed by small edits to its
+ * text, so what the user wrote around hwip's entries (comments, their ordering,
+ * their indentation) stays exactly as it was. `jsonc-parser` (Microsoft, the
+ * parser VS Code uses for its own settings) does the parsing and the edits;
+ * this file only fixes the conventions hwip needs on top of it.
+ *
+ * Plain JSON is a subset, so a file without comments is read and edited the
+ * same way. A file with a syntax error is not read at all (`JsoncSyntaxError`):
+ * editing around a broken part could write something worse.
+ *
+ * Every edit is checked: the text after it must read back as exactly the value
+ * the edit was meant to produce. The library gets that wrong in places — removing
+ * an item of an array whose last two items share a line joins them into one or
+ * breaks the brackets — and a settings file that agents read must never be left
+ * like that. A file with
+ * no comments is then written whole from the intended value (nothing of the
+ * user's is lost); one with comments is left unchanged and the edit throws
+ * (`JsoncEditError`).
+ */
+class JsoncSyntaxError extends Error {
+    constructor() {
+        super('not valid JSON (comments and trailing commas are fine, anything else is not)');
+        this.name = 'JsoncSyntaxError';
+    }
+}
+exports.JsoncSyntaxError = JsoncSyntaxError;
+/** Valid JSONC, but the value is a list, a string, `null` — not a settings object. */
+class JsoncNotObjectError extends Error {
+    constructor() {
+        super('does not hold a JSON object');
+        this.name = 'JsoncNotObjectError';
+    }
+}
+exports.JsoncNotObjectError = JsoncNotObjectError;
+// jsonc-parser's `SyntaxKind` is a const enum, which this build cannot import (isolatedModules).
+const SYNTAX_LINE_COMMENT = 12;
+const SYNTAX_BLOCK_COMMENT = 13;
+const SYNTAX_EOF = 17;
+/** An edit the library could not apply correctly to a file whose comments a rewrite would lose. */
+class JsoncEditError extends Error {
+    constructor() {
+        super('could not be edited without risking its comments');
+        this.name = 'JsoncEditError';
+    }
+}
+exports.JsoncEditError = JsoncEditError;
+const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** The value of a JSONC text, or `undefined` when it has a syntax error. An empty text is `{}`. */
+const parseJsonc = (text) => {
+    const body = text.replace(/^\uFEFF/, '');
+    if (body.trim() === '')
+        return {};
+    const errors = [];
+    const value = (0, jsonc_parser_1.parse)(body, errors, { allowTrailingComma: true });
+    return errors.length > 0 ? undefined : value;
+};
+exports.parseJsonc = parseJsonc;
+/** The indentation and line ending the file already uses, so an inserted entry looks like its neighbours. */
+const formattingOf = (body) => {
+    const eol = body.includes('\r\n') ? '\r\n' : '\n';
+    const indent = /^([ \t]+)\S/m.exec(body)?.[1];
+    if (indent?.startsWith('\t'))
+        return { insertSpaces: false, tabSize: 1, eol };
+    return { insertSpaces: true, tabSize: indent ? Math.min(indent.length, 8) : 2, eol };
+};
+/**
+ * A copy of `data` with `change` applied to the container that holds `path`'s last
+ * segment, missing containers on the way created as objects — the value an edit is
+ * meant to leave behind, to check the text against.
+ */
+const valueAfter = (data, path, change) => {
+    const copy = structuredClone(data);
+    let container = copy;
+    for (const segment of path.slice(0, -1)) {
+        if (!isPlainObject(container[segment]) && !Array.isArray(container[segment]))
+            container[segment] = {};
+        container = container[segment];
+    }
+    change(container, path[path.length - 1]);
+    return copy;
+};
+class JsoncDoc {
+    bom;
+    body;
+    formatting;
+    /** What the file held when it was read (null: there was no file), for `replaceFile` to check before it writes. */
+    expected;
+    /**
+     * `text` is a settings file's content; throws `JsoncSyntaxError`, or `JsoncNotObjectError` when it is valid but not an object.
+     * `existed` is false for a file that was not there (`text` is then empty).
+     */
+    constructor(text, existed = true) {
+        this.expected = existed ? text : null;
+        this.bom = text.startsWith('\uFEFF') ? '\uFEFF' : '';
+        const stripped = text.slice(this.bom.length);
+        const value = (0, exports.parseJsonc)(stripped);
+        if (value === undefined)
+            throw new JsoncSyntaxError();
+        if (!isPlainObject(value))
+            throw new JsoncNotObjectError();
+        // An empty file is a new one: edits need a document to land in.
+        this.body = stripped.trim() === '' ? '{}' : stripped;
+        this.formatting = formattingOf(this.body);
+    }
+    /** The text without an entry that shares its line (a compact array or object), or null when a comment sits in the way. */
+    withoutInline(unit, siblings) {
+        const i = siblings.indexOf(unit);
+        const end = unit.offset + unit.length;
+        const between = (from, to) => this.body.slice(from, to);
+        const bare = (text) => /^[\s,]*$/.test(text);
+        const next = siblings[i + 1];
+        if (next) {
+            // Up to the next entry: the entry, its comma and the space after it.
+            return bare(between(end, next.offset)) ? between(0, unit.offset) + between(next.offset, this.body.length) : null;
+        }
+        const before = siblings[i - 1];
+        const close = (unit.parent?.offset ?? 0) + (unit.parent?.length ?? 0) - 1;
+        // The only entry: everything from it to the closing bracket, its trailing comma included.
+        if (!before)
+            return bare(between(end, close)) ? between(0, unit.offset) + between(close, this.body.length) : null;
+        // The last of several: from the end of the one before (its comma goes) to this one's end; a trailing comma stays.
+        const beforeEnd = before.offset + before.length;
+        return bare(between(beforeEnd, unit.offset)) && bare(between(end, close))
+            ? between(0, beforeEnd) + between(end, this.body.length)
+            : null;
+    }
+    /** Would removing the entry at `path` take a comment with it (one inside the entry, or at the end of its last line)? */
+    removalTakesComment(path) {
+        const zone = this.removalZone(path);
+        return !!zone && JsoncDoc.commentsIn(this.body).some((c) => c.offset >= zone[0] && c.offset < zone[1]);
+    }
+    /** Does the text hold a comment? (Not one inside a string: the scanner knows tokens.) */
+    hasComments() {
+        const scanner = (0, jsonc_parser_1.createScanner)(this.body, false);
+        for (let kind = scanner.scan(); kind !== SYNTAX_EOF; kind = scanner.scan()) {
+            if (kind === SYNTAX_LINE_COMMENT || kind === SYNTAX_BLOCK_COMMENT)
+                return true;
+        }
+        return false;
+    }
+    /** Every comment in `text` with where it starts, in order. */
+    static commentsIn(text) {
+        const scanner = (0, jsonc_parser_1.createScanner)(text, false);
+        const found = [];
+        for (let kind = scanner.scan(); kind !== SYNTAX_EOF; kind = scanner.scan()) {
+            if (kind === SYNTAX_LINE_COMMENT || kind === SYNTAX_BLOCK_COMMENT)
+                found.push({ text: text.slice(scanner.getTokenOffset(), scanner.getTokenOffset() + scanner.getTokenLength()), offset: scanner.getTokenOffset() });
+        }
+        return found;
+    }
+    /**
+     * Did `next` lose a comment of the current text that was not inside `allowed`
+     * (a range of the current text: what the edit may take with it)? The library
+     * drops comments around a removed entry it has no right to; a copy of the same
+     * text elsewhere does not stand in for a lost one.
+     */
+    losesComment(next, allowed) {
+        const left = new Map();
+        for (const c of JsoncDoc.commentsIn(next))
+            left.set(c.text, (left.get(c.text) ?? 0) + 1);
+        const inAllowed = (offset) => !!allowed && offset >= allowed[0] && offset < allowed[1];
+        // Comments outside the allowed range claim their survivors first.
+        const before = JsoncDoc.commentsIn(this.body);
+        for (const c of [...before.filter((x) => !inAllowed(x.offset)), ...before.filter((x) => inAllowed(x.offset))]) {
+            const count = left.get(c.text) ?? 0;
+            if (count > 0)
+                left.set(c.text, count - 1);
+            else if (!inAllowed(c.offset))
+                return true;
+        }
+        return false;
+    }
+    /** Take `next` as the new text if it reads back as `expected` and loses no comment but those in `allowed`; else see the class comment. */
+    commit(next, expected, allowed = null) {
+        if ((0, node_util_1.isDeepStrictEqual)((0, exports.parseJsonc)(next), expected) && !this.losesComment(next, allowed)) {
+            this.body = next;
+            return;
+        }
+        if (this.hasComments())
+            throw new JsoncEditError();
+        this.body = JSON.stringify(expected, null, this.formatting.insertSpaces === false ? '\t' : ' '.repeat(this.formatting.tabSize ?? 2));
+    }
+    /** The current value, read again after every edit. */
+    get data() {
+        return (0, exports.parseJsonc)(this.body);
+    }
+    /** Set `path` to `value`, creating what is missing on the way. */
+    set(path, value) {
+        const expected = valueAfter(this.data, path, (container, key) => {
+            container[key] = value;
+        });
+        const tree = (0, jsonc_parser_1.parseTree)(this.body, [], { allowTrailingComma: true });
+        const existing = tree ? (0, jsonc_parser_1.findNodeAtLocation)(tree, path) : undefined;
+        if (tree && !existing) {
+            // A new property goes after the last one — and after the comment on its line.
+            const key = path[path.length - 1];
+            const parent = (0, jsonc_parser_1.findNodeAtLocation)(tree, path.slice(0, -1));
+            const text = parent?.type === 'object' && typeof key === 'string'
+                ? this.insertLast(parent, `${JSON.stringify(key)}: ${this.render(value)}`)
+                : null;
+            if (text !== null) {
+                this.refuseAdoptedComment(text, path);
+                return this.commit(text, expected);
+            }
+        }
+        // A value that is replaced may take the comments inside it along.
+        const replaced = existing ? [existing.offset, existing.offset + existing.length] : null;
+        const next = (0, jsonc_parser_1.applyEdits)(this.body, (0, jsonc_parser_1.modify)(this.body, path, value, { formattingOptions: this.formatting }));
+        if (!existing)
+            this.refuseAdoptedComment(next, path);
+        this.commit(next, expected, replaced);
+    }
+    /** Remove the property or array item at `path`. A comment right next to it goes with it. */
+    remove(path) {
+        const expected = valueAfter(this.data, path, (container, key) => {
+            if (Array.isArray(container))
+                container.splice(key, 1);
+            else
+                delete container[key];
+        });
+        const lines = this.withoutLines(path);
+        this.commit(lines ?? (0, jsonc_parser_1.applyEdits)(this.body, (0, jsonc_parser_1.modify)(this.body, path, undefined, { formattingOptions: this.formatting })), expected, this.removalZone(path));
+    }
+    /**
+     * What removing the entry at `path` may take with it: the entry itself and the
+     * comment at the end of its last line — not one above it, nor one after the
+     * closing bracket of its container, which are not this entry's.
+     */
+    removalZone(path) {
+        const tree = (0, jsonc_parser_1.parseTree)(this.body, [], { allowTrailingComma: true });
+        const node = tree ? (0, jsonc_parser_1.findNodeAtLocation)(tree, path) : undefined;
+        const unit = node?.parent?.type === 'property' ? node.parent : node;
+        const siblings = unit?.parent?.children;
+        if (!unit || !siblings)
+            return null;
+        const lineEndAfter = (at) => {
+            const nl = this.body.indexOf('\n', at);
+            return nl < 0 ? this.body.length : nl + 1;
+        };
+        const after = siblings[siblings.indexOf(unit) + 1];
+        const end = unit.offset + unit.length;
+        return [unit.offset, Math.min(lineEndAfter(end), after?.offset ?? unit.parent.offset + unit.parent.length - 1)];
+    }
+    /**
+     * The text without the lines of the entry at `path`, when it stands on lines of
+     * its own: its own comment and comma go with it, and so does the comma before it
+     * when it was the last one. A comment on another line, or on the line of the
+     * entry before, stays — the library would take the comment next to the entry
+     * along. An entry that shares its line with others goes through `withoutInline`.
+     */
+    withoutLines(path) {
+        const tree = (0, jsonc_parser_1.parseTree)(this.body, [], { allowTrailingComma: true });
+        const node = tree ? (0, jsonc_parser_1.findNodeAtLocation)(tree, path) : undefined;
+        const unit = node?.parent?.type === 'property' ? node.parent : node;
+        const siblings = unit?.parent?.children;
+        if (!unit || !siblings)
+            return null;
+        const lineStart = this.body.lastIndexOf('\n', unit.offset - 1) + 1;
+        const end = unit.offset + unit.length;
+        if (/\S/.test(this.body.slice(lineStart, unit.offset)))
+            return this.withoutInline(unit, siblings);
+        const rest = /^[ \t]*(,)?[ \t]*(?:\/\/[^\r\n]*|\/\*[^\r\n]*?\*\/)?[ \t]*(?:\r?\n|$)/.exec(this.body.slice(end));
+        if (!rest)
+            return this.withoutInline(unit, siblings);
+        const without = this.body.slice(0, lineStart) + this.body.slice(end + rest[0].length);
+        const before = siblings[siblings.indexOf(unit) - 1];
+        if (rest[1] !== undefined || !before)
+            return without;
+        // The last entry, in a file that writes no trailing comma: the one before it loses its comma.
+        const beforeEnd = before.offset + before.length;
+        const comma = /^[ \t]*,/.exec(this.body.slice(beforeEnd));
+        return comma ? without.slice(0, beforeEnd + comma[0].length - 1) + without.slice(beforeEnd + comma[0].length) : null;
+    }
+    /** Add `value` at the end of the array at `path`, after the comment on the last item's line. */
+    append(path, value) {
+        const expected = valueAfter(this.data, path, (container, key) => {
+            const list = container[key];
+            if (!Array.isArray(list))
+                throw new Error('not a list');
+            list.push(value);
+        });
+        const tree = (0, jsonc_parser_1.parseTree)(this.body, [], { allowTrailingComma: true });
+        const array = tree ? (0, jsonc_parser_1.findNodeAtLocation)(tree, path) : undefined;
+        const text = array?.type === 'array' ? this.insertLast(array, this.render(value)) : null;
+        const added = [...path, array?.children?.length ?? 0];
+        if (text !== null) {
+            this.refuseAdoptedComment(text, added);
+            return this.commit(text, expected);
+        }
+        const next = (0, jsonc_parser_1.applyEdits)(this.body, (0, jsonc_parser_1.modify)(this.body, [...path, -1], value, { formattingOptions: this.formatting, isArrayInsertion: true }));
+        this.refuseAdoptedComment(next, added);
+        this.commit(next, expected);
+    }
+    /**
+     * The library's insert can leave a comment of the user's on the line of the new
+     * entry, and an uninstall would take it away with the entry (it is the entry's
+     * "own" comment by position). A new entry must have no comment in its removal
+     * zone; otherwise fail now, naming the file, and leave the text alone.
+     */
+    refuseAdoptedComment(next, path) {
+        if (!this.hasComments())
+            return;
+        const after = new JsoncDoc(next);
+        if (after.removalTakesComment(path))
+            throw new JsoncEditError();
+    }
+    /** `value` as JSON text in the file's own indentation unit. */
+    render(value) {
+        const unit = this.formatting.insertSpaces === false ? '\t' : ' '.repeat(this.formatting.tabSize ?? 2);
+        return JSON.stringify(value, null, unit);
+    }
+    /**
+     * The text with `childText` put after the last child of an object or array, on a
+     * line of its own at the last child's indentation; null for an empty container
+     * or one whose last child shares its line with something else (the caller falls
+     * back). The library's insert would re-indent the siblings and move a comment at
+     * the end of the last child's line onto the new child.
+     */
+    insertLast(container, childText) {
+        const children = container.children ?? [];
+        const last = children[children.length - 1];
+        if (!last)
+            return null;
+        const lineStart = this.body.lastIndexOf('\n', last.offset - 1) + 1;
+        const before = this.body.slice(lineStart, last.offset);
+        if (/\S/.test(before))
+            return null;
+        const lastEnd = last.offset + last.length;
+        const close = container.offset + container.length - 1;
+        const tail = /^[ \t]*(,)?[ \t]*(\/\/[^\r\n]*|\/\*[^]*?\*\/)?/.exec(this.body.slice(lastEnd, close));
+        const hasComma = tail[1] !== undefined;
+        const at = lastEnd + tail[0].length;
+        // A comment that the closing bracket follows on its line would be left between the two entries.
+        if (tail[2] && !this.body.slice(at, close).includes('\n'))
+            return null;
+        const eol = this.formatting.eol ?? '\n';
+        // `childText` came in indented from its own first line: move it under the last child.
+        const text = childText.replace(/\r?\n/g, `${eol}${before}`);
+        const withNew = this.body.slice(0, at) + `${eol}${before}${text}${hasComma ? ',' : ''}` + this.body.slice(at);
+        return hasComma ? withNew : withNew.slice(0, lastEnd) + ',' + withNew.slice(lastEnd);
+    }
+    /** The file's new text: its byte order mark kept, one line ending at the end. */
+    text() {
+        return this.bom + this.body.trimEnd() + (this.formatting.eol ?? '\n');
+    }
+}
+exports.JsoncDoc = JsoncDoc;

package/dist/keep-awake.d.ts

@@ -0,0 +1,32 @@
+import { spawn } from 'node:child_process';
+/**
+ * Keep the host awake while the listener runs — macOS only.
+ *
+ * The listener holds an OUTBOUND WebSocket. macOS "Wake for network access"
+ * only wakes the machine for inbound requests to Bonjour-advertised services,
+ * so it does nothing for us: when the Mac idle-sleeps, the socket dies and the
+ * phone sits on "Waiting for the live stream…" until the lid is opened. On a
+ * machine that runs Claude Code this is masked — the agent spawns
+ * `caffeinate -i -t 300` while a turn is running — which is why one Mac looks
+ * fine and another, idling at a prompt, keeps dropping.
+ *
+ * `caffeinate -s -w <pid>`: `-s` blocks system sleep and is honoured ONLY on
+ * AC power (macOS drops the assertion on battery, so this never drains a
+ * laptop); `-w` releases it the moment our pid exits, so a crashed daemon
+ * leaves no orphan holding the machine up. The display still sleeps; a closed
+ * lid still sleeps — those are the user's call, not ours.
+ */
+export interface KeepAwakeOptions {
+    /** `false` = `--no-keep-awake` / `"keepAwake": false` in config. */
+    enabled: boolean;
+    log: (msg: string) => void;
+    platform?: NodeJS.Platform;
+    pid?: number;
+    spawnFn?: typeof spawn;
+}
+export interface KeepAwake {
+    /** Release the assertion now rather than at process exit. Idempotent. */
+    stop: () => void;
+}
+export declare const startKeepAwake: (opts: KeepAwakeOptions) => KeepAwake;
+//# sourceMappingURL=keep-awake.d.ts.map

package/dist/keep-awake.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startKeepAwake = void 0;
+const node_child_process_1 = require("node:child_process");
+const NOOP = { stop: () => undefined };
+const startKeepAwake = (opts) => {
+    if (!opts.enabled) {
+        opts.log('keep-awake: off — the Mac may idle-sleep and drop the socket');
+        return NOOP;
+    }
+    if ((opts.platform ?? process.platform) !== 'darwin')
+        return NOOP;
+    const pid = opts.pid ?? process.pid;
+    const spawnFn = opts.spawnFn ?? node_child_process_1.spawn;
+    const child = spawnFn('caffeinate', ['-s', '-w', String(pid)], { stdio: 'ignore' });
+    let stopped = false;
+    // ENOENT and friends arrive here, asynchronously — spawn itself does not
+    // throw for a missing binary. Not fatal: the listener works without it,
+    // the machine just sleeps like it did before.
+    child.on('error', (err) => {
+        stopped = true;
+        opts.log(`! keep-awake: caffeinate unavailable (${err.message}) — the Mac may idle-sleep and drop the socket`);
+    });
+    child.on('exit', (code, signal) => {
+        if (stopped)
+            return;
+        stopped = true;
+        opts.log(`! keep-awake: caffeinate exited early (${code ?? signal}) — the Mac may idle-sleep and drop the socket`);
+    });
+    // Never keep the event loop alive on the child's account: the daemon's
+    // lifetime is the socket loop's, and `-w` ties caffeinate to it anyway.
+    child.unref();
+    // Held with no agent session open too: the phone resumes a past session
+    // or starts one only while this Mac is awake to answer (C25 — say so
+    // rather than let the Mac's sleeplessness go unexplained).
+    opts.log(`keep-awake: caffeinate -s -w ${pid} — blocks idle sleep on AC power only, even with no agent session open, so the phone can resume one (--no-keep-awake to disable)`);
+    return {
+        stop: () => {
+            if (stopped)
+                return;
+            stopped = true;
+            child.kill();
+        },
+    };
+};
+exports.startKeepAwake = startKeepAwake;

package/dist/key-changes.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Devices whose key changed since this computer pinned them, kept until a person has been shown it.
+ *
+ * Whoever replaces a pin — `hwip notify`, `hwip ask`, `hwip agent send`, the listener, the MCP server — writes the
+ * change here, under the trust file's lock (`trust-lock.ts`). Their own output often reaches nobody (a hook's
+ * `2>/dev/null`, the daemon log, an MCP server's stderr), and once the pin holds the new key no one sees the change
+ * again. So it waits beside the pins until a surface a person reads takes it: a cli command at a terminal, the
+ * plugin's SessionStart and /hwip-mode, an MCP tool result.
+ *
+ * THE CONTRACT (cli and mcp-server write and read it, the plugin reads it — changing it is a cross-repo change):
+ *
+ *   path  key-changes.json beside trusted-devices.json (~/.hwip/key-changes.json), 0600
+ *   body  {"v":1,"changes":[{"deviceId":"<device id>","at":"<ISO 8601 UTC>","name":"<nickname, optional>"}]}
+ *         one entry per device, updated in place; at most 64, the oldest dropped
+ *   take  under the same lock as the writers (trusted-devices.lock), rename to key-changes.json.<pid>.taken, read,
+ *         delete: a writer cannot put back what was taken, and of two readers only the one whose rename wins shows
+ *         the changes. A record that does not parse, or another `v`, reads as none.
+ */
+export interface KeyChange {
+    deviceId: string;
+    /** When the pin was replaced, ISO 8601 UTC. */
+    at: string;
+    /** The device's nickname as the account lists it. */
+    name?: string;
+}
+export declare const MAX_KEY_CHANGES = 64;
+export declare const keyChangesPath: (trustPath: string) => string;
+/**
+ * Add `changes` to the record. Call it inside the `withTrustLock` section that replaced the pins: that lock is what
+ * keeps two writers from dropping each other's entry, and a taker from seeing an entry twice. Throws nothing: false
+ * means the record could not be written, and the caller says so — nothing else will.
+ */
+export declare const recordKeyChanges: (trustPath: string, changes: KeyChange[]) => boolean;
+/** The changes nobody has been shown yet, and the record gone. A lock that cannot be had leaves the record for the next surface. */
+export declare const takeKeyChanges: (trustPath: string, opts?: {
+    waitMs?: number;
+}) => KeyChange[];
+/** One line for a person; the caller adds its prefix. */
+export declare const describeKeyChange: (change: KeyChange) => string;
+/**
+ * Show the recorded changes on stderr and clear them — only when stderr is a terminal. A hook runs `hwip notify …
+ * 2>/dev/null`; taking the record there would lose it unseen, so it is left for the plugin to show.
+ */
+export declare const showKeyChanges: (trustPath: string, stderr: {
+    isTTY?: boolean;
+    write: (text: string) => unknown;
+}) => void;
+//# sourceMappingURL=key-changes.d.ts.map

package/dist/key-changes.js

@@ -0,0 +1,140 @@
+"use strict";
+/**
+ * Devices whose key changed since this computer pinned them, kept until a person has been shown it.
+ *
+ * Whoever replaces a pin — `hwip notify`, `hwip ask`, `hwip agent send`, the listener, the MCP server — writes the
+ * change here, under the trust file's lock (`trust-lock.ts`). Their own output often reaches nobody (a hook's
+ * `2>/dev/null`, the daemon log, an MCP server's stderr), and once the pin holds the new key no one sees the change
+ * again. So it waits beside the pins until a surface a person reads takes it: a cli command at a terminal, the
+ * plugin's SessionStart and /hwip-mode, an MCP tool result.
+ *
+ * THE CONTRACT (cli and mcp-server write and read it, the plugin reads it — changing it is a cross-repo change):
+ *
+ *   path  key-changes.json beside trusted-devices.json (~/.hwip/key-changes.json), 0600
+ *   body  {"v":1,"changes":[{"deviceId":"<device id>","at":"<ISO 8601 UTC>","name":"<nickname, optional>"}]}
+ *         one entry per device, updated in place; at most 64, the oldest dropped
+ *   take  under the same lock as the writers (trusted-devices.lock), rename to key-changes.json.<pid>.taken, read,
+ *         delete: a writer cannot put back what was taken, and of two readers only the one whose rename wins shows
+ *         the changes. A record that does not parse, or another `v`, reads as none.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.showKeyChanges = exports.describeKeyChange = exports.takeKeyChanges = exports.recordKeyChanges = exports.keyChangesPath = exports.MAX_KEY_CHANGES = void 0;
+const node_fs_1 = require("node:fs");
+const node_crypto_1 = require("node:crypto");
+const node_path_1 = require("node:path");
+const private_files_js_1 = require("./private-files.js");
+const subscriber_trust_js_1 = require("./subscriber-trust.js");
+const trust_lock_js_1 = require("./trust-lock.js");
+exports.MAX_KEY_CHANGES = 64;
+const NAME_MAX = 80;
+const ISO_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/;
+const keyChangesPath = (trustPath) => (0, node_path_1.join)((0, node_path_1.dirname)(trustPath), 'key-changes.json');
+exports.keyChangesPath = keyChangesPath;
+/** The relay writes nicknames: no control, direction or zero-width characters, one space per run, 80 characters at most. */
+const cleanName = (name) => {
+    if (typeof name !== 'string')
+        return undefined;
+    const plain = name.replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]|\p{Cf}/gu, '').replace(/\s+/g, ' ').trim();
+    const chars = Array.from(plain);
+    if (chars.length === 0)
+        return undefined;
+    return chars.length > NAME_MAX ? chars.slice(0, NAME_MAX).join('') : plain;
+};
+const entryOf = (raw) => {
+    if (typeof raw !== 'object' || raw === null)
+        return null;
+    const { deviceId, at, name } = raw;
+    if (typeof deviceId !== 'string' || !subscriber_trust_js_1.DEVICE_ID.test(deviceId) || typeof at !== 'string' || !ISO_UTC.test(at))
+        return null;
+    const clean = cleanName(name);
+    return clean === undefined ? { deviceId, at } : { deviceId, at, name: clean };
+};
+const readChanges = (path) => {
+    let raw;
+    try {
+        raw = JSON.parse((0, node_fs_1.readFileSync)(path, 'utf-8'));
+    }
+    catch {
+        return [];
+    }
+    const { v, changes } = (raw ?? {});
+    if (v !== 1 || !Array.isArray(changes))
+        return [];
+    return changes.map(entryOf).filter((c) => c !== null).slice(-exports.MAX_KEY_CHANGES);
+};
+/**
+ * Add `changes` to the record. Call it inside the `withTrustLock` section that replaced the pins: that lock is what
+ * keeps two writers from dropping each other's entry, and a taker from seeing an entry twice. Throws nothing: false
+ * means the record could not be written, and the caller says so — nothing else will.
+ */
+const recordKeyChanges = (trustPath, changes) => {
+    if (changes.length === 0)
+        return true;
+    const path = (0, exports.keyChangesPath)(trustPath);
+    const list = readChanges(path);
+    for (const change of changes) {
+        const entry = entryOf(change);
+        if (!entry)
+            continue;
+        const at = list.findIndex((c) => c.deviceId === entry.deviceId);
+        if (at >= 0)
+            list[at] = entry;
+        else
+            list.push(entry);
+    }
+    const temp = `${path}.${process.pid}.${(0, node_crypto_1.randomBytes)(6).toString('hex')}.tmp`;
+    try {
+        (0, private_files_js_1.mkdirHandedBack)((0, node_path_1.dirname)(path), 0o700);
+        (0, node_fs_1.writeFileSync)(temp, `${JSON.stringify({ v: 1, changes: list.slice(-exports.MAX_KEY_CHANGES) })}\n`, { mode: 0o600, flag: 'wx' });
+        (0, private_files_js_1.handBackToSudoUser)(temp);
+        (0, node_fs_1.renameSync)(temp, path);
+        return true;
+    }
+    catch {
+        try {
+            (0, node_fs_1.rmSync)(temp, { force: true });
+        }
+        catch { /* the folder is not there either */ }
+        return false;
+    }
+};
+exports.recordKeyChanges = recordKeyChanges;
+const takeRecord = (path) => {
+    const taken = `${path}.${process.pid}.taken`;
+    try {
+        (0, node_fs_1.renameSync)(path, taken);
+    }
+    catch {
+        return [];
+    }
+    try {
+        return readChanges(taken);
+    }
+    finally {
+        (0, node_fs_1.rmSync)(taken, { force: true });
+    }
+};
+/** The changes nobody has been shown yet, and the record gone. A lock that cannot be had leaves the record for the next surface. */
+const takeKeyChanges = (trustPath, opts = {}) => {
+    const path = (0, exports.keyChangesPath)(trustPath);
+    // Most commands find nothing: no lock for them.
+    if (!(0, node_fs_1.existsSync)(path))
+        return [];
+    const done = (0, trust_lock_js_1.withTrustLock)(trustPath, () => takeRecord(path), opts);
+    return done.locked ? done.value : [];
+};
+exports.takeKeyChanges = takeKeyChanges;
+/** One line for a person; the caller adds its prefix. */
+const describeKeyChange = (change) => `${change.name ?? change.deviceId} changed its encryption key — the new key is trusted. Not expecting that (app reinstalled?) Check it: hwip trust`;
+exports.describeKeyChange = describeKeyChange;
+/**
+ * Show the recorded changes on stderr and clear them — only when stderr is a terminal. A hook runs `hwip notify …
+ * 2>/dev/null`; taking the record there would lose it unseen, so it is left for the plugin to show.
+ */
+const showKeyChanges = (trustPath, stderr) => {
+    if (stderr.isTTY !== true)
+        return;
+    for (const change of (0, exports.takeKeyChanges)(trustPath))
+        stderr.write(`hwip: ${(0, exports.describeKeyChange)(change)}\n`);
+};
+exports.showKeyChanges = showKeyChanges;