@hwip/cli 0.0.1 → 0.1.0

package/dist/ask-context-switch.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleAskContext = exports.runAskContext = exports.describeAskContext = exports.setAskContext = exports.askContextEnabled = exports.askContextOffBy = exports.askContextProjectDir = void 0;
+const args_js_1 = require("./args.js");
+const project_switch_js_1 = require("./project-switch.js");
+const session_diff_js_1 = require("./session-diff.js");
+const askContext = (0, project_switch_js_1.projectSwitch)('ask-context', 'HWIP_ASK_CONTEXT');
+/** The project a question belongs to: the repository root, else the directory itself, so a question asked from a subfolder reads the same switch. */
+exports.askContextProjectDir = project_switch_js_1.projectDirOf;
+/** Why the context is off for this project, or `null` when it is on. `HWIP_ASK_CONTEXT=0` turns it off for one run. */
+exports.askContextOffBy = askContext.offBy;
+const askContextEnabled = (dir, env = process.env) => (0, exports.askContextOffBy)(dir, env) === null;
+exports.askContextEnabled = askContextEnabled;
+/** Turn the context on or off for this project, or for every project. Throws when the state file cannot be written or removed. */
+exports.setAskContext = askContext.set;
+const REASON = {
+    env: 'HWIP_ASK_CONTEXT is set to off',
+    project: 'turned off for this project',
+    global: 'turned off for every project',
+    unreadable: 'the switch file cannot be read, so it is treated as off',
+};
+const describeAskContext = (offBy) => offBy === null ? 'ask context: on' : `ask context: off (${REASON[offBy]})`;
+exports.describeAskContext = describeAskContext;
+const USAGE = 'Usage: hwip ask-context [status | on | off | show] [--global]';
+const runAskContext = (sub, global, deps) => {
+    const word = sub ?? 'status';
+    if (word !== 'status' && word !== 'on' && word !== 'off') {
+        deps.err(`hwip ask-context: unknown subcommand '${word}'. ${USAGE}`);
+        return 2;
+    }
+    if (global && word === 'status') {
+        deps.err(`hwip ask-context: --global goes with on or off. ${USAGE}`);
+        return 2;
+    }
+    const dir = (0, exports.askContextProjectDir)(deps.cwd(), deps.repoRoot);
+    if (word !== 'status') {
+        try {
+            (0, exports.setAskContext)(dir, word === 'on', global ? 'global' : 'project');
+        }
+        catch (err) {
+            deps.err(`hwip ask-context: could not change the switch: ${err.message}`);
+            return 1;
+        }
+    }
+    deps.out((0, exports.describeAskContext)((0, exports.askContextOffBy)(dir, deps.env)));
+    return 0;
+};
+exports.runAskContext = runAskContext;
+/**
+ * `show` prints, as one JSON line, what a question asked from this directory would carry: `{ context, off? }`
+ * (`collectAskContext`). It reads the switch itself, so a caller that only seals (mcp-server's `hwip_ask`) needs
+ * no switch logic of its own. Nothing is sent.
+ */
+const handleAskContext = async (args) => {
+    if (args._arg1 === 'show') {
+        if ((0, args_js_1.flagOn)(args, 'global')) {
+            console.error(`hwip ask-context: --global goes with on or off. ${USAGE}`);
+            return 2;
+        }
+        const { collectAskContext } = await import('./ask-context-attach.js');
+        const line = `${JSON.stringify(await collectAskContext(process.cwd(), process.env))}\n`;
+        // The caller exits right after: a pipe on macOS is written asynchronously, and 64 KiB would be cut short.
+        await new Promise((resolve, reject) => process.stdout.write(line, (err) => (err ? reject(err) : resolve())));
+        return 0;
+    }
+    return (0, exports.runAskContext)(typeof args._arg1 === 'string' && args._arg1 ? args._arg1 : undefined, (0, args_js_1.flagOn)(args, 'global'), {
+        cwd: () => process.cwd(),
+        out: (line) => console.log(line),
+        err: (line) => console.error(line),
+        env: process.env,
+        repoRoot: session_diff_js_1.repoRootOf,
+    });
+};
+exports.handleAskContext = handleAskContext;

