@hwip/cli 0.0.1 → 0.1.1

package/dist/pi-transcript.d.ts

@@ -0,0 +1,26 @@
+/**
+ * pi's transcript format, projected into the events the timeline draws.
+ *
+ * The second projector, and the one that proves the seam: `turn-watch` reads
+ * this file's output through `TranscriptProjector` without knowing pi exists.
+ * Everything here is pi's vocabulary and belongs to pi alone — a third agent
+ * means a third file, not another branch in this one.
+ *
+ * Shape measured 2026-09-14 against `~/.pi/agent/sessions/**\/*.jsonl`
+ * (40 sessions, 494 lines in the deepest), and the writer that produces it:
+ * `@earendil-works/pi-coding-agent/dist/core/session-manager.js`, at its
+ * `CURRENT_SESSION_VERSION = 3`.
+ *
+ * Nothing here refuses to read another version, and that is deliberate: an
+ * unknown entry type falls out of the checks below and the timeline is thinner
+ * by one row. A projector that stopped on a version bump would take the rows it
+ * still understood down with it.
+ */
+import { type TranscriptProjector } from './transcript-tail.js';
+/**
+ * pi writes one line per message, not one per content block, so a message's
+ * `msg` event needs no merging across lines — the one place this projector is
+ * simpler than Claude's.
+ */
+export declare const projectPiEntries: TranscriptProjector;
+//# sourceMappingURL=pi-transcript.d.ts.map

package/dist/pi-transcript.js

