@hwip/cli 0.0.1 → 0.1.0

package/dist/command-refusal.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Telling the phone why a command it sent was not typed (backlog C9).
+ *
+ * A refusal used to leave one log line on this machine, so the phone kept
+ * showing "sent" for a command that never landed. The addressed listener now
+ * answers on the ephemeral relay it already holds open, with
+ *
+ *     { subtype: 'agent.command.refused', sessionName, pushId, reason }
+ *
+ * (the relay broadcasts it to the account's devices and stamps `deviceId` with
+ * this listener, as for every listener frame). The app matches it to the push
+ * it sent by `pushId`. Codes only: never the command text, keys or paths. A
+ * listener or an app that does not know the subtype ignores it; a code the app
+ * does not know is shown as a generic refusal.
+ *
+ * Stream input (`agent.command.input`) already had its own answer, the
+ * `input_rejected` stream-error frame; it carries the same codes in an
+ * optional `reason` field.
+ */
+export declare const COMMAND_REFUSALS: readonly ["rate_limited", "unknown_session", "subagent_view_only", "shell_pane", "shell_input", "unknown_key", "invalid_command", "attachment_failed", "sealed_rejected", "inject_failed", "e2ee_required", "prompt_changed", "schedule_invalid", "schedule_limit", "schedule_failed"];
+export type CommandRefusal = (typeof COMMAND_REFUSALS)[number];
+export interface CommandRefusedFrame {
+    subtype: 'agent.command.refused';
+    sessionName: string;
+    pushId: string;
+    reason: CommandRefusal;
+}
+export declare const commandRefusedFrame: (sessionName: string, pushId: string, reason: CommandRefusal) => CommandRefusedFrame;
+/**
+ * What the relay may learn. `shell_input` (a control character or newline in
+ * the text), `invalid_command` (empty text) and the two schedule reasons (a
+ * limit hit, a field wrong) are read off the text itself; for a sealed command
+ * that would tell the relay something about plaintext it must not see, so they
+ * go out as the generic `sealed_rejected`.
+ */
+export declare const reasonForPhone: (reason: CommandRefusal, sealed: boolean) => CommandRefusal;
+export declare const isSessionStateRefusal: (reason: CommandRefusal) => boolean;
+/** Frames per session per minute. A phone flooding a session refuses itself blind past this; the log keeps counting. */
+export declare const REFUSAL_FRAMES_PER_MINUTE = 30;
+export declare const REFUSAL_WINDOW_MS = 60000;
+/** Sessions the limiter tracks inside one window; the scan per call is bounded by this. */
+export declare const REFUSAL_TRACKED_SESSIONS = 256;
+export interface RefusalLimiter {
+    (key: string, now?: number): boolean;
+    /** Sessions currently tracked. */
+    size: () => number;
+}
+/** A sliding count per key: `max` yeses per `windowMs`, idle keys forgotten. */
+export declare const createRefusalLimiter: (max: number, windowMs: number, maxKeys?: number) => RefusalLimiter;
+/** The function the listener's WS loop hands `handlePush`: one frame per refusal, within the per-session limit. */
+export declare const createRefusalReporter: (send: (data: Record<string, unknown>) => void, allow: RefusalLimiter) => ((refusal: {
+    sessionName: string;
+    pushId: string;
+    reason: CommandRefusal;
+}) => void);
+//# sourceMappingURL=command-refusal.d.ts.map