package/dist/ask-context.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The context a sealed question could carry: what the session changed (git diff against HEAD) and what its
+ * terminal shows, masked and held to one size. Nothing here sends anything or touches a wire; a caller that
+ * seals the result owns that. The git half reuses `session-diff.ts` (which keeps `.gitignore`d files, filtered
+ * files and oversized trees out) and the masking half reuses `secret-mask.ts` — there is no git or mask logic
+ * of its own.
+ *
+ * Two parts, because they travel differently: `summary` is small and rides in a sealed body, `original` is the
+ * text itself and is sized for one sealed attachment.
+ */
+import { type DiffFileEntry, type DiffResult } from './session-diff.js';
+/** What `original` may weigh once serialized as JSON, in bytes. */
+export declare const ASK_CONTEXT_MAX_BYTES: number;
+/** Lines of the terminal screen that are kept (the last ones). */
+export declare const ASK_CONTEXT_SCREEN_LINES = 60;
+/** What the screen may weigh once serialized as JSON, in bytes. */
+export declare const ASK_CONTEXT_SCREEN_MAX_BYTES: number;
+/** Files the summary lists by name. */
+export declare const ASK_CONTEXT_SUMMARY_FILES = 20;
+/** What `summary` may weigh once serialized as JSON, in bytes; listed files past it are counted in `moreFiles` instead. */
+export declare const ASK_CONTEXT_SUMMARY_MAX_BYTES: number;
+/** Lines of the screen that are read and masked before the last ones are picked, so a key block that began above the picked lines still hides. */
+export declare const ASK_CONTEXT_SCREEN_WINDOW_LINES = 500;
+export interface AskContextSummary {
+    /** `ok` the diff half is there; `no_repo` the directory is in no repository; `failed` git could not answer. */
+    diff: 'ok' | 'no_repo' | 'failed';
+    files: number;
+    added: number;
+    removed: number;
+    listed: Array<Pick<DiffFileEntry, 'path' | 'status' | 'added' | 'removed' | 'binary'>>;
+    /** Files changed that are not in `listed`. */
+    moreFiles: number;
+    screenLines: number;
+    /** Secret-looking spots masked in the text that was read (a spot in a cut-off part counts too). */
+    masked: number;
+    /** Whether the diff / the screen holds less than there was (files left out, a patch cut, screen rows scrolled off or dropped). */
+    cut: {
+        diff: boolean;
+        screen: boolean;
+    };
+}
+export interface AskContext {
+    summary: AskContextSummary;
+    original: {
+        diff: string;
+        screen: string;
+    };
+}
+export interface AskContextInput {
+    files: DiffFileEntry[];
+    /** Git had more changed files than `files` holds. */
+    truncated?: boolean;
+    /** One file's masked patch; `null` when it could not be read. An empty text is a file with no patch (binary, filtered). */
+    patchOf: (path: string) => {
+        text: string;
+        masked: number;
+    } | null;
+    /** The terminal screen as captured, not yet masked. */
+    screen: string | null;
+    diff?: AskContextSummary['diff'];
+}
+/** What `original` weighs once serialized. */
+export declare const askContextBytes: (ctx: Pick<AskContext, "original">) => number;
+/** The context for the files changed and the screen shown. Pure: same input, same value, nothing is read or sent. */
+export declare const composeAskContext: (input: AskContextInput) => AskContext;
+export interface GatherDeps {
+    repoRootOf: (cwd: string) => string | null;
+    collectDiffFiles: (root: string, base: 'head') => DiffResult<{
+        files: DiffFileEntry[];
+        truncated: boolean;
+    }>;
+    collectFilePatch: (root: string, base: 'head', path: string) => DiffResult<{
+        text: string;
+        masked: number;
+    }>;
+    now: () => number;
+}
+/**
+ * The context of the session at `cwd`: the changes against HEAD (new files included) and `screen`. `null` when
+ * there is neither a change nor a screen — nothing to carry. A directory outside a repository, or a git that
+ * cannot answer, leaves the screen alone and says so in `summary.diff`.
+ */
+export declare const gatherAskContext: (cwd: string, screen: string | null, overrides?: Partial<GatherDeps>) => AskContext | null;
+//# sourceMappingURL=ask-context.d.ts.map

package/dist/ask-context.js