@@ -0,0 +1,255 @@
+"use strict";
+/**
+ * pi's transcript format, projected into the events the timeline draws.
+ *
+ * The second projector, and the one that proves the seam: `turn-watch` reads
+ * this file's output through `TranscriptProjector` without knowing pi exists.
+ * Everything here is pi's vocabulary and belongs to pi alone — a third agent
+ * means a third file, not another branch in this one.
+ *
+ * Shape measured 2026-09-14 against `~/.pi/agent/sessions/**\/*.jsonl`
+ * (40 sessions, 494 lines in the deepest), and the writer that produces it:
+ * `@earendil-works/pi-coding-agent/dist/core/session-manager.js`, at its
+ * `CURRENT_SESSION_VERSION = 3`.
+ *
+ * Nothing here refuses to read another version, and that is deliberate: an
+ * unknown entry type falls out of the checks below and the timeline is thinner
+ * by one row. A projector that stopped on a version bump would take the rows it
+ * still understood down with it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectPiEntries = void 0;
+const transcript_tail_js_1 = require("./transcript-tail.js");
+/**
+ * Which tool argument reads as "what this call is about", first match wins.
+ *
+ * pi's own list, deliberately not Claude's: pi has no `description` argument,
+ * so the sentence-a-human-wrote field Claude's list leads with does not exist
+ * here. `path` leads instead because it covers read/write/edit/grep, the calls
+ * where the target is the whole point of the row. `name` beats `task` because a
+ * `subagent` call carries both and its `task` is a briefing — measured at 300+
+ * characters with embedded newlines, which renders as a wall, not a label.
+ *
+ * `command` is absent for the reason it is absent from Claude's list — a
+ * command line is the argument most likely to carry a secret. `bashProgram`
+ * below is what stands in for it.
+ */
+const PI_TARGET_KEYS = ['path', 'pattern', 'query', 'name', 'question', 'task', 'file_path'];
+/**
+ * The program a shell call runs, and nothing else.
+ *
+ * Measured over 40 sessions: 1187 of ~1800 tool calls are `bash`/`guarded_bash`,
+ * whose only argument is `command`. Dropping it wholesale — the rule Claude's
+ * projector follows — would leave two thirds of a pi timeline as rows that say
+ * "bash" and nothing more, which is a list of nothing. Carrying `command` whole
+ * would put the field most likely to hold a token, an `Authorization` header or
+ * a signed URL onto the wire.
+ *
+ * So only a bare program name leaves: `git`, `npm`, `curl`. Arguments never do,
+ * which is where every one of those secrets lives.
+ *
+ * Three kinds of token are stepped over on the way to it, because stopping at
+ * any of them produces a row that says nothing:
+ *
+ *  - `VAR=value` assignments, skipped rather than shown — the value is the
+ *    secret-shaped half.
+ *  - Flags. A leading `-l` is never the program.
+ *  - A prefix builtin and everything up to the next `&&`, `||` or `;`. Measured
+ *    over every pi session on this machine, `cd` is the first token of 786 of
+ *    ~1400 shell calls — `cd <dir> && <the actual work>`. Reporting "cd" for
+ *    the majority of a timeline's rows is the same as reporting nothing.
+ */
+const SHELL_PREFIX_BUILTINS = new Set(['cd', 'set', 'export', 'source', 'exec', 'time', 'env', '.']);
+/** `&&`, `||`, `;`, `|` — split on them rather than scanning for them, because
+ *  they are written glued to their neighbours as often as spaced (`cd /x&&ls`). */
+const SHELL_SEPARATOR = /&&|\|\||[;|]/;
+/** The program a single command segment runs, or undefined when it names none. */
+const programOfSegment = (segment) => {
+    for (const token of segment.trim().split(/\s+/)) {
+        if (!token)
+            continue;
+        // `FOO=bar cmd …` — the value is the secret-shaped half, so step over
+        // the assignment entirely rather than reporting either half of it.
+        if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(token))
+            continue;
+        // A flag where the program should be means this segment names no
+        // program. Skipping it would promote the following argument — a path,
+        // a URL — into the program slot, which is how `-l /some/path` would
+        // otherwise be reported as `/some/path`.
+        if (token.startsWith('-'))
+            return undefined;
+        return token;
+    }
+    return undefined;
+};
+const bashProgram = (input) => {
+    if (!input || typeof input !== 'object')
+        return undefined;
+    const command = input.command;
+    if (typeof command !== 'string')
+        return undefined;
+    // Split naively: a `|` or `;` inside quotes splits too, so a segment can
+    // begin mid-string and name no program. That is safe — the worst outcome is
+    // a missing label, never a wrong one that leaks an argument. The cap is a
+    // separate concern: a pathological `cd a && cd b && …` chain costs a fixed
+    // number of steps, not one per token of whatever the agent wrote.
+    const segments = command.split(SHELL_SEPARATOR, 64);
+    for (const segment of segments) {
+        const program = programOfSegment(segment);
+        if (program === undefined)
+            continue;
+        // `cd`, `set`, `env` … — real, but only ever a preamble to the work.
+        if (SHELL_PREFIX_BUILTINS.has(program))
+            continue;
+        return (0, transcript_tail_js_1.clamp)(program);
+    }
+    return undefined;
+};
+/**
+ * Wrappers pi uses when it injects context into the `user` role.
+ *
+ * pi stamps no provenance on an entry — measured across every session on this
+ * machine, a harness injection and a typed message carry byte-identical keys
+ * (`id,message,parentId,timestamp,type`), so the `origin.kind`/`promptSource`
+ * check Claude's projector makes has no counterpart here. The opening wrapper is
+ * the only signal there is.
+ *
+ * What they hold is why this matters: `<file name="/Users/…/artifacts/…">` and
+ * `<skill name="02-implement" location="/Users/…/SKILL.md">` carry a whole file
+ * or skill body plus absolute local paths, and without this they reach the phone
+ * as the user's own words.
+ *
+ * Measured over the 131 user-role messages in `~/.pi/agent/sessions` on this
+ * machine: 29 entries open with `<file`, 17 with `<skill`, and nothing else
+ * opens with a tag at all. The list is exactly what was observed, so a wrapper
+ * pi adds later needs adding here — and only after it is seen, because the cost
+ * of a wrong guess runs the other way: `<pm>` reads like one of these and is
+ * not, it is the plan template's package-manager placeholder appearing in prose
+ * a person wrote, and filtering on it would delete their message.
+ *
+ * These entries are dropped whole rather than stripped, unlike Claude's
+ * `<system-reminder>` blocks, because there is no human half to keep — the
+ * injection IS the entry.
+ */
+const PI_INJECTED_PROMPT = /^\s*<(file|skill)[\s>]/;
+/** Text out of pi's content blocks — every role builds its prose the same way. */
+const textOf = (content) => {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    let text = '';
+    for (const block of content) {
+        if (!block || typeof block !== 'object')
+            continue;
+        const item = block;
+        if (item.type === 'text' && typeof item.text === 'string')
+            text += item.text;
+    }
+    return text;
+};
+/**
+ * pi writes one line per message, not one per content block, so a message's
+ * `msg` event needs no merging across lines — the one place this projector is
+ * simpler than Claude's.
+ */
+const projectPiEntries = (lines, opts = {}) => {
+    const events = [];
+    for (const raw of lines) {
+        let entry;
+        try {
+            const parsed = JSON.parse(raw);
+            if (!parsed || typeof parsed !== 'object')
+                continue;
+            entry = parsed;
+        }
+        catch {
+            continue;
+        }
+        // `session`, `model_change`, `thinking_level_change`, `compaction`,
+        // `custom`, `custom_message` — pi's bookkeeping. None of it is
+        // something the agent did, and an entry type added in a later version
+        // lands here too rather than breaking the watch.
+        if (entry.type !== 'message')
+            continue;
+        const message = entry.message;
+        if (!message || typeof message !== 'object')
+            continue;
+        const msg = message;
+        const at = typeof entry.timestamp === 'string' ? entry.timestamp : undefined;
+        const stamp = at ? { at } : {};
+        if (msg.role === 'user') {
+            // What the person typed. Carried for the same reason Claude's
+            // prompts are: without it the timeline records no question — but
+            // only once the harness's own injections have been ruled out, since
+            // pi files those under this role too.
+            const text = textOf(msg.content).trim();
+            if (text && !PI_INJECTED_PROMPT.test(text)) {
+                events.push({ kind: 'prompt', text: (0, transcript_tail_js_1.clamp)(text, transcript_tail_js_1.MAX_EVENT_TEXT_CHARS), ...stamp });
+            }
+            continue;
+        }
+        if (msg.role === 'toolResult') {
+            if (typeof msg.toolCallId !== 'string')
+                continue;
+            const resultLines = (0, transcript_tail_js_1.resultLinesOf)(msg.content);
+            events.push({
+                kind: 'tool_result',
+                id: msg.toolCallId,
+                ok: msg.isError !== true,
+                ...(resultLines ? { lines: resultLines } : {}),
+                ...stamp,
+            });
+            continue;
+        }
+        if (msg.role !== 'assistant') {
+            opts.onUnknown?.(`pi message role ${typeof msg.role === 'string' ? msg.role : '(none)'}`);
+            continue;
+        }
+        const content = Array.isArray(msg.content) ? msg.content : [];
+        const usage = msg.usage;
+        if (usage && typeof usage === 'object' && typeof entry.id === 'string') {
+            const u = usage;
+            const thinking = content.filter((block) => block && typeof block === 'object' && block.type === 'thinking').length;
+            events.push({
+                kind: 'msg',
+                mid: (0, transcript_tail_js_1.clamp)(entry.id),
+                ...(typeof msg.model === 'string' ? { model: (0, transcript_tail_js_1.clamp)(msg.model) } : {}),
+                out: (0, transcript_tail_js_1.finiteNumber)(u.output),
+                ctx: (0, transcript_tail_js_1.finiteNumber)(u.input) + (0, transcript_tail_js_1.finiteNumber)(u.cacheRead) + (0, transcript_tail_js_1.finiteNumber)(u.cacheWrite),
+                ...(thinking ? { thinking } : {}),
+                ...stamp,
+            });
+        }
+        for (const block of content) {
+            if (!block || typeof block !== 'object')
+                continue;
+            const item = block;
+            if (item.type === 'toolCall' && typeof item.id === 'string' && typeof item.name === 'string') {
+                const target = (0, transcript_tail_js_1.oneLine)((0, transcript_tail_js_1.targetFrom)(item.arguments, PI_TARGET_KEYS)) ?? bashProgram(item.arguments);
+                events.push({
+                    kind: 'tool',
+                    id: item.id,
+                    name: (0, transcript_tail_js_1.clamp)(item.name),
+                    ...(target ? { target } : {}),
+                    ...stamp,
+                });
+                continue;
+            }
+            if (item.type === 'text' && typeof item.text === 'string') {
+                if (item.text.trim())
+                    events.push({ kind: 'text', text: (0, transcript_tail_js_1.clamp)(item.text, transcript_tail_js_1.MAX_EVENT_TEXT_CHARS), ...stamp });
+                continue;
+            }
+            // `thinking` falls through on purpose, exactly as it does for Claude:
+            // the timeline shows what the agent did, not what it considered.
+            // Only the count leaves, on `msg` above.
+            if (item.type === 'thinking')
+                continue;
+            // A block this file does not know, or a known one whose fields moved.
+            opts.onUnknown?.(`pi content block ${typeof item.type === 'string' ? item.type : '(no type)'}`);
+        }
+    }
+    return (0, transcript_tail_js_1.sliceSinceLastPrompt)(events, opts);
+};
+exports.projectPiEntries = projectPiEntries;

