@hwip/cli 0.0.1 → 0.1.1

package/dist/agent-rules-fetch.js

@@ -0,0 +1,275 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.refreshManifest = exports.rulesUrl = exports.syncManifestFromCache = exports.loadManifestFromCache = exports.resetActiveManifest = exports.getActiveManifestSource = exports.getActiveManifest = exports.compareManifestVersions = exports.validateManifest = exports.RULES_REFRESH_INTERVAL_MS = exports.RULES_CACHE_FILE = void 0;
+/**
+ * OTA delivery for agent detection rules (SPEC-AGENT-AWARENESS §S7).
+ *
+ * Agent UIs change on their release cadence, not ours: when Claude
+ * Code reshapes its status line, detection must be fixable by shipping
+ * DATA, not a new daemon. The listener therefore resolves its manifest
+ * as: valid remote fetch → valid disk cache → bundled defaults. Every
+ * tier fails closed to the next — a dead endpoint, corrupt cache, or
+ * hostile payload can never leave the listener without rules, and
+ * `disabledRuleIds` in a fetched manifest acts as a same-day
+ * kill-switch for a misfiring rule (no release, no restart).
+ *
+ * Version precedence: a fetched/cached manifest only activates when
+ * its version is >= the bundled one. npm publishes land in minutes
+ * while the server manifest ships with a full deploy, so a fresh cli
+ * routinely carries NEWER rules than the endpoint — without the gate,
+ * the older remote manifest would shadow every bundled rule fix until
+ * the server caught up. Server-side rollback still works: the server
+ * bumps the version even when reverting rule content.
+ */
+const fs_1 = require("fs");
+const path_1 = require("path");
+const config_js_1 = require("./config.js");
+const agent_state_js_1 = require("./agent-state.js");
+const agent_rules_default_js_1 = require("./agent-rules.default.js");
+const private_files_js_1 = require("./private-files.js");
+exports.RULES_CACHE_FILE = (0, path_1.join)(config_js_1.CONFIG_DIR, 'agent-rules.json');
+exports.RULES_REFRESH_INTERVAL_MS = 6 * 60 * 60 * 1000;
+// Matches the server-side serving cap; anything bigger is not a manifest.
+const MAX_MANIFEST_BYTES = 256 * 1024;
+const FETCH_TIMEOUT_MS = 10_000;
+const VALID_STATES = new Set(['working', 'blocked', 'idle', 'unknown']);
+const isStringArray = (v) => Array.isArray(v) && v.every((s) => typeof s === 'string');
+const isCondition = (v) => {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const c = v;
+    if (c.contains !== undefined && !isStringArray(c.contains))
+        return false;
+    if (c.regex !== undefined && !isStringArray(c.regex))
+        return false;
+    return true;
+};
+const isRule = (v) => {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const r = v;
+    if (typeof r.id !== 'string' || r.id.length === 0)
+        return false;
+    if (typeof r.state !== 'string' || !VALID_STATES.has(r.state))
+        return false;
+    // Safe integers, not merely finite. These numbers arrive from the server
+    // and decide behavior: a fractional priority orders rules by values no
+    // author can reason about, 1e21 outranks every rule ever written including
+    // the kill-switch, and a fractional tailLines slices a capture at a
+    // fraction of a line.
+    if (!Number.isSafeInteger(r.priority))
+        return false;
+    if (r.region !== undefined && r.region !== 'tail' && r.region !== 'whole')
+        return false;
+    if (r.tailLines !== undefined && (!Number.isSafeInteger(r.tailLines) || r.tailLines < 1 || r.tailLines > 200))
+        return false;
+    if (r.contains !== undefined && !isStringArray(r.contains))
+        return false;
+    if (r.regex !== undefined && !isStringArray(r.regex))
+        return false;
+    if (r.any !== undefined && (!Array.isArray(r.any) || !r.any.every(isCondition)))
+        return false;
+    if (r.not !== undefined && (!Array.isArray(r.not) || !r.not.every(isCondition)))
+        return false;
+    if (r.skipStateUpdate !== undefined && typeof r.skipStateUpdate !== 'boolean')
+        return false;
+    return true;
+};
+/**
+ * Structural validation of an untrusted manifest. Engine-version gate
+ * included: a manifest authored for a future engine is rejected whole —
+ * partial interpretation of unknown semantics is worse than falling
+ * back to bundled rules.
+ */
+const validateManifest = (value) => {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const m = value;
+    if (m.engineVersion !== agent_state_js_1.ENGINE_VERSION)
+        return null;
+    if (typeof m.version !== 'string' || m.version.length === 0)
+        return null;
+    if (m.disabledRuleIds !== undefined && !isStringArray(m.disabledRuleIds))
+        return null;
+    if (typeof m.agents !== 'object' || m.agents === null)
+        return null;
+    for (const rules of Object.values(m.agents)) {
+        if (!Array.isArray(rules) || !rules.every(isRule))
+            return null;
+    }
+    return value;
+};
+exports.validateManifest = validateManifest;
+/**
+ * Segment-wise numeric compare of dotted date versions
+ * ("2026.07.04.3"). Plain string compare fails on ".10" vs ".9";
+ * non-numeric segments compare as equal so a malformed version can
+ * never crash the refresh path.
+ */
+const compareManifestVersions = (a, b) => {
+    const as = a.split('.').map(Number);
+    const bs = b.split('.').map(Number);
+    const len = Math.max(as.length, bs.length);
+    for (let i = 0; i < len; i++) {
+        const d = (as[i] ?? 0) - (bs[i] ?? 0);
+        if (Number.isNaN(d))
+            continue;
+        if (d !== 0)
+            return d < 0 ? -1 : 1;
+    }
+    return 0;
+};
+exports.compareManifestVersions = compareManifestVersions;
+let activeManifest = agent_rules_default_js_1.DEFAULT_MANIFEST;
+let activeSource = 'bundled';
+const getActiveManifest = () => activeManifest;
+exports.getActiveManifest = getActiveManifest;
+const getActiveManifestSource = () => activeSource;
+exports.getActiveManifestSource = getActiveManifestSource;
+const activateManifest = (manifest, source) => {
+    activeManifest = manifest;
+    activeSource = source;
+    // Old manifest's compiled patterns must not pin memory forever.
+    (0, agent_state_js_1.clearRegexCache)();
+};
+/** Test hook. */
+const resetActiveManifest = () => {
+    activateManifest(agent_rules_default_js_1.DEFAULT_MANIFEST, 'bundled');
+};
+exports.resetActiveManifest = resetActiveManifest;
+/**
+ * Startup path (synchronous): promote the disk cache if it validates,
+ * else stay on bundled. Never throws — detection must work offline.
+ */
+const loadManifestFromCache = () => {
+    try {
+        const cache = JSON.parse((0, fs_1.readFileSync)(exports.RULES_CACHE_FILE, 'utf-8'));
+        const manifest = (0, exports.validateManifest)(cache.manifest);
+        if (manifest && (0, exports.compareManifestVersions)(manifest.version, agent_rules_default_js_1.DEFAULT_MANIFEST.version) >= 0) {
+            activateManifest(manifest, 'cache');
+        }
+    }
+    catch {
+        // Missing/corrupt cache — bundled rules carry the session.
+    }
+    return activeSource;
+};
+exports.loadManifestFromCache = loadManifestFromCache;
+/** mtime of the cache file the last time `syncManifestFromCache` looked; null = no file. */
+let cacheSeenMtime;
+/**
+ * Worker-thread path. A `worker_threads` Worker gets its own module instance,
+ * so `loadManifestFromCache` on the main thread leaves the worker on
+ * `DEFAULT_MANIFEST`, which would miss a fetched manifest's newer rules and its
+ * `disabledRuleIds` kill-switch for the life of the daemon (2026-09-14: a pi
+ * session whose pane the same rules classified `working` in-thread, back when
+ * the bundle carried claude rules only). Call this before each sweep: it
+ * reloads the cache only when the file changed, so the main thread's refresh
+ * reaches the worker on its next sweep without any message-protocol change.
+ */
+const syncManifestFromCache = () => {
+    let mtime;
+    try {
+        mtime = (0, fs_1.statSync)(exports.RULES_CACHE_FILE).mtimeMs;
+    }
+    catch {
+        mtime = null;
+    }
+    if (mtime === cacheSeenMtime)
+        return activeSource;
+    if (mtime === null) {
+        cacheSeenMtime = null;
+        return activeSource;
+    }
+    const source = (0, exports.loadManifestFromCache)();
+    // Latch only a read that landed. The cache is written without tmp+rename,
+    // so a stat/read from this thread can catch it half-written; a 304 refresh
+    // never rewrites the file, so latching that torn read would leave this
+    // thread on bundled rules for the daemon's life.
+    if (source === 'cache')
+        cacheSeenMtime = mtime;
+    return source;
+};
+exports.syncManifestFromCache = syncManifestFromCache;
+const readCachedEtag = () => {
+    try {
+        const cache = JSON.parse((0, fs_1.readFileSync)(exports.RULES_CACHE_FILE, 'utf-8'));
+        return typeof cache.etag === 'string' ? cache.etag : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+const rulesUrl = () => {
+    const override = (0, config_js_1.resolvedEnv)('HWIP_AGENT_RULES_URL');
+    if (override)
+        return override;
+    // The base the key goes to: a config file that cannot be read stops this (the refresh then keeps the
+    // current manifest) rather than fetching from the default stage while the account is on another.
+    const base = (0, config_js_1.resolveBaseUrl)(undefined, (0, config_js_1.loadConfig)());
+    return `${base.replace(/\/$/, '')}/agent-detection/manifest`;
+};
+exports.rulesUrl = rulesUrl;
+/**
+ * One refresh attempt: conditional GET, validate, persist, activate.
+ * All failure modes degrade to the current active manifest.
+ */
+const refreshManifest = async (fetchImpl = fetch) => {
+    let url;
+    try {
+        url = (0, exports.rulesUrl)();
+    }
+    catch (err) {
+        // The address itself is broken: saying so once beats an 'error' that reads as offline,
+        // and retrying a broken address on every tick would only repeat it.
+        console.error(`agent rules: ${err instanceof Error ? err.message : String(err)} — keeping the current manifest`);
+        return { source: activeSource, outcome: 'config-error' };
+    }
+    try {
+        const etag = readCachedEtag();
+        const res = await fetchImpl(url, {
+            headers: etag ? { 'If-None-Match': etag } : {},
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+        });
+        if (res.status === 304) {
+            return { source: activeSource, outcome: 'not-modified', version: activeManifest.version };
+        }
+        if (!res.ok) {
+            return { source: activeSource, outcome: 'error' };
+        }
+        const body = await res.text();
+        if (Buffer.byteLength(body, 'utf-8') > MAX_MANIFEST_BYTES) {
+            return { source: activeSource, outcome: 'invalid' };
+        }
+        const manifest = (0, exports.validateManifest)(JSON.parse(body));
+        if (!manifest) {
+            return { source: activeSource, outcome: 'invalid' };
+        }
+        const cache = {
+            etag: res.headers.get('etag') ?? undefined,
+            fetchedAt: new Date().toISOString(),
+            manifest,
+        };
+        try {
+            (0, private_files_js_1.mkdirHandedBack)(config_js_1.CONFIG_DIR);
+            (0, fs_1.writeFileSync)(exports.RULES_CACHE_FILE, JSON.stringify(cache, null, 2) + '\n');
+            (0, private_files_js_1.handBackToSudoUser)(exports.RULES_CACHE_FILE);
+        }
+        catch {
+            // Cache write failure is non-fatal: the manifest still
+            // activates for this process lifetime.
+        }
+        if ((0, exports.compareManifestVersions)(manifest.version, agent_rules_default_js_1.DEFAULT_MANIFEST.version) < 0) {
+            // Endpoint hasn't caught up to this build's bundled rules.
+            // Cache is still written above (the ETag stops refetch churn)
+            // but startup applies the same gate, so bundled stays active.
+            return { source: activeSource, outcome: 'stale-ignored', version: manifest.version };
+        }
+        activateManifest(manifest, 'remote');
+        return { source: 'remote', outcome: 'updated', version: manifest.version };
+    }
+    catch {
+        return { source: activeSource, outcome: 'error' };
+    }
+};
+exports.refreshManifest = refreshManifest;

package/dist/agent-rules.default.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Bundled default detection rules — the fallback when no OTA manifest
+ * has been fetched (or the fetched one fails validation, §S7).
+ *
+ * Rule content is authored HERE, from observation of each agent's UI.
+ * Do not import or transcribe rules from third-party projects: the
+ * bundled set is original work under this repo's license.
+ *
+ * Claude Code observations behind these rules (UI as of mid-2026):
+ * - While running, the status line shows an "esc to interrupt" hint
+ *   next to the spinner/progress text.
+ * - Blocking dialogs (permission requests, plan approval, question
+ *   forms) render a numbered/arrow-key option list with "esc" as the
+ *   cancel affordance and Enter as the confirm affordance.
+ * - At rest, the input box renders a `❯` prompt and the footer offers
+ *   "? for shortcuts".
+ * - The transcript viewer (ctrl+o) overlays the pane; the agent may
+ *   still be working underneath, so it must not change the state.
+ *
+ * Every agent here carries the same rules the server manifest publishes
+ * (hwip server/src/agent-rules/manifest.json, version 2026.10.18.1 — hwip#532, merged and deployed before this cli ships),
+ * so a listener that never reaches the endpoint classifies them too. A fetched
+ * manifest replaces this bundle whole for state reports; schedules read only
+ * this bundle. An agent without rules here
+ * reports `unknown`: honest ignorance beats guessed state, and
+ * harness-bench.test.ts fails the moment a rule set is half-filled.
+ */
+import { type DetectionManifest } from './agent-state.js';
+export declare const DEFAULT_MANIFEST: DetectionManifest;
+//# sourceMappingURL=agent-rules.default.d.ts.map

package/dist/agent-rules.default.js

@@ -0,0 +1,305 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MANIFEST = void 0;
+/**
+ * Bundled default detection rules — the fallback when no OTA manifest
+ * has been fetched (or the fetched one fails validation, §S7).
+ *
+ * Rule content is authored HERE, from observation of each agent's UI.
+ * Do not import or transcribe rules from third-party projects: the
+ * bundled set is original work under this repo's license.
+ *
+ * Claude Code observations behind these rules (UI as of mid-2026):
+ * - While running, the status line shows an "esc to interrupt" hint
+ *   next to the spinner/progress text.
+ * - Blocking dialogs (permission requests, plan approval, question
+ *   forms) render a numbered/arrow-key option list with "esc" as the
+ *   cancel affordance and Enter as the confirm affordance.
+ * - At rest, the input box renders a `❯` prompt and the footer offers
+ *   "? for shortcuts".
+ * - The transcript viewer (ctrl+o) overlays the pane; the agent may
+ *   still be working underneath, so it must not change the state.
+ *
+ * Every agent here carries the same rules the server manifest publishes
+ * (hwip server/src/agent-rules/manifest.json, version 2026.10.18.1 — hwip#532, merged and deployed before this cli ships),
+ * so a listener that never reaches the endpoint classifies them too. A fetched
+ * manifest replaces this bundle whole for state reports; schedules read only
+ * this bundle. An agent without rules here
+ * reports `unknown`: honest ignorance beats guessed state, and
+ * harness-bench.test.ts fails the moment a rule set is half-filled.
+ */
+const agent_state_js_1 = require("./agent-state.js");
+exports.DEFAULT_MANIFEST = {
+    engineVersion: agent_state_js_1.ENGINE_VERSION,
+    version: '2026.10.18.1',
+    agents: {
+        claude: [
+            {
+                // Transcript / verbose-output overlay: freeze state.
+                id: 'claude-transcript-overlay',
+                state: 'unknown',
+                priority: 1000,
+                skipStateUpdate: true,
+                any: [
+                    { contains: ['showing detailed transcript'] },
+                    { contains: ['ctrl+o to toggle'] },
+                ],
+            },
+            {
+                // Blocking dialog: an option list waiting on the user.
+                // "esc" alone is ambiguous (working shows "esc to
+                // interrupt"), so require a selection affordance too.
+                id: 'claude-blocked-dialog',
+                state: 'blocked',
+                priority: 900,
+                contains: ['esc'],
+                any: [
+                    { contains: ['do you want'] },
+                    { contains: ['enter to select'] },
+                    { contains: ['enter to confirm'] },
+                    { contains: ['to navigate'] },
+                ],
+                not: [{ contains: ['esc to interrupt'] }],
+            },
+            {
+                id: 'claude-working-interrupt-hint',
+                state: 'working',
+                priority: 800,
+                contains: ['esc to interrupt'],
+            },
+            {
+                // Newer CC skins drop the "esc to interrupt" hint; the
+                // live token counter on the spinner line
+                // ("✶ Churning… (1m 2s · ↓ 1.2k tokens)") only renders
+                // while the agent is actually running.
+                id: 'claude-working-token-counter',
+                state: 'working',
+                priority: 790,
+                regex: ['[↓↑]\\s?[\\d.,]+k? tokens'],
+            },
+            {
+                // Elapsed-time spinner suffix ("(12s · ..." / "(1m 2s ·")
+                // — second fallback for skins that hide the token counter
+                // early in a turn.
+                id: 'claude-working-elapsed-spinner',
+                state: 'working',
+                priority: 780,
+                regex: ['…\\s*\\((?:\\d+m )?\\d+s ·'],
+            },
+            {
+                // Compact pass ("✱ Compacting conversation… (51s)")
+                // renders neither the interrupt hint nor a token
+                // counter, but the session is busy and can't take
+                // input — without this it reads as idle.
+                id: 'claude-working-compacting',
+                state: 'working',
+                priority: 770,
+                contains: ['compacting conversation'],
+            },
+            {
+                // Idle prompt: `❯` at line start in the tail, with no
+                // dialog affordances around it.
+                id: 'claude-idle-prompt',
+                state: 'idle',
+                priority: 600,
+                regex: ['^\\s*❯'],
+                not: [
+                    { contains: ['do you want'] },
+                    { contains: ['enter to select'] },
+                ],
+            },
+            {
+                // Fallback idle signal when the prompt glyph is themed
+                // away: the shortcuts footer only renders at rest.
+                id: 'claude-idle-shortcuts-footer',
+                state: 'idle',
+                priority: 500,
+                contains: ['? for shortcuts'],
+            },
+        ],
+        codex: [
+            // Codex CLI v0.160.1, captured 2026-10-08 and 2026-10-15 (see
+            // harness-bench.test.ts). Its dialogs replace the composer and its
+            // footer with a `› 1.` option list over an `enter <verb> · esc …`
+            // line. At rest the composer sits over a `? for shortcuts` footer;
+            // while a turn runs both stay drawn under a `• Working (… • esc to
+            // interrupt)` line, so working must outrank idle.
+            //
+            // KNOWN GAP — no tool ever ran (the workspace was out of credits),
+            // so the tool-approval dialog was never drawn and has no rule. The
+            // idle rule refuses a tail holding the markers those dialogs and
+            // older Codex approval prompts draw — a `› 1.` option list, a
+            // `(y)`/`(n)` key hint, a `· esc …` footer, `enter to confirm` or
+            // `esc to cancel` — so an approval dialog that kept the footer
+            // reads `unknown` as long as it draws one of them. One that draws
+            // none would read `idle`; capture it before trusting this rule
+            // further.
+            {
+                id: 'codex-blocked-hooks-review',
+                state: 'blocked',
+                priority: 900,
+                contains: ['hooks need review', 'enter confirm'],
+            },
+            {
+                id: 'codex-blocked-usage-limit',
+                state: 'blocked',
+                priority: 900,
+                contains: ['usage limit reached', 'enter select'],
+            },
+            {
+                id: 'codex-blocked-update',
+                state: 'blocked',
+                priority: 900,
+                contains: ['update available', 'enter continue'],
+            },
+            {
+                id: 'codex-blocked-trust-dialog',
+                state: 'blocked',
+                priority: 900,
+                contains: ['trust this folder', 'enter continue'],
+            },
+            {
+                id: 'codex-working-interrupt-hint',
+                state: 'working',
+                priority: 800,
+                contains: ['esc to interrupt'],
+            },
+            {
+                // The footer is gone while a draft is typed, so a pane with
+                // unsent text reads `unknown` — the safe side for a schedule.
+                // 30 lines, not the default 10: a dialog marker drawn high
+                // above a kept footer must still be in view of `not`.
+                id: 'codex-idle-shortcuts-footer',
+                state: 'idle',
+                priority: 600,
+                tailLines: 30,
+                contains: ['? for shortcuts'],
+                not: [
+                    { regex: ['^\\s*›\\s*\\d+\\.'] },
+                    { regex: ['·\\s*esc '] },
+                    { regex: ['enter (?:to )?(?:confirm|select|continue)'] },
+                    { regex: ['esc to (?:cancel|deny)'] },
+                    { regex: ['\\([yn]\\)\\s*$'] },
+                ],
+            },
+        ],
+        gemini: [
+            {
+                // Tool approval (Shell, Edit, WriteFile), captured 2026-10-18 on
+                // Gemini CLI v0.46.0: a rounded box whose answers start with
+                // `│ ● 1. Allow once` under a boxed question line. Keyed on
+                // both, not the bare phrase, so agent text or a tool output box
+                // printing the answer row is not a dialog. The
+                // dialog draws no footer and hides the input box; 30 lines
+                // because a long diff sits between the header and the answers
+                // and a later notice box can be drawn below it.
+                id: 'gemini-blocked-tool-approval',
+                state: 'blocked',
+                priority: 900,
+                tailLines: 30,
+                regex: ['^\\s*│\\s+(?:●\\s+)?1\\.\\s+allow once'],
+                any: [
+                    { regex: ['^\\s*│ allow execution of .*\\?\\s*│$'] },
+                    { regex: ['^\\s*│ apply this change\\?\\s*│$'] },
+                ],
+                // The input box is hidden while Gemini asks; with it on screen the box is the agent's own text.
+                not: [{ contains: ['type your message'] }],
+            },
+            {
+                // Observed on Gemini CLI v0.46.0.
+                id: 'gemini-blocked-trust-dialog',
+                state: 'blocked',
+                priority: 900,
+                tailLines: 30,
+                contains: ['do you trust the files in this folder?'],
+            },
+            {
+                id: 'gemini-working-cancel-hint',
+                state: 'working',
+                priority: 800,
+                contains: ['esc to cancel'],
+            },
+            {
+                id: 'gemini-idle-input-placeholder',
+                state: 'idle',
+                priority: 600,
+                contains: ['type your message'],
+                not: [{ contains: ['esc to cancel'] }],
+            },
+        ],
+        opencode: [
+            // Written from the screen strings recorded in the C136 backlog
+            // row (opencode 1.18.35) and a user's permission screen, then
+            // checked against panes captured 2026-10-18 on opencode 2.0.29
+            // (harness bench: bash and edit requests). The button wording
+            // differs between versions (`Allow always` vs `Always allow`),
+            // hence the rule keys on the `Permission required` title line,
+            // guarded by any button or footer string so the phrase in tool
+            // output or agent text alone is not a dialog. tailLines 30
+            // because an edit request draws its diff between that line and
+            // the buttons. Other prompts (the agent asking a question) are
+            // not captured and report `unknown`.
+            // No idle rule: at rest the footer is only `ctrl+p commands`,
+            // which says nothing the absence of `esc interrupt` does not.
+            {
+                id: 'opencode-blocked-permission',
+                state: 'blocked',
+                priority: 900,
+                tailLines: 30,
+                contains: ['permission required'],
+                any: [
+                    { contains: ['allow once'] },
+                    { contains: ['reject'] },
+                    { contains: ['enter confirm'] },
+                ],
+            },
+            {
+                id: 'opencode-working-interrupt-hint',
+                state: 'working',
+                priority: 800,
+                contains: ['esc interrupt'],
+            },
+        ],
+        pi: [
+            {
+                // Observed on pi v0.85.1. `blocked` was captured on a picker
+                // drawn through ctx.ui.custom by an ask_user_question
+                // extension (hint `↑↓ navigate • Enter select • Esc cancel`).
+                // pi core's own extension dialogs end their hint with
+                // `escape/ctrl+c cancel` under the default keybindings —
+                // matched by the same pattern but read from the vendor file,
+                // not captured. A user who rebinds tui.select.cancel changes
+                // that text and falls back to `working` or `idle`.
+                id: 'pi-blocked-dialog',
+                state: 'blocked',
+                priority: 900,
+                any: [
+                    { regex: ['enter\\b.*\\besc(?:ape)?(?:/ctrl\\+c)?\\s+cancel\\s*$'] },
+                    { regex: ['enter to \\w+ • esc to go back\\s*$'] },
+                ],
+            },
+            {
+                // pi's default Loader frames at the start of a line, bare or
+                // inside the editor's top border — anchored so a braille glyph
+                // mid-line in tool output does not count. An extension that
+                // swaps the indicator frames reports `idle` while working.
+                id: 'pi-working-spinner',
+                state: 'working',
+                priority: 800,
+                regex: ['^\\s*(?:─+\\s*)?[⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏] +[a-z]'],
+            },
+            {
+                // Keys on the footer's context-usage figure (`5.0%/1.0M`, or
+                // `?/1.0M` right after a compaction), which renders from the
+                // first frame, before any token count exists. The footer
+                // truncates its stats line with `...` when wider than the
+                // pane and this figure is its last item, so a pane too narrow
+                // for the stats reports `unknown` rather than `idle`.
+                id: 'pi-idle-context-footer',
+                state: 'idle',
+                priority: 600,
+                regex: ['(?:^|\\s)(?:\\d+(?:\\.\\d+)?%|\\?)/\\d+(?:\\.\\d+)?[km]?\\b'],
+            },
+        ],
+    },
+};

package/dist/agent-session.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Stable agent-session grouping when running inside a tmux agent session, so a
+ * push or hook event files under the same session key as the listener's own
+ * pushes — surviving Claude session-UUID rotation, and letting the phone open
+ * the agent chat (with its live terminal and key row) instead of a bare push
+ * screen: `buildNotificationDeepLink` needs BOTH fields
+ * (apps/mobile/src/navigation/linking.ts).
+ *
+ * The device id MUST equal the listener's `computeListenerDeviceId`, so it's
+ * resolved the same way (machine-id hash → sticky file → hostname) via the
+ * shared read-only helper — NOT a bare hostname hash, which drifts from the
+ * listener's id when a machine id is readable and files the push under a
+ * non-matching session key.
+ *
+ * One definition for every sender in this package: `hwip notify` (hwip-hook.ts)
+ * and `hwip ask` (ask.ts). The MCP server has its own copy of the same rule
+ * (mcp-server/src/config.ts) because it is a separate package.
+ */
+export declare const agentSessionContext: () => {
+    agentDeviceId: string;
+    agentSessionName: string;
+} | null;
+//# sourceMappingURL=agent-session.d.ts.map

package/dist/agent-session.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentSessionContext = void 0;
+const node_child_process_1 = require("node:child_process");
+const listener_device_id_js_1 = require("./listener-device-id.js");
+/**
+ * Stable agent-session grouping when running inside a tmux agent session, so a
+ * push or hook event files under the same session key as the listener's own
+ * pushes — surviving Claude session-UUID rotation, and letting the phone open
+ * the agent chat (with its live terminal and key row) instead of a bare push
+ * screen: `buildNotificationDeepLink` needs BOTH fields
+ * (apps/mobile/src/navigation/linking.ts).
+ *
+ * The device id MUST equal the listener's `computeListenerDeviceId`, so it's
+ * resolved the same way (machine-id hash → sticky file → hostname) via the
+ * shared read-only helper — NOT a bare hostname hash, which drifts from the
+ * listener's id when a machine id is readable and files the push under a
+ * non-matching session key.
+ *
+ * One definition for every sender in this package: `hwip notify` (hwip-hook.ts)
+ * and `hwip ask` (ask.ts). The MCP server has its own copy of the same rule
+ * (mcp-server/src/config.ts) because it is a separate package.
+ */
+const agentSessionContext = () => {
+    if (!process.env.TMUX)
+        return null;
+    // A pi subagent pane carries its own wire name (<#S>.<pane> — the
+    // listener's naming) in this env, set by the extension for its notify
+    // children. It wins over #S, which would file the push under the parent.
+    const fromEnv = process.env.HWIP_AGENT_SESSION_NAME?.trim();
+    if (fromEnv)
+        return { agentDeviceId: (0, listener_device_id_js_1.listenerDeviceId)(), agentSessionName: fromEnv };
+    let name;
+    try {
+        name = (0, node_child_process_1.execFileSync)('tmux', ['display-message', '-p', '#S'], { encoding: 'utf-8' }).trim();
+    }
+    catch {
+        return null;
+    }
+    if (!name)
+        return null;
+    return { agentDeviceId: (0, listener_device_id_js_1.listenerDeviceId)(), agentSessionName: name };
+};
+exports.agentSessionContext = agentSessionContext;