@@ -0,0 +1,172 @@
+"use strict";
+/**
+ * The context a sealed question could carry: what the session changed (git diff against HEAD) and what its
+ * terminal shows, masked and held to one size. Nothing here sends anything or touches a wire; a caller that
+ * seals the result owns that. The git half reuses `session-diff.ts` (which keeps `.gitignore`d files, filtered
+ * files and oversized trees out) and the masking half reuses `secret-mask.ts` — there is no git or mask logic
+ * of its own.
+ *
+ * Two parts, because they travel differently: `summary` is small and rides in a sealed body, `original` is the
+ * text itself and is sized for one sealed attachment.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gatherAskContext = exports.composeAskContext = exports.askContextBytes = exports.ASK_CONTEXT_SCREEN_WINDOW_LINES = exports.ASK_CONTEXT_SUMMARY_MAX_BYTES = exports.ASK_CONTEXT_SUMMARY_FILES = exports.ASK_CONTEXT_SCREEN_MAX_BYTES = exports.ASK_CONTEXT_SCREEN_LINES = exports.ASK_CONTEXT_MAX_BYTES = void 0;
+const session_diff_js_1 = require("./session-diff.js");
+const secret_mask_js_1 = require("./secret-mask.js");
+/** What `original` may weigh once serialized as JSON, in bytes. */
+exports.ASK_CONTEXT_MAX_BYTES = 64 * 1024;
+/** Lines of the terminal screen that are kept (the last ones). */
+exports.ASK_CONTEXT_SCREEN_LINES = 60;
+/** What the screen may weigh once serialized as JSON, in bytes. */
+exports.ASK_CONTEXT_SCREEN_MAX_BYTES = 8 * 1024;
+/** Files the summary lists by name. */
+exports.ASK_CONTEXT_SUMMARY_FILES = 20;
+/** What `summary` may weigh once serialized as JSON, in bytes; listed files past it are counted in `moreFiles` instead. */
+exports.ASK_CONTEXT_SUMMARY_MAX_BYTES = 4 * 1024;
+/** Longest path the summary shows, in bytes; a longer one is cut (the summary rides in a size-capped body). */
+const SUMMARY_PATH_MAX_BYTES = 128;
+/** Lines of the screen that are read and masked before the last ones are picked, so a key block that began above the picked lines still hides. */
+exports.ASK_CONTEXT_SCREEN_WINDOW_LINES = 500;
+/** How long gathering may spend asking git for patches. */
+const GATHER_BUDGET_MS = 5_000;
+const CUT_MARKER = '[hwip: cut]\n';
+/** Bytes `text` takes inside a JSON string (quotes not counted): newlines, quotes and control characters cost more than one. */
+const jsonBytes = (text) => Buffer.byteLength(JSON.stringify(text)) - 2;
+/** What `original` weighs once serialized. */
+const askContextBytes = (ctx) => Buffer.byteLength(JSON.stringify(ctx.original));
+exports.askContextBytes = askContextBytes;
+/** The last lines of a screen, masked and held to the screen budget. Blank rows under the last text are not lines. */
+const composeScreen = (screen) => {
+    const rows = (screen ?? '').split('\n').map((row) => row.replace(/\r$/, ''));
+    while (rows.length > 0 && rows[rows.length - 1].trim() === '')
+        rows.pop();
+    // Mask the window as a whole before picking its last lines: the BEGIN of a key block may sit above them.
+    const masked = (0, secret_mask_js_1.maskText)(rows.slice(-exports.ASK_CONTEXT_SCREEN_WINDOW_LINES).join('\n'));
+    const kept = masked.text === '' ? [] : masked.text.split('\n').slice(-exports.ASK_CONTEXT_SCREEN_LINES);
+    let bytes = kept.reduce((sum, row) => sum + jsonBytes(row) + 2, -2);
+    let cut = masked.text !== '' && masked.text.split('\n').length > kept.length;
+    while (kept.length > 1 && bytes > exports.ASK_CONTEXT_SCREEN_MAX_BYTES) {
+        bytes -= jsonBytes(kept.shift()) + 2;
+        cut = true;
+    }
+    // One line that is over the budget on its own: its start stays (it is masked already, so a cut leaves no secret's head).
+    if (kept.length === 1 && jsonBytes(kept[0]) > exports.ASK_CONTEXT_SCREEN_MAX_BYTES) {
+        while (jsonBytes(kept[0]) > exports.ASK_CONTEXT_SCREEN_MAX_BYTES)
+            kept[0] = kept[0].slice(0, Math.floor(kept[0].length * 0.9));
+        cut = true;
+    }
+    return { text: kept.join('\n'), lines: kept.length, masked: masked.masked, cut };
+};
+/** `text` up to the last whole line that fits `room` JSON bytes. */
+const wholeLinesWithin = (text, room) => {
+    let used = 0;
+    let end = 0;
+    for (const line of text.match(/[^\n]*\n|[^\n]+$/g) ?? []) {
+        used += jsonBytes(line);
+        if (used > room)
+            break;
+        end += line.length;
+    }
+    return text.slice(0, end);
+};
+/** The patches of the files, in order, up to `budget` JSON bytes; a patch that does not fit is cut at a line and the rest is not asked for. */
+const composeDiff = (input, budget) => {
+    let text = '';
+    let masked = 0;
+    let unread = false;
+    let room = budget - jsonBytes(CUT_MARKER);
+    for (const entry of input.files) {
+        if (room <= 0)
+            return { text: text + CUT_MARKER, masked, cut: true };
+        const patch = input.patchOf(entry.path);
+        if (!patch) {
+            unread = true;
+            continue;
+        }
+        if (patch.text === '')
+            continue;
+        masked += patch.masked;
+        const whole = patch.text.endsWith('\n') ? patch.text : `${patch.text}\n`;
+        if (jsonBytes(whole) <= room) {
+            text += whole;
+            room -= jsonBytes(whole);
+            continue;
+        }
+        return { text: text + wholeLinesWithin(whole, room) + CUT_MARKER, masked, cut: true };
+    }
+    return { text, masked, cut: unread };
+};
+/** A path over the limit is cut between characters and marked with `…`; the mark counts, so what is shown never passes `SUMMARY_PATH_MAX_BYTES` (the reader of the summary refuses a longer one). */
+const summaryPath = (path) => {
+    if (Buffer.byteLength(path) <= SUMMARY_PATH_MAX_BYTES)
+        return path;
+    const room = SUMMARY_PATH_MAX_BYTES - Buffer.byteLength('…');
+    let kept = '';
+    let bytes = 0;
+    for (const char of path) {
+        bytes += Buffer.byteLength(char);
+        if (bytes > room)
+            break;
+        kept += char;
+    }
+    return `${kept}…`;
+};
+/** The context for the files changed and the screen shown. Pure: same input, same value, nothing is read or sent. */
+const composeAskContext = (input) => {
+    const screen = composeScreen(input.screen);
+    const room = exports.ASK_CONTEXT_MAX_BYTES - (0, exports.askContextBytes)({ original: { diff: '', screen: screen.text } });
+    const diff = composeDiff(input, room);
+    const listed = input.files.slice(0, exports.ASK_CONTEXT_SUMMARY_FILES).map((f) => ({
+        path: summaryPath(f.path),
+        status: f.status,
+        added: f.added,
+        removed: f.removed,
+        ...(f.binary ? { binary: true } : {}),
+    }));
+    const added = input.files.reduce((sum, f) => sum + f.added, 0);
+    const removed = input.files.reduce((sum, f) => sum + f.removed, 0);
+    const summaryWith = (count) => ({
+        diff: input.diff ?? 'ok',
+        files: input.files.length,
+        added,
+        removed,
+        listed: listed.slice(0, count),
+        moreFiles: input.files.length - count,
+        screenLines: screen.lines,
+        masked: diff.masked + screen.masked,
+        cut: { diff: diff.cut || input.truncated === true, screen: screen.cut },
+    });
+    // A path of escapes (control characters cost six bytes each in JSON) can take the list far past its budget.
+    let count = listed.length;
+    while (count > 0 && Buffer.byteLength(JSON.stringify(summaryWith(count))) > exports.ASK_CONTEXT_SUMMARY_MAX_BYTES)
+        count -= 1;
+    return { summary: summaryWith(count), original: { diff: diff.text, screen: screen.text } };
+};
+exports.composeAskContext = composeAskContext;
+const LIVE_DEPS = { repoRootOf: session_diff_js_1.repoRootOf, collectDiffFiles: session_diff_js_1.collectDiffFiles, collectFilePatch: session_diff_js_1.collectFilePatch, now: Date.now };
+/**
+ * The context of the session at `cwd`: the changes against HEAD (new files included) and `screen`. `null` when
+ * there is neither a change nor a screen — nothing to carry. A directory outside a repository, or a git that
+ * cannot answer, leaves the screen alone and says so in `summary.diff`.
+ */
+const gatherAskContext = (cwd, screen, overrides = {}) => {
+    const deps = { ...LIVE_DEPS, ...overrides };
+    const root = deps.repoRootOf(cwd);
+    const listing = root ? deps.collectDiffFiles(root, 'head') : null;
+    const diff = !root ? 'no_repo' : listing?.ok ? 'ok' : 'failed';
+    const gaveUp = deps.now() + GATHER_BUDGET_MS;
+    const ctx = (0, exports.composeAskContext)({
+        files: listing?.ok ? listing.files : [],
+        truncated: listing?.ok ? listing.truncated : false,
+        patchOf: (path) => {
+            if (!root || deps.now() > gaveUp)
+                return null;
+            const patch = deps.collectFilePatch(root, 'head', path);
+            return patch.ok ? { text: patch.text, masked: patch.masked } : null;
+        },
+        screen,
+        diff,
+    });
+    return ctx.summary.files === 0 && ctx.original.screen === '' ? null : ctx;
+};
+exports.gatherAskContext = gatherAskContext;