package/dist/presence.d.ts

@@ -0,0 +1,14 @@
+import type { GateMarker, GatePushMode } from './gate.js';
+export interface PresenceDeps {
+    env: NodeJS.ProcessEnv;
+    /** stdout of a probe command, or null when it fails, is missing, or times out. */
+    run: (cmd: string, args: string[]) => string | null;
+    now: () => number;
+}
+export declare const isAway: (deps?: PresenceDeps) => boolean;
+/**
+ * Presence for decidePush, probed only where it can change the verdict: quiet
+ * with no `high` marker is the one path that is otherwise silent.
+ */
+export declare const awayForGate: (pushMode: GatePushMode, marker: GateMarker, probe?: () => boolean) => boolean;
+//# sourceMappingURL=presence.d.ts.map

package/dist/presence.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.awayForGate = exports.isAway = void 0;
+/**
+ * Presence — is the user away from the terminal?
+ *
+ * The TS twin of `plugin/hooks/gate.sh` hwip_is_away (hwipit/plugin): the
+ * Claude Stop hook asks there, every `notify --auto` hook asks here, and both
+ * must answer alike. The quiet dial silences routine pushes because the user is
+ * watching the pane; an away user is not, so the answer becomes decidePush's
+ * `away`. Keep the probe order and fallbacks in sync with the bash side — the
+ * cases in presence.test.ts mirror its `away:` block in test-hwip-stop.sh.
+ *
+ * Away is the machine verdict below, or this session's own tmux pane being
+ * hidden (`paneHidden`): a keyboard or a tmux client says the user is at the
+ * desk, not which tmux session they are looking at.
+ *
+ * Threshold: HWIP_AWAY_SEC seconds (default 300, `0` disables, anything that is
+ * not a whole number of at most 9 digits falls back to the default). Probes,
+ * first answer wins:
+ *   1. inside tmux and no client attached to the server at all → away. Any
+ *      attached client means someone is at a tmux terminal, so switching the
+ *      one client between sessions does not make the MACHINE read as away (the
+ *      pane check above still asks about this session).
+ *   2. not over SSH and ioreg reports HIDIdleTime (macOS) → that decides, and
+ *      nothing below runs: tmux activity only sees keys typed into tmux, so a
+ *      user reading a browser would look idle to it. Inside tmux, "over SSH"
+ *      comes from the session environment (`show-environment`), which tmux
+ *      refreshes on every attach — the process's own SSH_CONNECTION is frozen
+ *      at server start.
+ *   3. inside tmux → the newest client_activity (SSH and non-macOS hosts).
+ * Anything else is present: an unreadable signal must never add a push.
+ */
+const child_process_1 = require("child_process");
+const AWAY_SEC_DEFAULT = 300;
+const PROBE_TIMEOUT_MS = 2000;
+const runProbe = (cmd, args) => {
+    const r = (0, child_process_1.spawnSync)(cmd, args, {
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        timeout: PROBE_TIMEOUT_MS,
+    });
+    return r.status === 0 ? (r.stdout ?? '') : null;
+};
+const defaultDeps = () => ({ env: process.env, run: runProbe, now: Date.now });
+const awayThresholdSec = (raw) => raw !== undefined && /^\d{1,9}$/.test(raw) ? Number(raw) : AWAY_SEC_DEFAULT;
+const hidIdleSec = (ioregOut) => {
+    const match = ioregOut?.match(/"HIDIdleTime" = (\d+)/);
+    return match ? Math.floor(Number(match[1]) / 1e9) : null;
+};
+const newestActivitySec = (clientsOut) => {
+    const stamps = clientsOut.split('\n').filter((l) => /^\d+$/.test(l)).map(Number);
+    return stamps.length > 0 ? Math.max(...stamps) : null;
+};
+// null = tmux had no answer for the variable, so the process env decides.
+const isOverSsh = (deps, inTmux) => {
+    const sessionVar = inTmux ? deps.run('tmux', ['show-environment', 'SSH_CONNECTION']) : null;
+    if (sessionVar !== null)
+        return sessionVar.startsWith('SSH_CONNECTION=');
+    return Boolean(deps.env.SSH_CONNECTION);
+};
+/**
+ * Is this session's tmux pane out of sight? Asks tmux about `$TMUX_PANE`:
+ * `#{session_attached}` (clients on its session), `#{window_active}` (its
+ * window is the session's current one), `#{pane_active}` and
+ * `#{window_zoomed_flag}` (a different pane zoomed over it hides it; a split
+ * that is merely not the active one is still on screen). A control-mode client
+ * (iTerm2 `tmux -CC`) makes a non-current window look hidden while it is on
+ * screen, so one attached anywhere reads as unknown; so does a window linked
+ * into several sessions, which tmux reports for just one of them (not
+ * detected). Anything short of a plain answer — not in tmux, no TMUX_PANE,
+ * tmux silent, output that is not four numbers — is not hidden.
+ */
+const paneHidden = (deps) => {
+    const pane = deps.env.TMUX_PANE;
+    if (!deps.env.TMUX || !pane)
+        return false;
+    const out = deps.run('tmux', [
+        'display-message', '-p', '-t', pane,
+        '#{session_attached} #{window_active} #{pane_active} #{window_zoomed_flag}',
+    ]);
+    if (out === null)
+        return false;
+    const fields = out.trim().split(/\s+/);
+    if (fields.length !== 4 || !fields.every((f) => /^\d+$/.test(f)))
+        return false;
+    const [attached, windowActive, paneActive, zoomed] = fields.map(Number);
+    const hidden = attached === 0 || windowActive === 0 || (zoomed !== 0 && paneActive === 0);
+    if (!hidden)
+        return false;
+    const control = deps.run('tmux', ['list-clients', '-F', '#{client_control_mode}']);
+    return !(control ?? '').split('\n').includes('1');
+};
+const machineAway = (deps, threshold) => {
+    // null = not in tmux, or no server answered; '' = a server with no clients.
+    const clients = deps.env.TMUX ? deps.run('tmux', ['list-clients', '-F', '#{client_activity}']) : null;
+    if (clients !== null && clients.trim() === '')
+        return true;
+    if (!isOverSsh(deps, clients !== null)) {
+        // -r -k -d 1: just the IOHIDSystem node (~4 KB), not its ~380 KB subtree.
+        const idle = hidIdleSec(deps.run('ioreg', ['-r', '-k', 'HIDIdleTime', '-d', '1', '-c', 'IOHIDSystem']));
+        if (idle !== null)
+            return idle >= threshold;
+    }
+    if (clients === null)
+        return false;
+    const newest = newestActivitySec(clients);
+    if (newest === null)
+        return false;
+    return Math.floor(deps.now() / 1000) - newest >= threshold;
+};
+const isAway = (deps = defaultDeps()) => {
+    const threshold = awayThresholdSec(deps.env.HWIP_AWAY_SEC);
+    if (threshold === 0)
+        return false;
+    return machineAway(deps, threshold) || paneHidden(deps);
+};
+exports.isAway = isAway;
+/**
+ * Presence for decidePush, probed only where it can change the verdict: quiet
+ * with no `high` marker is the one path that is otherwise silent.
+ */
+const awayForGate = (pushMode, marker, probe = exports.isAway) => pushMode === 'quiet' && marker !== 'high' && probe();
+exports.awayForGate = awayForGate;

