@hwip/cli 0.0.1 → 0.1.1

package/dist/remote-hook.d.ts

@@ -0,0 +1,12 @@
+/** Agents whose prompt-submit hooks this command serves. Claude Code is
+ *  NOT here — its hook ships with the plugin (hooks/hwip-remote.sh). */
+export declare const REMOTE_HOOK_AGENTS: readonly ["gemini", "codex", "pi"];
+export type RemoteHookAgent = (typeof REMOTE_HOOK_AGENTS)[number];
+export declare const remoteEntrySections: () => string;
+export declare const isRemoteHookAgent: (raw: string) => raw is RemoteHookAgent;
+/**
+ * Core of the hook: match the stdin payload against the marker and return
+ * the JSON to print, or null for a silent no-op. Never throws.
+ */
+export declare const runRemoteHook: (agent: RemoteHookAgent, stdin: string, env?: NodeJS.ProcessEnv, now?: () => number) => string | null;
+//# sourceMappingURL=remote-hook.d.ts.map

package/dist/remote-hook.js

@@ -0,0 +1,196 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runRemoteHook = exports.isRemoteHookAgent = exports.remoteEntrySections = exports.REMOTE_HOOK_AGENTS = void 0;
+/**
+ * `hwip remote-hook <agent>` — prompt-submit hook handler for agents whose
+ * hooks the cli installs directly: Gemini CLI (BeforeAgent), Codex CLI
+ * (UserPromptSubmit), and Pi (before_agent_start, consumed by the hwip
+ * extension itself). TS twin of the Claude Code plugin's
+ * hooks/hwip-remote.sh (ADR-0002).
+ *
+ * The listener records every phone→pane text injection as a one-shot
+ * marker (`remote-<hash>` in the hwip state dir) holding the epoch second
+ * and sha256 of the injected text. When the submitted prompt matches that
+ * record — same project (cksum of the cwd), fresh (≤15 min), and
+ * byte-identical trimmed text — the hook emits additionalContext telling
+ * the model the user is driving the session from their phone, which enters
+ * sticky REMOTE mode.
+ *
+ * Detection is exact: a terminal keystroke racing a phone message can
+ * never false-match. Parity with the writer (listener.ts writeRemoteMarker)
+ * is by construction — both sides share gate.ts remoteDigest/remoteMarkerPath.
+ *
+ * The marker is one-shot, but REMOTE is not: entry records the mode (gate.ts
+ * touchRemoteActive) so it outlives the entry turn and survives compaction.
+ * A prompt that reaches this hook without a marker was typed at the terminal —
+ * the only way text becomes a prompt without one is the user's own keyboard,
+ * since a phone answer to a hwip_ask comes back as a tool_result and never
+ * reaches a prompt hook. The user is back, so the mode ends here (gate.ts
+ * clearRemoteActive) and the hook says so once.
+ *
+ * No marker and no live state → null (silent no-op); this hook only ever adds
+ * context and must never block a prompt.
+ */
+const fs_1 = require("fs");
+const config_js_1 = require("./config.js");
+const core_sections_js_1 = require("./core-sections.js");
+const hwip_core_generated_js_1 = require("./hwip-core.generated.js");
+const gate_js_1 = require("./gate.js");
+/** Agents whose prompt-submit hooks this command serves. Claude Code is
+ *  NOT here — its hook ships with the plugin (hooks/hwip-remote.sh). */
+exports.REMOTE_HOOK_AGENTS = ['gemini', 'codex', 'pi'];
+/** Per-agent hookEventName echoed back in hookSpecificOutput — each CLI
+ *  validates it against the event that invoked the hook. */
+const HOOK_EVENT_NAME = {
+    gemini: 'BeforeAgent',
+    codex: 'UserPromptSubmit',
+    pi: 'before_agent_start',
+};
+/**
+ * Freshness window (seconds), same as the bash reader: deliberately
+ * generous — false positives are already impossible without an exact hash
+ * match; its only job is to stop the SAME text typed at the terminal much
+ * later from re-flagging. It must survive the real gap between injection
+ * and prompt submit (a message sent mid-turn queues until the turn ends).
+ */
+const FRESH_WINDOW_SEC = 900;
+const TWO_WAY_CONTEXT = `# System note (Hwip remote-origin detect)
+
+This user message arrived from the user's phone via Hwip agent chat (verified by the listener — exact text match). The user is driving this session remotely and is NOT at the terminal. Enter sticky REMOTE mode now (the "Sticky REMOTE mode" rule in your Hwip rules): end EVERY response with \`hwip_ask\` (buttons + free-text) until the user exits — an exit signal (done/stop/exit), or a prompt they type at the terminal, which this hook will tell you about. Plain-text questions are invisible to them.`;
+// The static rule file of these agents carries the NORMAL branch only
+// (templates.ts PROMPT_HOOK_CORE), so the turn that enters REMOTE is where the
+// contract has to arrive in full — the twin of plugin/hooks/hwip-remote.sh
+// reading CORE_RULES.md on entry. Read from the generated core rather than
+// restated here: a copy would be one more place for the rule to drift. The
+// four sections together cite only rules they carry (1–4, 7–9), so no
+// cross-reference dangles; remote-hook.test.ts checks that.
+//
+// Where it goes depends on what the agent's hook can carry:
+// - gemini/codex: additionalContext, once per entry — a later phone prompt on
+//   a session already in REMOTE gets the note alone, since the contract is
+//   already in its context.
+// - pi: `systemPrompt`, on every phone prompt. pi's before_agent_start can
+//   replace the system prompt for that run, and a system-prompt change is not
+//   persisted — so the contract costs nothing after REMOTE ends, whereas an
+//   injected message rides every later turn of the session (2026-09-13: a
+//   "hello" from the phone left 7.5K chars in a 300-turn implement session
+//   until compaction, and the compaction summary then restated the rules).
+//   The additionalContext note stays short on every phone prompt.
+// Sliced on that turn only — this command runs on every prompt submit, and
+// the common path is a silent no-op. Exported for the tests.
+const remoteEntrySections = () => ['When hwip_ask is MANDATORY', 'When hwip_ask is the DEFAULT', 'Sticky REMOTE mode', 'When to use AskUserQuestion vs hwip_ask']
+    .map((heading) => (0, core_sections_js_1.coreSection)(hwip_core_generated_js_1.HWIP_CORE_HOOK_DRIVEN, heading))
+    .join('\n\n');
+exports.remoteEntrySections = remoteEntrySections;
+const ONE_WAY_CONTEXT = `# System note (Hwip remote-origin detect)
+
+This user message arrived from the user's phone via Hwip agent chat (verified by the listener — exact text match), but no hook id is configured (neither \`HWIP_HOOK_ID\` nor \`hookId\` in ~/.hwip/config.json), so the two-way tool (hwip_ask) is unavailable. Make your final message self-contained — the completion push is the user's only feedback channel. If you have not already mentioned it this session, tell the user once that running \`npx @hwip/cli setup\` upgrades this into a two-way remote session (buttons + text replies from the phone).`;
+/**
+ * The first prompt a remote session's user types at the terminal. Emitted
+ * once — the state is cleared with it, so every later terminal turn is a
+ * silent no-op. Kept in step with the wording in
+ * plugin/hooks/hwip-remote.sh.
+ */
+const EXIT_CONTEXT = `# System note (Hwip)
+
+The user typed this prompt at the terminal, so this session has LEFT sticky REMOTE mode — answer normally (the NORMAL branch of your Hwip rules) and do not end this response with \`hwip_ask\` just to keep the loop alive. One rule still holds: if you actually ask the user something, ask it with \`hwip_ask\`. Re-entry is automatic the moment they send another message from their phone.`;
+const isRemoteHookAgent = (raw) => exports.REMOTE_HOOK_AGENTS.includes(raw);
+exports.isRemoteHookAgent = isRemoteHookAgent;
+/**
+ * Core of the hook: match the stdin payload against the marker and return
+ * the JSON to print, or null for a silent no-op. Never throws.
+ */
+const runRemoteHook = (agent, stdin, env = process.env, now = Date.now) => {
+    let prompt;
+    let cwd;
+    try {
+        const input = JSON.parse(stdin);
+        prompt = typeof input.prompt === 'string' ? input.prompt : '';
+        cwd = typeof input.cwd === 'string' ? input.cwd : '';
+    }
+    catch {
+        return null;
+    }
+    // `cwd` keys every state file, so without it there is nothing to look up.
+    if (!cwd)
+        return null;
+    // Mute outranks everything (the mute rule) — stay silent and leave both the marker
+    // and the state untouched (the next inject overwrites the marker anyway).
+    if ((0, gate_js_1.isMuted)(cwd))
+        return null;
+    const emit = (additionalContext, systemPrompt) => JSON.stringify({
+        hookSpecificOutput: { hookEventName: HOOK_EVENT_NAME[agent], additionalContext, ...(systemPrompt ? { systemPrompt } : {}) },
+    });
+    // Exactly one additionalContext per invocation, and the verdict decides
+    // which: 'phone' enters, 'keyboard' leaves, 'unclear' says nothing and
+    // leaves the mode as it was.
+    const origin = remoteOrigin(prompt, cwd, now);
+    if (origin === 'phone') {
+        // Resolved on the two branches that need it, not up front — the common
+        // no-marker path never reads the config file.
+        if (!(0, config_js_1.resolveHookId)(env))
+            return emit(ONE_WAY_CONTEXT);
+        // Only a two-way session has a mode to stay in — without hwip_ask there is
+        // nothing for a later turn to be reminded of, so no state is recorded.
+        const entering = !(0, gate_js_1.isRemoteActive)(cwd, now);
+        (0, gate_js_1.touchRemoteActive)(cwd, now);
+        if (agent === 'pi')
+            return emit(TWO_WAY_CONTEXT, (0, exports.remoteEntrySections)());
+        return emit(entering ? `${TWO_WAY_CONTEXT}\n\n${(0, exports.remoteEntrySections)()}` : TWO_WAY_CONTEXT);
+    }
+    if (origin === 'keyboard' && (0, gate_js_1.isRemoteActive)(cwd, now) && (0, config_js_1.resolveHookId)(env)) {
+        (0, gate_js_1.clearRemoteActive)(cwd);
+        return emit(EXIT_CONTEXT);
+    }
+    return null;
+};
+exports.runRemoteHook = runRemoteHook;
+const remoteOrigin = (prompt, cwd, now) => {
+    const hash = (0, gate_js_1.projectHash)(cwd);
+    const marker = (0, gate_js_1.remoteMarkerPath)(hash);
+    let content;
+    try {
+        content = (0, fs_1.readFileSync)(marker, 'utf-8');
+    }
+    catch {
+        return 'keyboard';
+    }
+    if (!prompt)
+        return 'unclear';
+    // Marker format: "<epochSec> <sha256hex>\n" (listener.ts writeRemoteMarker).
+    // At most 12 digits, like the REMOTE state's time (gate.ts isRemoteActive; bash `hwip_age_sec`): a longer one is not a time.
+    const record = content.match(/^(\d{1,12}) ([0-9a-f]{64})\n?$/);
+    if (!record) {
+        // Junk can only ever be re-read and re-rejected — same housekeeping a
+        // stale marker gets. Twin: hwip-remote.sh's `rm -f` on the parse branches.
+        try {
+            (0, fs_1.unlinkSync)(marker);
+        }
+        catch {
+            /* best-effort housekeeping */
+        }
+        return 'keyboard';
+    }
+    if (Math.floor(now() / 1000) - Number(record[1]) > FRESH_WINDOW_SEC) {
+        // Stale markers are dead weight (can never flag) — delete on sight.
+        try {
+            (0, fs_1.unlinkSync)(marker);
+        }
+        catch {
+            /* best-effort housekeeping */
+        }
+        return 'keyboard';
+    }
+    if ((0, gate_js_1.remoteDigest)(prompt) !== record[2])
+        return 'unclear';
+    // Matched — consume the marker so an identical later prompt (e.g. typed
+    // at the terminal) can't re-flag. Housekeeping is not the verdict: the
+    // match is valid whether or not the delete lands.
+    try {
+        (0, fs_1.unlinkSync)(marker);
+    }
+    catch {
+        /* emit anyway — the match itself is valid */
+    }
+    return 'phone';
+};