package/dist/ask-pending.d.ts

@@ -0,0 +1,47 @@
+/** What makes two asks the same question: the same words, asked from the same place. */
+export interface AskedQuestion {
+    hookId: string;
+    agentDeviceId?: string;
+    agentSessionName?: string;
+    title: string;
+    body?: string;
+    actions?: {
+        id: string;
+        label: string;
+    }[];
+    acceptsExit?: boolean;
+}
+/** A question on the phone: where its answer is read, what opens it, and when its window ends (ms). */
+export interface PendingAsk {
+    eventId: string;
+    askId: string;
+    deadline: number;
+}
+/** One question's place in the store. */
+export interface PendingSlot {
+    /** The question as an earlier run left it, now this process's to wait on; null when there is none to take. */
+    claim(): PendingAsk | null;
+    /** Keep the question this process has just put up. */
+    record(ask: PendingAsk): void;
+    /** The question is over: forget it. False when a record of it is still there, to be read by the next run. */
+    settle(): boolean;
+}
+export interface PendingAsks {
+    of(question: AskedQuestion): PendingSlot;
+}
+export interface PendingDeps {
+    now: () => number;
+    pid: number;
+    alive: (pid: number) => boolean;
+    /** Part of the match: machines that share a home folder do not share a process table. */
+    host: string;
+    cwd: () => string;
+}
+/** The shape of an id as it goes into a URL path and a seal: the server's event ids (`hevt_` + ULID) and ours (base64url). */
+export declare const ID: RegExp;
+export declare const matchKey: (question: AskedQuestion, where: {
+    host: string;
+    cwd: string;
+}) => string;
+export declare const pendingAsks: (dir: string, over?: Partial<PendingDeps>) => PendingAsks;
+//# sourceMappingURL=ask-pending.d.ts.map