package/dist/private-files.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Who a file hwip creates under the home folder belongs to when root runs it by `sudo` with HOME
+ * kept (macOS does): the person who typed `sudo`, so the next plain `hwip` can read what this
+ * one wrote. Null unless every sign agrees: root, `SUDO_UID`/`SUDO_GID` set to real ids, the path
+ * under the home folder, and the home folder owned by that same `SUDO_UID`. The last one is what
+ * stops a root whose HOME is `/root` (sudo resets it there on Linux) from handing root's folder
+ * to whoever ran `sudo`.
+ */
+export declare const sudoOwner: (path: string) => {
+    uid: number;
+    gid: number;
+} | null;
+/**
+ * Give a path root just created to the person who ran `sudo` (see `sudoOwner`). Best effort. The path
+ * itself, never what a link points at: whoever owns the folder can put a link where the new file was,
+ * and root following it would hand them a file of anyone's.
+ */
+export declare const handBackToSudoUser: (path: string) => void;
+/**
+ * `mkdir -p`: every folder it makes, not only the last, goes to the person who ran `sudo` when root
+ * makes it — a root-owned `~/.hwip` is one the next plain `hwip` cannot write in.
+ */
+export declare const mkdirHandedBack: (dir: string, mode?: number) => void;
+/**
+ * Make sure `path` exists before a plain write fills it, handing it back when root made it. For a
+ * caller whose write line is better left alone (it sits next to code others are changing); the
+ * write that follows keeps the owner, since it opens the same file.
+ */
+export declare const createdHandedBack: (path: string) => void;
+/** `mkdir` without `-p`: fails with EEXIST when it is there, so the caller can tell who made it first. */
+export declare const mkdirExclusiveHandedBack: (dir: string) => void;
+/**
+ * The directory exists and only its owner can enter it (0700). A symlink is left
+ * as it is: it points at a folder that may be shared on purpose (dotfiles), and
+ * what it points at is not ours to lock.
+ *
+ * Opened without following a link and changed through what was opened, so the folder looked at is the
+ * one changed: by name, a link put there after the look got its target locked instead. Where the
+ * platform has no such open (Windows, which has no such modes either), by name as before.
+ *
+ * A folder its owner cannot read (0377) cannot be opened, yet others may still write into it, so that one
+ * too is changed by name — when it is a folder of the caller's own, and unless root runs this (by either of
+ * its ids): root is who could lock a file of someone else's through a link put there after the look. A person
+ * can only lock their own.
+ */
+export declare const ensurePrivateDir: (dir: string) => void;
+/** The file exists and only its owner can read it (0600); its content is untouched. A link at the
+ *  end is left as it is: creating its target and then fixing only the link would leave a file of
+ *  someone's behind (C149 ②). An existing file is changed through an fd for the same reason. */
+export declare const ensurePrivateFile: (path: string) => void;
+//# sourceMappingURL=private-files.d.ts.map