package/dist/replace-file.d.ts

@@ -0,0 +1,50 @@
+/** A file hwip is about to rewrite is not valid UTF-8: reading it as text would turn its bytes into U+FFFD and the write would keep that. */
+export declare class NotUtf8Error extends Error {
+    constructor(filePath: string);
+}
+/** The file changed between hwip reading it and writing it: the write would drop the other writer's change. */
+export declare class FileChangedError extends Error {
+    constructor(filePath: string);
+}
+/** hwip may not write the file, or may not create the temp file it writes beside it: it is left as it is, and the user is told which. */
+export declare class NotWritableError extends Error {
+    constructor(filePath: string, why: string);
+}
+/** A file's text, exactly: throws `NotUtf8Error` instead of decoding bad bytes to U+FFFD. A byte order mark is kept. */
+export declare const readText: (filePath: string) => string;
+/** `readText`, or null for a file that is not there (any other failure — no permission — still throws). */
+export declare const readTextIfExists: (filePath: string) => string | null;
+/**
+ * Delete a file hwip owned whole, unless it changed since it was read: a delete is a write too, and
+ * a line the user added in between would go with it. `expected` is what was read.
+ */
+export declare const removeFile: (filePath: string, expected: string) => void;
+/**
+ * Write a user's file so it is either the old content or the new one, never a
+ * cut-off mix: a plain write empties the file first, and a full disk or a kill
+ * in between leaves the agent's settings truncated. The new content goes to a
+ * temp file beside the real one and is renamed over it.
+ *
+ * A symlink is followed, not replaced (dotfile managers link these files into
+ * a repo), and an existing file keeps its mode. The rename makes a new inode,
+ * so a hard link to the old file keeps the old content (not when it is written in place).
+ *
+ * `expected` is what the caller read before it built `content` (null: the file
+ * was not there). Just before the rename the file is read again, and a write
+ * that would drop what someone else wrote in between throws `FileChangedError`
+ * instead. Left out, nothing is checked (a file hwip owns whole). The window
+ * between that read and the rename is not closed, only made very small.
+ *
+ * `mode` is the mode the new file has when it appears under its name, new file
+ * or old: a file with a secret in it must not be wider than that for a moment.
+ * Left out, a new file is 0644 and an old one keeps its mode.
+ *
+ * A file the user cannot write is not replaced: the rename needs no permission on it, but the
+ * user made it read-only on purpose, so `NotWritableError` (root can write any file, so for root
+ * nothing is read-only). A writable file in a directory that
+ * takes no new entries is written in place (what a plain write did before this function): the
+ * user can change the file, so changing it is not a bypass. A file that is not there, in such a
+ * directory, cannot be made: `NotWritableError`.
+ */
+export declare const replaceFile: (filePath: string, content: string, expected?: string | null, mode?: number) => void;
+//# sourceMappingURL=replace-file.d.ts.map