package/dist/ask-pending.js

@@ -0,0 +1,221 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pendingAsks = exports.matchKey = exports.ID = void 0;
+/**
+ * The questions `hwip ask` has on the phone, kept so that one cut short can be taken up again.
+ *
+ * `hwip ask` blocks, and what runs it does not always wait: an agent's tool call times out, a shell is
+ * closed. The question stays on the phone and the answer stays on the server, with nobody left to read
+ * it — and asking again puts a second card next to the first. So each question that went up leaves a
+ * record here, and the same command run again from the same place finds it and waits on that question
+ * instead of sending another.
+ *
+ * A record holds where the answer is read and what opens it, and nothing of the wording — not the
+ * buttons' ids either, which a bare `--actions` makes of their labels: the question is matched by a hash. Its file is named for the process that waits on it, so whose it is never has to be
+ * read out of it. It is taken up only once that process has died — two that run side by side each ask
+ * their own — and by one process only: taking is a rename to the taker's own name, which one of them
+ * wins. A record is under some process's name at every moment, and no name is used twice.
+ *
+ * All of it is best effort. State that cannot be read or written costs the taking up, never the ask.
+ */
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const private_files_js_1 = require("./private-files.js");
+/** The first hex digits of the match that name the file: 128 bits. */
+const NAME_HEX = 32;
+const NONCE_HEX = 8;
+const PREFIX = 'ask-pending-';
+/** A record's file: the question, the pid that waits on it, and a nonce that keeps a pid used again from meeting an old name. */
+const RECORD = new RegExp(`^${PREFIX}([0-9a-f]{${NAME_HEX}})\\.([1-9][0-9]*)\\.[0-9a-f]{${NONCE_HEX}}$`);
+/** A file of ours that is not a record — one half written — this old belongs to a process that died at it. */
+const LEFTOVER_MAX_AGE_MS = 60 * 60 * 1000;
+/** The shape of an id as it goes into a URL path and a seal: the server's event ids (`hevt_` + ULID) and ours (base64url). */
+exports.ID = /^[A-Za-z0-9_-]{1,128}$/;
+const matchKey = (question, where) => (0, node_crypto_1.createHash)('sha256')
+    .update(JSON.stringify([
+    where.host,
+    question.hookId,
+    question.agentDeviceId ?? null,
+    question.agentSessionName ?? null,
+    where.cwd,
+    question.title,
+    question.body ?? null,
+    (question.actions ?? []).map(({ id, label }) => [id, label]),
+    question.acceptsExit === true,
+]))
+    .digest('hex');
+exports.matchKey = matchKey;
+/** The failure of a file that is not there. */
+const isMissing = (err) => err instanceof Error && 'code' in err && err.code === 'ENOENT';
+/** Signal 0 reaches nothing and fails for a pid that is not there (ESRCH). Any other failure — EPERM, another user's process — is of one that is. */
+const processAlive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return !(err instanceof Error && 'code' in err && err.code === 'ESRCH');
+    }
+};
+/** A file is read as a record only when every field is what this module writes: the file is the user's own, and may have been touched. */
+const isStored = (value) => typeof value === 'object' && value !== null
+    && 'v' in value && value.v === 1
+    && 'match' in value && typeof value.match === 'string'
+    && 'hookId' in value && typeof value.hookId === 'string'
+    && 'eventId' in value && typeof value.eventId === 'string' && exports.ID.test(value.eventId)
+    && 'askId' in value && typeof value.askId === 'string' && exports.ID.test(value.askId)
+    && 'deadline' in value && Number.isSafeInteger(value.deadline) && Number(value.deadline) > 0;
+/**
+ * The record at `path`: `undefined` when there is no file, `null` when what is there is not a record.
+ * Throws when the file is there and cannot be read: that may pass, and is no reason to drop it.
+ */
+const read = (path) => {
+    let raw;
+    try {
+        raw = (0, node_fs_1.readFileSync)(path, 'utf-8');
+    }
+    catch (err) {
+        if (isMissing(err))
+            return undefined;
+        throw err;
+    }
+    try {
+        const value = JSON.parse(raw);
+        return isStored(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+};
+const remove = (path) => {
+    try {
+        (0, node_fs_1.unlinkSync)(path);
+    }
+    catch { /* gone already, or not ours to remove */ }
+};
+/** The slot of a question that cannot be placed: nothing is kept, and nothing taken up. */
+const NO_SLOT = { claim: () => null, record: () => undefined, settle: () => true };
+const pendingAsks = (dir, over = {}) => {
+    const deps = { now: Date.now, pid: process.pid, alive: processAlive, host: (0, node_os_1.hostname)(), cwd: () => process.cwd(), ...over };
+    /** Records past their deadline or not records at all, and leftovers of processes that died mid-write. */
+    const sweep = (names) => {
+        const now = deps.now();
+        for (const name of names) {
+            if (!name.startsWith(PREFIX))
+                continue;
+            const path = (0, node_path_1.join)(dir, name);
+            // Each file on its own: one that another process removes meanwhile, or that cannot be read, is passed over.
+            try {
+                if (!RECORD.test(name)) {
+                    if (now - (0, node_fs_1.statSync)(path).mtimeMs > LEFTOVER_MAX_AGE_MS)
+                        remove(path);
+                    continue;
+                }
+                const kept = read(path);
+                if (kept === null || (kept && kept.deadline <= now))
+                    remove(path);
+            }
+            catch { /* left for the next sweep */ }
+        }
+    };
+    return {
+        of: (question) => {
+            let match;
+            try {
+                // The directory this runs in may be gone (a removed worktree): `process.cwd()` throws then.
+                match = (0, exports.matchKey)(question, { host: deps.host, cwd: deps.cwd() });
+            }
+            catch {
+                return NO_SLOT;
+            }
+            const tag = match.slice(0, NAME_HEX);
+            /** The pid a file of this question is kept under; `undefined` for any other file. */
+            const ownerOf = (name) => {
+                const parts = RECORD.exec(name);
+                return parts && parts[1] === tag ? Number(parts[2]) : undefined;
+            };
+            const ownPath = () => (0, node_path_1.join)(dir, `${PREFIX}${tag}.${deps.pid}.${(0, node_crypto_1.randomUUID)().slice(0, NONCE_HEX)}`);
+            return {
+                claim: () => {
+                    try {
+                        const names = (0, node_fs_1.readdirSync)(dir);
+                        sweep(names);
+                        // One listing for both: a record the sweep removed reads as not there.
+                        for (const name of names) {
+                            const owner = ownerOf(name);
+                            // Not this question, or one a process is still waiting on. A record under this process's
+                            // own pid is from before it asked anything: the pid has been used again.
+                            if (owner === undefined || (owner !== deps.pid && deps.alive(owner)))
+                                continue;
+                            const path = (0, node_path_1.join)(dir, name);
+                            try {
+                                const kept = read(path);
+                                if (kept === undefined)
+                                    continue;
+                                if (kept === null || kept.match !== match || kept.hookId !== question.hookId) {
+                                    remove(path);
+                                    continue;
+                                }
+                                if (kept.deadline <= deps.now())
+                                    continue;
+                                // Taken by one process only: the rename fails for every other that tries, and for
+                                // this one when the record has been taken — or settled — since the look. What it
+                                // moves is what was read: a name is written once and never used again.
+                                (0, node_fs_1.renameSync)(path, ownPath());
+                                return { eventId: kept.eventId, askId: kept.askId, deadline: kept.deadline };
+                            }
+                            catch { /* another's by now, or unreadable: the next one */ }
+                        }
+                        return null;
+                    }
+                    catch {
+                        return null;
+                    }
+                },
+                record: (ask) => {
+                    const path = ownPath();
+                    const tmp = `${path}.tmp-${(0, node_crypto_1.randomUUID)()}`;
+                    try {
+                        // The names say which questions are open and for which processes: nobody else's to list.
+                        (0, private_files_js_1.ensurePrivateDir)(dir);
+                        // Written whole under another name, then moved into place: a reader never sees half of one.
+                        (0, node_fs_1.writeFileSync)(tmp, JSON.stringify({ v: 1, match, hookId: question.hookId, ...ask }), { mode: 0o600, flag: 'wx' });
+                        (0, private_files_js_1.handBackToSudoUser)(tmp);
+                        (0, node_fs_1.renameSync)(tmp, path);
+                    }
+                    catch {
+                        // The folder cannot be written: this question is not taken up again.
+                        remove(tmp);
+                    }
+                },
+                settle: () => {
+                    let names;
+                    try {
+                        names = (0, node_fs_1.readdirSync)(dir);
+                    }
+                    catch {
+                        // Nothing can be listed, so nothing is there for the next run to take either.
+                        return true;
+                    }
+                    let gone = true;
+                    // By name, not by what the file says: a record that cannot be read is ended all the same.
+                    for (const name of names) {
+                        if (ownerOf(name) !== deps.pid)
+                            continue;
+                        try {
+                            (0, node_fs_1.unlinkSync)((0, node_path_1.join)(dir, name));
+                        }
+                        catch (err) {
+                            if (!isMissing(err))
+                                gone = false;
+                        }
+                    }
+                    return gone;
+                },
+            };
+        },
+    };
+};
+exports.pendingAsks = pendingAsks;