package/dist/command-refusal.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * Telling the phone why a command it sent was not typed (backlog C9).
+ *
+ * A refusal used to leave one log line on this machine, so the phone kept
+ * showing "sent" for a command that never landed. The addressed listener now
+ * answers on the ephemeral relay it already holds open, with
+ *
+ *     { subtype: 'agent.command.refused', sessionName, pushId, reason }
+ *
+ * (the relay broadcasts it to the account's devices and stamps `deviceId` with
+ * this listener, as for every listener frame). The app matches it to the push
+ * it sent by `pushId`. Codes only: never the command text, keys or paths. A
+ * listener or an app that does not know the subtype ignores it; a code the app
+ * does not know is shown as a generic refusal.
+ *
+ * Stream input (`agent.command.input`) already had its own answer, the
+ * `input_rejected` stream-error frame; it carries the same codes in an
+ * optional `reason` field.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRefusalReporter = exports.createRefusalLimiter = exports.REFUSAL_TRACKED_SESSIONS = exports.REFUSAL_WINDOW_MS = exports.REFUSAL_FRAMES_PER_MINUTE = exports.isSessionStateRefusal = exports.reasonForPhone = exports.commandRefusedFrame = exports.COMMAND_REFUSALS = void 0;
+exports.COMMAND_REFUSALS = [
+    /** More commands for this session than the per-minute budget allows. */
+    'rate_limited',
+    /** No tmux session of that name on this machine. */
+    'unknown_session',
+    /** The session is a subagent pane: view-only, the phone cannot type into it. */
+    'subagent_view_only',
+    /** The pane sits at a shell prompt and is not an `hwip sh` session. */
+    'shell_pane',
+    /** An `hwip sh` session refuses the input: attachments, control characters, a newline in an insert. */
+    'shell_input',
+    /** A key name that is not on the allowed list. */
+    'unknown_key',
+    /** The command makes no sense as sent (empty, or an insert beside a body). */
+    'invalid_command',
+    /** A sealed attachment would not open or was missing, so the command was not typed. */
+    'attachment_failed',
+    /** A sealed command that did not check out: sender key, label, replay. */
+    'sealed_rejected',
+    /** The checks passed but tmux would not take the keystrokes. */
+    'inject_failed',
+    /** The command came in plaintext, and this listener only takes sealed ones (body, keys, insert or attachment). */
+    'e2ee_required',
+    /** The command was bound to a blocked prompt (`ifPrompt`) and the screen shows another one, or none. */
+    'prompt_changed',
+    /** A schedule request that is malformed, past a limit on one schedule, or names no schedule of that session. */
+    'schedule_invalid',
+    /** A schedule request that would make more schedules than a machine may have. */
+    'schedule_limit',
+    /** A valid schedule request this machine could not carry out: its schedule files or session record would not read or write. */
+    'schedule_failed',
+];
+/** A push chooses these two strings; the listener echoes no more than this of either. */
+const MAX_ECHO_CHARS = 200;
+/** The first MAX_ECHO_CHARS UTF-16 units, minus a surrogate pair the cap would cut in half. */
+const capEcho = (text) => {
+    const cut = text.slice(0, MAX_ECHO_CHARS);
+    const last = cut.charCodeAt(cut.length - 1);
+    return last >= 0xd800 && last <= 0xdbff ? cut.slice(0, -1) : cut;
+};
+const commandRefusedFrame = (sessionName, pushId, reason) => ({
+    subtype: 'agent.command.refused',
+    sessionName: capEcho(sessionName),
+    pushId: capEcho(pushId),
+    reason,
+});
+exports.commandRefusedFrame = commandRefusedFrame;
+/** Reasons read off the plaintext of a sealed command, which the relay must not learn. */
+const TEXT_DEPENDENT_REFUSALS = ['shell_input', 'invalid_command', 'schedule_invalid', 'schedule_limit'];
+/**
+ * What the relay may learn. `shell_input` (a control character or newline in
+ * the text), `invalid_command` (empty text) and the two schedule reasons (a
+ * limit hit, a field wrong) are read off the text itself; for a sealed command
+ * that would tell the relay something about plaintext it must not see, so they
+ * go out as the generic `sealed_rejected`.
+ */
+const reasonForPhone = (reason, sealed) => sealed && TEXT_DEPENDENT_REFUSALS.includes(reason) ? 'sealed_rejected' : reason;
+exports.reasonForPhone = reasonForPhone;
+/**
+ * Reasons that come from the state of the session or the listener, never from
+ * the text. Only these ride a stream `input_rejected` frame: its text may be
+ * sealed, and a refusal that depends on it must not be told to the relay.
+ */
+const SESSION_STATE_REFUSALS = [
+    'rate_limited', 'unknown_session', 'subagent_view_only', 'shell_pane', 'inject_failed', 'prompt_changed',
+];
+const isSessionStateRefusal = (reason) => SESSION_STATE_REFUSALS.includes(reason);
+exports.isSessionStateRefusal = isSessionStateRefusal;
+/** Frames per session per minute. A phone flooding a session refuses itself blind past this; the log keeps counting. */
+exports.REFUSAL_FRAMES_PER_MINUTE = 30;
+exports.REFUSAL_WINDOW_MS = 60_000;
+/** Sessions the limiter tracks inside one window; the scan per call is bounded by this. */
+exports.REFUSAL_TRACKED_SESSIONS = 256;
+/** A sliding count per key: `max` yeses per `windowMs`, idle keys forgotten. */
+const createRefusalLimiter = (max, windowMs, maxKeys = exports.REFUSAL_TRACKED_SESSIONS) => {
+    const seen = new Map();
+    const allow = ((key, now = Date.now()) => {
+        for (const [k, stamps] of seen) {
+            if (stamps.length === 0 || now - stamps[stamps.length - 1] >= windowMs)
+                seen.delete(k);
+        }
+        // A push picks the session name it asks about: past the cap, a name that is
+        // not already tracked gets no frame rather than a map entry.
+        if (!seen.has(key) && seen.size >= maxKeys)
+            return false;
+        const recent = (seen.get(key) ?? []).filter((t) => now - t < windowMs);
+        if (recent.length >= max) {
+            seen.set(key, recent);
+            return false;
+        }
+        recent.push(now);
+        seen.set(key, recent);
+        return true;
+    });
+    allow.size = () => seen.size;
+    return allow;
+};
+exports.createRefusalLimiter = createRefusalLimiter;
+/** The function the listener's WS loop hands `handlePush`: one frame per refusal, within the per-session limit. */
+const createRefusalReporter = (send, allow) => ({ sessionName, pushId, reason }) => {
+    if (!allow(sessionName))
+        return;
+    send({ ...(0, exports.commandRefusedFrame)(sessionName, pushId, reason) });
+};
+exports.createRefusalReporter = createRefusalReporter;