package/dist/replace-file.js

@@ -0,0 +1,328 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.replaceFile = exports.removeFile = exports.readTextIfExists = exports.readText = exports.NotWritableError = exports.FileChangedError = exports.NotUtf8Error = void 0;
+const fs_1 = require("fs");
+const crypto_1 = require("crypto");
+const path_1 = require("path");
+const private_files_js_1 = require("./private-files.js");
+/** A file hwip is about to rewrite is not valid UTF-8: reading it as text would turn its bytes into U+FFFD and the write would keep that. */
+class NotUtf8Error extends Error {
+    constructor(filePath) {
+        super(`${filePath} is not valid UTF-8 text, left it unchanged`);
+        this.name = 'NotUtf8Error';
+    }
+}
+exports.NotUtf8Error = NotUtf8Error;
+/** The file changed between hwip reading it and writing it: the write would drop the other writer's change. */
+class FileChangedError extends Error {
+    constructor(filePath) {
+        super(`${filePath} changed while hwip was editing it, left it as it is (run the command again)`);
+        this.name = 'FileChangedError';
+    }
+}
+exports.FileChangedError = FileChangedError;
+/** hwip may not write the file, or may not create the temp file it writes beside it: it is left as it is, and the user is told which. */
+class NotWritableError extends Error {
+    constructor(filePath, why) {
+        super(`${filePath} ${why}, left it unchanged`);
+        this.name = 'NotWritableError';
+    }
+}
+exports.NotWritableError = NotWritableError;
+/** A file's text, exactly: throws `NotUtf8Error` instead of decoding bad bytes to U+FFFD. A byte order mark is kept. */
+const readText = (filePath) => {
+    const bytes = (0, fs_1.readFileSync)(filePath);
+    try {
+        return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch {
+        throw new NotUtf8Error(filePath);
+    }
+};
+exports.readText = readText;
+/** `readText`, or null for a file that is not there (any other failure — no permission — still throws). */
+const readTextIfExists = (filePath) => {
+    try {
+        return (0, exports.readText)(filePath);
+    }
+    catch (err) {
+        if (err instanceof Error && 'code' in err && err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+};
+exports.readTextIfExists = readTextIfExists;
+/**
+ * Delete a file hwip owned whole, unless it changed since it was read: a delete is a write too, and
+ * a line the user added in between would go with it. `expected` is what was read.
+ */
+const removeFile = (filePath, expected) => {
+    let now;
+    try {
+        now = (0, exports.readTextIfExists)(filePath);
+    }
+    catch {
+        throw new FileChangedError(filePath);
+    }
+    if (now !== expected)
+        throw new FileChangedError(filePath);
+    (0, fs_1.rmSync)(filePath, { force: true });
+};
+exports.removeFile = removeFile;
+/** The kernel follows at most 40 links in a path (Linux `ELOOP`; macOS stops at 32): so does this. */
+const MAX_LINK_HOPS = 40;
+/** The file a write to `filePath` lands in: the end of a symlink chain, even
+ *  one that does not exist yet (a plain write creates it there). */
+const writeTarget = (filePath) => {
+    try {
+        return (0, fs_1.realpathSync)(filePath);
+    }
+    catch {
+        /* missing, or a link (chain) to a missing file */
+    }
+    // `realpath` cannot say where a chain that ends in nothing ends: walk it a link at a time.
+    // One step only would stop at the middle link, and the rename would replace it with a file.
+    let at = filePath;
+    for (let hops = 0; (0, fs_1.lstatSync)(at, { throwIfNoEntry: false })?.isSymbolicLink(); hops++) {
+        if (hops === MAX_LINK_HOPS)
+            throw new Error(`${filePath} links to itself, or through too many links, so it was left unchanged`);
+        // A relative link is read from the directory the link is really in, which `..` makes a difference for
+        // when that directory is itself reached through a symlink (`~/.cursor` into a dotfiles repo).
+        let base = (0, path_1.dirname)(at);
+        try {
+            base = (0, fs_1.realpathSync)(base);
+        }
+        catch {
+            /* the directory is not there either: the lexical one is all there is */
+        }
+        at = (0, path_1.resolve)(base, (0, fs_1.readlinkSync)(at));
+    }
+    return at;
+};
+const lacksPermission = (err) => err instanceof Error && 'code' in err && (err.code === 'EACCES' || err.code === 'EPERM');
+/**
+ * Whether someone else already wrote exactly `content` since `expected` was read (nothing left to do).
+ * Throws `FileChangedError` when the file holds anything but `expected` or `content`.
+ */
+const alreadyWritten = (target, filePath, expected, content) => {
+    if (expected === undefined)
+        return false;
+    let now;
+    try {
+        now = (0, exports.readTextIfExists)(target);
+    }
+    catch {
+        throw new FileChangedError(filePath); // unreadable, or no longer text: not what was read either
+    }
+    if (now === expected)
+        return false;
+    if (now === content)
+        return true;
+    throw new FileChangedError(filePath);
+};
+/**
+ * Write over the file itself, for a directory that takes no new entries (a temp file cannot be made
+ * there). Not atomic: a kill in between leaves a cut-off file, so the old bytes are put back if the
+ * write fails, and the asked-for mode is set first so a secret is never in a wider file.
+ */
+const writeInPlace = (target, content, mode) => {
+    const { O_RDWR, O_NOFOLLOW } = fs_1.constants;
+    // Without `O_NOFOLLOW` (Windows, which has no such modes either) the old by-name path stays.
+    if (O_NOFOLLOW === undefined) {
+        const old = (0, fs_1.readFileSync)(target);
+        if (mode !== undefined)
+            (0, fs_1.chmodSync)(target, mode);
+        try {
+            (0, fs_1.writeFileSync)(target, content);
+        }
+        catch (err) {
+            try {
+                (0, fs_1.writeFileSync)(target, old);
+            }
+            catch {
+                throw new Error(`${target} could not be written and its old content could not be put back, so it may be cut off`, { cause: err });
+            }
+            throw err;
+        }
+        return;
+    }
+    // Opened without following a link at its end, and read through what was opened: a link
+    // planted after `writeTarget` resolved it fails closed here (ELOOP) instead of redirecting
+    // the read, the mode change and the write onto another file.
+    let fd;
+    try {
+        fd = (0, fs_1.openSync)(target, O_RDWR | O_NOFOLLOW);
+    }
+    catch {
+        throw new FileChangedError(target);
+    }
+    try {
+        const old = (0, fs_1.readFileSync)(fd);
+        if (mode !== undefined)
+            (0, fs_1.fchmodSync)(fd, mode);
+        // An fd write starts where the last one stopped (a truncate does not move the offset):
+        // cut and write at 0, so a retry and the put-back below both start at the beginning.
+        (0, fs_1.ftruncateSync)(fd, 0);
+        try {
+            (0, fs_1.writeSync)(fd, content, 0, 'utf8');
+        }
+        catch (err) {
+            try {
+                (0, fs_1.ftruncateSync)(fd, 0);
+                (0, fs_1.writeSync)(fd, old, 0, null, 0);
+            }
+            catch {
+                throw new Error(`${target} could not be written and its old content could not be put back, so it may be cut off`, { cause: err });
+            }
+            throw err;
+        }
+    }
+    finally {
+        (0, fs_1.closeSync)(fd);
+    }
+};
+/**
+ * Write a user's file so it is either the old content or the new one, never a
+ * cut-off mix: a plain write empties the file first, and a full disk or a kill
+ * in between leaves the agent's settings truncated. The new content goes to a
+ * temp file beside the real one and is renamed over it.
+ *
+ * A symlink is followed, not replaced (dotfile managers link these files into
+ * a repo), and an existing file keeps its mode. The rename makes a new inode,
+ * so a hard link to the old file keeps the old content (not when it is written in place).
+ *
+ * `expected` is what the caller read before it built `content` (null: the file
+ * was not there). Just before the rename the file is read again, and a write
+ * that would drop what someone else wrote in between throws `FileChangedError`
+ * instead. Left out, nothing is checked (a file hwip owns whole). The window
+ * between that read and the rename is not closed, only made very small.
+ *
+ * `mode` is the mode the new file has when it appears under its name, new file
+ * or old: a file with a secret in it must not be wider than that for a moment.
+ * Left out, a new file is 0644 and an old one keeps its mode.
+ *
+ * A file the user cannot write is not replaced: the rename needs no permission on it, but the
+ * user made it read-only on purpose, so `NotWritableError` (root can write any file, so for root
+ * nothing is read-only). A writable file in a directory that
+ * takes no new entries is written in place (what a plain write did before this function): the
+ * user can change the file, so changing it is not a bypass. A file that is not there, in such a
+ * directory, cannot be made: `NotWritableError`.
+ */
+const replaceFile = (filePath, content, expected, mode) => {
+    (0, private_files_js_1.mkdirHandedBack)((0, path_1.dirname)(filePath));
+    const target = writeTarget(filePath);
+    (0, private_files_js_1.mkdirHandedBack)((0, path_1.dirname)(target));
+    const existing = (0, fs_1.statSync)(target, { throwIfNoEntry: false });
+    if (existing) {
+        try {
+            (0, fs_1.accessSync)(target, fs_1.constants.W_OK);
+        }
+        catch {
+            throw new NotWritableError(filePath, 'is read-only');
+        }
+    }
+    // Random name, exclusive create: a predictable name is one another process
+    // could pre-create as a symlink for this write to follow.
+    const tmp = `${target}.${(0, crypto_1.randomBytes)(6).toString('hex')}.tmp`;
+    let created = false;
+    try {
+        // Created without following a link at its end (C149 ④): `writeFileSync` with `wx`
+        // opens what a pre-placed link points at. The fd below fails closed (ELOOP) instead,
+        // and mode/owner go onto the fd, never by name onto whatever `tmp` became after.
+        if (fs_1.constants.O_NOFOLLOW === undefined) {
+            try {
+                (0, fs_1.writeFileSync)(tmp, content, { mode: 0o600, flag: 'wx' });
+            }
+            catch (err) {
+                // The exclusive create may have made the file and then failed writing it (a full disk): that file is ours.
+                // EEXIST means the name was taken before, by someone else.
+                if (!(err instanceof Error && 'code' in err && err.code === 'EEXIST')) {
+                    try {
+                        (0, fs_1.rmSync)(tmp, { force: true });
+                    }
+                    catch {
+                        /* the write's own error is the one to report */
+                    }
+                }
+                if (!lacksPermission(err))
+                    throw err;
+                if (!existing)
+                    throw new NotWritableError(filePath, `cannot be created: ${(0, path_1.dirname)(target)} takes no new files`);
+                if (alreadyWritten(target, filePath, expected, content))
+                    return;
+                writeInPlace(target, content, mode);
+                return;
+            }
+            created = true;
+            // After the write: the create mode is cut by the umask.
+            (0, fs_1.chmodSync)(tmp, mode ?? (existing ? existing.mode & 0o777 : 0o644));
+            // The rename makes a new inode owned by whoever runs this: root (sudo, HOME kept) must not take a user's file.
+            if (existing && process.getuid?.() === 0 && existing.uid !== 0)
+                (0, fs_1.chownSync)(tmp, existing.uid, existing.gid);
+        }
+        else {
+            const flags = fs_1.constants.O_CREAT | fs_1.constants.O_EXCL | fs_1.constants.O_WRONLY | fs_1.constants.O_NOFOLLOW;
+            let tmpFd;
+            try {
+                tmpFd = (0, fs_1.openSync)(tmp, flags, 0o600);
+            }
+            catch (err) {
+                if (!lacksPermission(err))
+                    throw err;
+                if (!existing)
+                    throw new NotWritableError(filePath, `cannot be created: ${(0, path_1.dirname)(target)} takes no new files`);
+                if (alreadyWritten(target, filePath, expected, content))
+                    return;
+                writeInPlace(target, content, mode);
+                return;
+            }
+            created = true;
+            try {
+                (0, fs_1.writeFileSync)(tmpFd, content);
+                // After the write: the create mode is cut by the umask.
+                (0, fs_1.fchmodSync)(tmpFd, mode ?? (existing ? existing.mode & 0o777 : 0o644));
+                // A file root creates (a first login: no config.json yet) goes to the person who ran sudo, as its folder does.
+                // The rename-over-an-existing-file case is the existing-owner line below.
+                if (!existing) {
+                    const owner = (0, private_files_js_1.sudoOwner)(tmp);
+                    if (owner) {
+                        try {
+                            (0, fs_1.fchownSync)(tmpFd, owner.uid, owner.gid);
+                        }
+                        catch { /* not ours to change */ }
+                    }
+                }
+                // The rename makes a new inode owned by whoever runs this: root (sudo, HOME kept) must not take a user's file.
+                if (existing && process.getuid?.() === 0 && existing.uid !== 0)
+                    (0, fs_1.fchownSync)(tmpFd, existing.uid, existing.gid);
+            }
+            finally {
+                (0, fs_1.closeSync)(tmpFd);
+            }
+        }
+        // Narrow the rename-by-name window (no `renameat` in Node): refuse a `tmp` that
+        // became a link or gained a second name since the exclusive create.
+        const tmpSeen = (0, fs_1.lstatSync)(tmp, { throwIfNoEntry: false });
+        if (!tmpSeen?.isFile() || tmpSeen.nlink !== 1) {
+            throw new FileChangedError(filePath);
+        }
+        if (alreadyWritten(target, filePath, expected, content)) {
+            // Someone else (a second `hwip install` at the same time) already wrote exactly this: nothing left to do.
+            (0, fs_1.unlinkSync)(tmp);
+            return;
+        }
+        (0, fs_1.renameSync)(tmp, target);
+    }
+    catch (err) {
+        if (created) {
+            try {
+                (0, fs_1.unlinkSync)(tmp);
+            }
+            catch {
+                /* already renamed or removed */
+            }
+        }
+        throw err;
+    }
+};
+exports.replaceFile = replaceFile;

package/dist/schedule-command.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `hwip schedule` — add, list and remove scheduled sessions (F8).
+ *
+ * This only writes and reads the files in `schedule.ts`. The listener starts the sessions
+ * (`schedule-runner.ts`), so nothing here needs a running listener except the sessions firing.
+ */
+import { type Checked, type Schedule, type ScheduleWhen } from './schedule.js';
+export interface ScheduleCommandDeps {
+    now: () => number;
+    /** The directory the session is named for (`detectProjectDir`). */
+    projectDir: () => string;
+    /** The main checkout of the repo `dir` is in; null outside git. For `--wt`. */
+    checkoutRoot: (dir: string) => string | null;
+    /** Whether git takes `name` as a branch name. For `--wt`. */
+    validBranch: (root: string, name: string) => Promise<boolean>;
+    listenerRunning: () => boolean;
+    /** The agent kinds a prompt can be scheduled for: those whose detection rules can say `idle` (`schedule-ready.ts`). */
+    promptKinds: () => readonly string[];
+    out: (line: string) => void;
+    err: (line: string) => void;
+}
+/** `daily 09:00`, `weekdays 09:00`, `mon,wed 09:00`, `every 30m`, `every 2h`. */
+export declare const describeWhen: (when: ScheduleWhen) => string;
+interface Built {
+    make: (id: string) => Schedule;
+    agentName: string;
+}
+/** The schedule `hwip schedule add <words>` asks for, before it has an id. */
+export declare const buildSchedule: (words: string[], deps: ScheduleCommandDeps) => Promise<Checked<Built>>;
+/** `words`: argv after `schedule`. Returns the exit code. */
+export declare const runSchedule: (words: string[], deps: ScheduleCommandDeps) => Promise<number>;
+export declare const liveScheduleDeps: () => ScheduleCommandDeps;
+export declare const handleSchedule: (words: string[]) => Promise<number>;
+export {};
+//# sourceMappingURL=schedule-command.d.ts.map