package/dist/command-scan.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Scan the machine's installed agent skills into a name-only catalog.
+ *
+ * Payload discipline (plan PLAN-13-16-18): paths never leave this machine, so
+ * the output carries skill names and nothing else.
+ *
+ * An entry is the slash command itself, so it carries whatever prefix the agent
+ * registers the skill under (`AGENT_SKILL_PREFIX`, plugin names for Claude Code).
+ *
+ * Names come from the directory, not from the file — an ASSUMPTION, not a rule
+ * the agents enforce: pi resolves a skill's name as `frontmatter.name` and only
+ * falls back to the directory (`dist/core/skills.js:244`, pi 0.85.1), and its
+ * docs say so outright ("Pi allows skill names to differ from their parent
+ * directory"). It holds on every skill measured here — 132/132 under
+ * `~/.claude/skills` and the installed plugins (2026-09-13), 12/12 under
+ * `~/.agents/skills` (2026-09-13) — and a skill that breaks it shows the user a
+ * command that does not run, which is the same as not listing it.
+ *
+ * Reading the file would buy the real name, and cost a YAML parser this scanner
+ * is not equipped to be: 42 of 43 user skills quote their description and one
+ * uses a folded scalar, so the regex this replaced shipped the quotes and
+ * truncated to an unbalanced one. The file is opened for nothing but its own
+ * existence until a divergent skill is actually measured.
+ */
+export interface AgentCommandEntry {
+    /** What the user types after `/` — see `AGENT_SKILL_PREFIX`. */
+    name: string;
+}
+/** agentKind -> skill entries; agents with no skills are omitted. */
+export type AgentCommandCatalog = Record<string, AgentCommandEntry[]>;
+/** Serialized-catalog budget. Names-only measures ~2KB here; ws frames die at 128KB. */
+export declare const PAYLOAD_LIMIT_BYTES: number;
+export interface ScanResult {
+    catalog: AgentCommandCatalog;
+    /** Skills cut to fit the budget. Non-zero is worth a log line — never shrink silently. */
+    dropped: number;
+}
+/**
+ * Scan every agent's skill directories into one catalog. A directory that is
+ * absent contributes nothing; a directory that exists and cannot be read throws,
+ * and the caller keeps its previous catalog rather than publishing an empty one.
+ * Dedup is within each agentKind only — the same skill installed for claude and
+ * pi legitimately appears in both.
+ */
+export declare const scanAgentCommands: (homeDir: string) => ScanResult;
+//# sourceMappingURL=command-scan.d.ts.map

package/dist/command-scan.js

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanAgentCommands = exports.PAYLOAD_LIMIT_BYTES = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const agents_js_1 = require("./agents.js");
+/**
+ * What each agent registers its skills as. The catalog exists to be typed into
+ * the agent, so it carries the invocation token, not the bare directory name.
+ *
+ * pi registers `skill:<name>` (`docs/skills.md § Skill Commands`, and
+ * `` `skill:${skill.name}` `` in its bundle, pi 0.85.1); typing `/01-plan` in a
+ * pi session was observed to abort rather than run the skill (2026-09-13).
+ * Claude Code's user skills are `/<name>`; its PLUGIN skills are
+ * `/<plugin>:<name>`, so those get their prefix from the install entry instead.
+ */
+const AGENT_SKILL_PREFIX = {
+    pi: 'skill:',
+};
+/** Agents that register skills filed under grouping folders — see `scanSkillDir`. */
+const AGENT_SKILL_RECURSIVE = new Set(['pi']);
+/** Serialized-catalog budget. Names-only measures ~2KB here; ws frames die at 128KB. */
+exports.PAYLOAD_LIMIT_BYTES = 64 * 1024;
+/**
+ * True when `<dir>/SKILL.md` is a readable file. This is the whole membership
+ * test: it rejects non-skill directories, and it rejects dangling symlinks
+ * (`~/.agents/skills` had three) because the stat resolves through the link.
+ */
+const isSkillDir = (dir) => {
+    try {
+        return (0, fs_1.statSync)((0, path_1.join)(dir, 'SKILL.md')).isFile();
+    }
+    catch {
+        return false;
+    }
+};
+/** A directory that is simply not there is not an error — every other one is. */
+const isMissing = (err) => {
+    const code = err?.code;
+    return code === 'ENOENT' || code === 'ENOTDIR';
+};
+/**
+ * Directory entries, or none when the directory does not exist.
+ *
+ * Anything else — EACCES on a mode-000 skills dir, EIO on a stale network mount
+ * — is rethrown rather than read as "no skills". Swallowing it would report an
+ * empty catalog and blank the phone's menu, which is precisely the outcome the
+ * listener's try/catch keeps the previous catalog to avoid.
+ */
+const entriesOf = (dir) => {
+    try {
+        return (0, fs_1.readdirSync)(dir);
+    }
+    catch (err) {
+        if (isMissing(err))
+            return [];
+        throw err;
+    }
+};
+/**
+ * How deep below a skills root a `SKILL.md` is still found. pi walks the tree
+ * (`loadSkillsFromDirInternal`, `dist/core/skills.js:160`), so a skill filed
+ * under a grouping folder is real to it; two levels covers the grouping folders
+ * its docs describe without turning a stray checkout into a scan of the disk.
+ */
+const MAX_SKILL_DEPTH = 3;
+/**
+ * Skill directory names under `dir`. A directory holding `SKILL.md` IS the
+ * skill and is not descended into — that is pi's own rule, and it keeps a
+ * skill's bundled fixtures from being read as more skills.
+ *
+ * `recursive` mirrors the agent: pi groups skills in folders, while Claude Code
+ * registers exactly `~/.claude/skills/<name>` — descending there would invent
+ * commands out of directories it holds but does not register (`_shared/`).
+ */
+const scanSkillDir = (dir, recursive = false, depth = 1) => {
+    const names = [];
+    for (const entry of entriesOf(dir)) {
+        if (entry.startsWith('.') || entry === 'node_modules')
+            continue;
+        const child = (0, path_1.join)(dir, entry);
+        if (isSkillDir(child)) {
+            names.push(entry);
+        }
+        else if (recursive && depth < MAX_SKILL_DEPTH) {
+            names.push(...scanSkillDir(child, true, depth + 1));
+        }
+    }
+    return names;
+};
+/**
+ * Plugin skills live at `<installPath>/skills/<name>/SKILL.md`. Only install paths
+ * listed in `installed_plugins.json` are scanned — the plugin cache also holds
+ * uninstalled marketplace entries (514 of 710 on this machine) that must not
+ * appear.
+ */
+const scanClaudePlugins = (home) => {
+    let parsed;
+    try {
+        parsed = JSON.parse((0, fs_1.readFileSync)((0, path_1.join)(home, '.claude', 'plugins', 'installed_plugins.json'), 'utf-8'));
+    }
+    catch {
+        return [];
+    }
+    const names = [];
+    for (const [key, installs] of Object.entries(parsed.plugins ?? {})) {
+        // Key is `<plugin>@<marketplace>`; the command prefix is the plugin half.
+        const plugin = key.split('@')[0];
+        for (const install of installs ?? []) {
+            if (!install.installPath)
+                continue;
+            names.push(...scanSkillDir((0, path_1.join)(install.installPath, 'skills')).map((name) => `${plugin}:${name}`));
+        }
+    }
+    return names;
+};
+/** Byte length of the serialized catalog — the cap the ws frame actually feels. */
+const payloadBytes = (catalog) => Buffer.byteLength(JSON.stringify(catalog), 'utf-8');
+/**
+ * Scan every agent's skill directories into one catalog. A directory that is
+ * absent contributes nothing; a directory that exists and cannot be read throws,
+ * and the caller keeps its previous catalog rather than publishing an empty one.
+ * Dedup is within each agentKind only — the same skill installed for claude and
+ * pi legitimately appears in both.
+ */
+const scanAgentCommands = (homeDir) => {
+    const catalog = {};
+    for (const [agentId, dirs] of Object.entries(agents_js_1.AGENT_SKILL_DIRS)) {
+        const prefix = AGENT_SKILL_PREFIX[agentId] ?? '';
+        const recursive = AGENT_SKILL_RECURSIVE.has(agentId);
+        const names = dirs.flatMap((dir) => scanSkillDir((0, path_1.join)(homeDir, dir), recursive).map((name) => `${prefix}${name}`));
+        if (agentId === 'claude')
+            names.push(...scanClaudePlugins(homeDir));
+        const merged = [...new Set(names)].map((name) => ({ name }));
+        if (merged.length > 0)
+            catalog[agentId] = merged;
+    }
+    // Enforce the serialized budget by dropping whole skills from the tail. The
+    // catalog is ~2KB in practice, so this loop is a backstop, not a hot path —
+    // it re-measures the real payload each pass rather than keeping a running
+    // subtraction that no realistic input would ever exercise.
+    let dropped = 0;
+    while (payloadBytes(catalog) > exports.PAYLOAD_LIMIT_BYTES) {
+        const lastAgent = Object.keys(catalog).pop();
+        if (!lastAgent)
+            break;
+        catalog[lastAgent].pop();
+        dropped += 1;
+        if (catalog[lastAgent].length === 0)
+            delete catalog[lastAgent];
+    }
+    return { catalog, dropped };
+};
+exports.scanAgentCommands = scanAgentCommands;

package/dist/command-seal.d.ts

@@ -0,0 +1,57 @@
+/**
+ * `hwip agent send` (F2): the message goes to the target listener inside a push-v1 envelope, so the
+ * server relays it and reads nothing of what is typed into the other session.
+ *
+ * Every message is sealed, as every `hwip ask` question is (ask-seal.ts): when that cannot be done it is refused, never sent
+ * in the clear. No phone app is needed — the target is a computer.
+ *
+ * The receiving listener takes a command only from a device whose key it can check, and the server stamps a send made with
+ * an API key `api_<keyId>`, which names no machine. So the sealed label carries `from`, this machine's device id; the listener
+ * admits it by the key the account lists for that id and the one it pinned.
+ *
+ * Who reads the message is the account's device list: the target's slot is the listener's own, and every other listed device
+ * that has a key (a phone's bubble opens) gets one. Each device on the list is pinned on the way (`trust-pins.ts`), the target
+ * included, so no `hwip trust` comes first; a key that changed replaces its pin with one warning.
+ *
+ * Nothing here logs or returns a decrypt or encrypt error's message.
+ */
+import { type DeviceRecipient, type PushBodyInput } from './crypto.js';
+import { type AskSealDeps, type SealedFields } from './ask-seal.js';
+import { type CommandSeqRefusal } from './command-seq.js';
+import { type RegisterWhy } from './self-register.js';
+export type CommandSealDeps = Pick<AskSealDeps, 'loadKeys' | 'self' | 'listDevices' | 'register' | 'trustPath' | 'warn'> & {
+    /** The next command number from the counter every sender on this machine shares. */
+    nextNumber?: () => Promise<number | {
+        refused: CommandSeqRefusal;
+    }>;
+    seal?: (content: PushBodyInput, recipients: DeviceRecipient[]) => Promise<SealedFields & {
+        isEncrypted: true;
+    }>;
+};
+export type CommandRefusal = 'keystore' | 'devices' | 'self-unlisted' | 'target-unlisted' | 'number-locked' | 'number-unusable' | 'encrypt';
+export declare const COMMAND_REFUSAL_TEXT: Record<CommandRefusal, string>;
+export declare const commandRefusalMessage: (cause: CommandRefusal, why?: RegisterWhy) => string;
+/** What `POST /pushes/send` gets for an `agent.command`: the sealed fields and no text at all. */
+export type AgentCommandPayload = {
+    targetDeviceId: string;
+    agentSessionName: string;
+    isEncrypted: true;
+} & SealedFields;
+export type PreparedCommand = {
+    kind: 'sealed';
+    fields: SealedFields;
+} | {
+    kind: 'refused';
+    cause: CommandRefusal;
+    why?: RegisterWhy;
+};
+/**
+ * Seal `message` for `session` on `targetDeviceId`.
+ * The caller sends `sealed` with the returned fields (body, key, slots) and tells the user of `refused` without sending.
+ */
+export declare const sealedCommand: (command: {
+    targetDeviceId: string;
+    session: string;
+    message: string;
+}, deps: CommandSealDeps) => Promise<PreparedCommand>;
+//# sourceMappingURL=command-seal.d.ts.map

package/dist/command-seal.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * `hwip agent send` (F2): the message goes to the target listener inside a push-v1 envelope, so the
+ * server relays it and reads nothing of what is typed into the other session.
+ *
+ * Every message is sealed, as every `hwip ask` question is (ask-seal.ts): when that cannot be done it is refused, never sent
+ * in the clear. No phone app is needed — the target is a computer.
+ *
+ * The receiving listener takes a command only from a device whose key it can check, and the server stamps a send made with
+ * an API key `api_<keyId>`, which names no machine. So the sealed label carries `from`, this machine's device id; the listener
+ * admits it by the key the account lists for that id and the one it pinned.
+ *
+ * Who reads the message is the account's device list: the target's slot is the listener's own, and every other listed device
+ * that has a key (a phone's bubble opens) gets one. Each device on the list is pinned on the way (`trust-pins.ts`), the target
+ * included, so no `hwip trust` comes first; a key that changed replaces its pin with one warning.
+ *
+ * Nothing here logs or returns a decrypt or encrypt error's message.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sealedCommand = exports.commandRefusalMessage = exports.COMMAND_REFUSAL_TEXT = void 0;
+const crypto_js_1 = require("./crypto.js");
+const command_seq_js_1 = require("./command-seq.js");
+const trust_pins_js_1 = require("./trust-pins.js");
+const self_register_js_1 = require("./self-register.js");
+exports.COMMAND_REFUSAL_TEXT = {
+    'keystore': 'this machine\'s encryption keys did not load; the message was not sent',
+    'devices': 'the device list could not be fetched; the message was not sent',
+    'self-unlisted': (0, self_register_js_1.unregisteredText)('message'),
+    'target-unlisted': 'the target computer is not in the account\'s device list with a key (run `hwip listener` on it once); the message was not sent',
+    'number-locked': 'another hwip process holds ~/.hwip/command-seq.lock; try again in a moment (the message was not sent)',
+    'number-unusable': 'the command counter ~/.hwip/command-seq cannot be read or written; the message was not sent',
+    'encrypt': 'sealing the message failed; the message was not sent',
+};
+const commandRefusalMessage = (cause, why) => `sealed send: ${cause === 'self-unlisted' ? (0, self_register_js_1.unregisteredText)('message', why) : exports.COMMAND_REFUSAL_TEXT[cause]}`;
+exports.commandRefusalMessage = commandRefusalMessage;
+/**
+ * Seal `message` for `session` on `targetDeviceId`.
+ * The caller sends `sealed` with the returned fields (body, key, slots) and tells the user of `refused` without sending.
+ */
+const sealedCommand = async (command, deps) => {
+    try {
+        await deps.loadKeys();
+    }
+    catch {
+        return { kind: 'refused', cause: 'keystore' };
+    }
+    const self = deps.self();
+    if (!self)
+        return { kind: 'refused', cause: 'keystore' };
+    let devices;
+    try {
+        devices = await deps.listDevices();
+        if (!Array.isArray(devices))
+            throw new Error('not a list');
+    }
+    catch {
+        return { kind: 'refused', cause: 'devices' };
+    }
+    // The listener admits this machine by the key the list holds for it: one missing or under another key is put there first.
+    const listing = await (0, self_register_js_1.ensureSelfListed)(devices, self, deps.register);
+    if (!listing.ok)
+        return { kind: 'refused', cause: 'self-unlisted', why: listing.why };
+    devices = listing.devices;
+    (0, trust_pins_js_1.observeDevices)(deps.trustPath, devices, { selfId: self.deviceId, warn: deps.warn ?? (() => undefined) });
+    // The target's slot is the listener's own; this computer's key is its own. Everything else the list holds with a key reads too.
+    const targetKey = command.targetDeviceId === self.deviceId ? self.publicKey : devices.find((d) => d.deviceId === command.targetDeviceId)?.publicKey;
+    if (!targetKey || !(0, crypto_js_1.samePublicKey)(targetKey, targetKey))
+        return { kind: 'refused', cause: 'target-unlisted' };
+    const readers = (0, crypto_js_1.selectRecipients)(devices).filter((d) => d.deviceId !== self.deviceId && d.deviceId !== command.targetDeviceId);
+    const recipients = [{ deviceId: command.targetDeviceId, publicKey: targetKey }, ...readers];
+    const n = await (deps.nextNumber ?? (() => (0, command_seq_js_1.nextCommandNumber)()))();
+    if (typeof n !== 'number')
+        return { kind: 'refused', cause: n.refused === 'lock' ? 'number-locked' : 'number-unusable' };
+    try {
+        const sealed = await (deps.seal ?? crypto_js_1.encryptPushBodyForDevices)({ body: command.message, cmd: { n, session: command.session, device: command.targetDeviceId, from: self.deviceId } }, recipients);
+        // A recipient whose key would not import is skipped by the sealer: the send must not go without the target's slot.
+        if (!sealed.deviceKeyMap[command.targetDeviceId])
+            return { kind: 'refused', cause: 'encrypt' };
+        return {
+            kind: 'sealed',
+            fields: { body: sealed.body, senderPublicKey: sealed.senderPublicKey, deviceKeyMap: sealed.deviceKeyMap },
+        };
+    }
+    catch {
+        return { kind: 'refused', cause: 'encrypt' };
+    }
+};
+exports.sealedCommand = sealedCommand;

package/dist/command-seq.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The number a sealed command carries (`cmd.n`): the listener takes only a number greater than the
+ * last it saw from that sender, so every process on this machine that sends as this machine — the
+ * CLI and any number of MCP servers — has to draw from one counter. It is a file with a single
+ * line, `~/.hwip/command-seq`, read and rewritten under an exclusive lock file beside it.
+ *
+ * `n = max(last + 1, now)`: the clock keeps numbers moving forward when the file is lost, which
+ * would otherwise start over at 1 and have every listener drop the new commands as replays. This is
+ * the formula the phone uses for its own counter (`PeerPins.nextCommand`).
+ *
+ * The MCP server carries a copy of this file; the file's name, its one-line format and the lock's
+ * name are the contract between them.
+ */
+export type CommandSeqRefusal = 
+/** The lock could not be taken: another sender holds it. */
+'lock'
+/** The counter could not be read, or written, or no longer fits a number. */
+ | 'io';
+export interface CommandSeqDeps {
+    /** Where the counter lives. Default `~/.hwip`. */
+    dir?: string;
+    /** The clock, in ms since the epoch. */
+    now?: () => number;
+    /** Wait between tries for the lock. */
+    sleep?: (ms: number) => Promise<void>;
+}
+export declare const nextCommandNumber: (deps?: CommandSeqDeps) => Promise<number | {
+    refused: CommandSeqRefusal;
+}>;
+//# sourceMappingURL=command-seq.d.ts.map