@hwip/cli 0.0.1 → 0.1.0

package/dist/args.d.ts

@@ -0,0 +1,74 @@
+/**
+ * What each flag the CLI knows does with the word after it. A `value` flag takes
+ * that word whatever it looks like: the value can be text nobody typed (a command
+ * to approve, the model's last message), and one that starts with `--base-url=…`
+ * must not be read as the CLI's own flag. A `boolean` takes a following word only
+ * as the old parser did (a word that does not look like a flag); `optional` is a
+ * flag whose value may be left out (`trust --reset [device]`). A flag missing here
+ * is read the old way, and the test over COMMAND_FLAGS keeps a new one from
+ * missing.
+ */
+export declare const FLAG_KINDS: Readonly<Record<string, 'value' | 'boolean' | 'optional'>>;
+/** A yes/no flag was given a value that is neither (`--dry-run=maybe`). */
+export declare class FlagValueError extends Error {
+    readonly flag: string;
+    readonly value: string;
+    constructor(flag: string, value: string);
+}
+/**
+ * Is the yes/no flag `name` on? The one reading every consumer of such a flag shares: not given is
+ * off; given bare (`--dry-run`), `=true`, `=1`, `=yes` is on; `=false`, `=0`, `=no` is off; any
+ * other value stops with `FlagValueError`, because a flag read as "not given" is how
+ * `--dry-run=true` removed what it was asked to preview and `--no-turn-history=1` left the
+ * upload on. The boolean parser also takes the word after a flag as its value (`--dry-run yes`),
+ * and that word goes through the same reading. Words are matched without case.
+ * `lenient` reads a value that is neither as off instead of stopping, for the few places
+ * that must answer whatever the flags hold (the usage gate, an error report).
+ */
+export declare const flagOn: (args: Record<string, string | boolean>, name: string, lenient?: boolean) => boolean;
+export declare const parseArgs: (argv: string[]) => Record<string, string | boolean>;
+/**
+ * The CLI's flags, and for `send` and `agent send` the words after it. They take everything
+ * after it as the target and the message, verbatim: its flags come from the
+ * part before it only, so a `--base-url` word in a message never redirects the
+ * API key and a `--version` never swallows the send. The one exception is a
+ * help flag where the target goes. The `send` is the positional word the flag
+ * parser itself reads as the command (`send`) or as the one right after `agent`
+ * — never a word that merely looks like it: a flag value can be spelled
+ * `send`, and a message can hold `agent send`.
+ */
+export declare const parseCliArgv: (argv: string[]) => {
+    args: Record<string, string | boolean>;
+    sendArgv: string[];
+};
+/**
+ * Print usage instead of running anything. A help flag used to run the
+ * command itself, so `notify --help` sent a push and `uninstall --help`
+ * uninstalled. An agent subcommand (`hwip cc`) passes the flags after it to
+ * the agent untouched, so `hwip cc --help` is the agent's help — but a help
+ * flag before it is hwip's own.
+ */
+export declare const asksForUsage: (argv: string[], args: Record<string, string | boolean>, isAgentCommand: boolean) => boolean;
+/** Flags every command accepts: `createHook` and the usage gate read them. */
+export declare const GLOBAL_FLAGS: string[];
+/**
+ * The flags each command reads, besides the global ones. Commands missing here
+ * (agent subcommands, `sh`, `mcp`) are not checked: an agent subcommand hands
+ * the words after it to the agent, and `send`'s message is never parsed.
+ */
+export declare const COMMAND_FLAGS: Readonly<Record<string, readonly string[]>>;
+/**
+ * Flags the command would ignore, in the order typed. A typo (`--titel`) used
+ * to vanish silently, and the push went out with the default title.
+ */
+export declare const unknownFlags: (args: Record<string, string | boolean>) => string[];
+/**
+ * The first yes/no flag of a command that holds a value that is neither yes nor no, as the
+ * words to print, or null. Checked before the command runs: its handlers read the flags with
+ * `flagOn`, which stops on the same values, and by then work may be under way. A command that
+ * hands its words to an agent (or is not in `COMMAND_FLAGS`) is not checked, and neither is
+ * `trust --yes`, whose value is the device it names. `--allow-host` is checked here too (C132): a list that is
+ * no list of host names stops `login` and `install` before an agent picker or a browser, not after.
+ */
+export declare const badFlagValue: (args: Record<string, string | boolean>) => string | null;
+//# sourceMappingURL=args.d.ts.map

package/dist/args.js

@@ -0,0 +1,254 @@
+"use strict";
+// ── Arg Parser ──────────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.badFlagValue = exports.unknownFlags = exports.COMMAND_FLAGS = exports.GLOBAL_FLAGS = exports.asksForUsage = exports.parseCliArgv = exports.parseArgs = exports.flagOn = exports.FlagValueError = exports.FLAG_KINDS = void 0;
+const login_address_js_1 = require("./login-address.js");
+/**
+ * A word that starts a flag: `--name` or `--name=value`. A dash run like
+ * `--- done` is a value, so `--title "--- done"` keeps its title.
+ */
+const isFlagWord = (word) => /^--[^-=]/.test(word);
+/**
+ * What each flag the CLI knows does with the word after it. A `value` flag takes
+ * that word whatever it looks like: the value can be text nobody typed (a command
+ * to approve, the model's last message), and one that starts with `--base-url=…`
+ * must not be read as the CLI's own flag. A `boolean` takes a following word only
+ * as the old parser did (a word that does not look like a flag); `optional` is a
+ * flag whose value may be left out (`trust --reset [device]`). A flag missing here
+ * is read the old way, and the test over COMMAND_FLAGS keeps a new one from
+ * missing.
+ */
+exports.FLAG_KINDS = {
+    key: 'value', 'api-key': 'value', 'base-url': 'value', 'ws-url': 'value', 'web-url': 'value',
+    'allow-host': 'value',
+    title: 'value', body: 'value', url: 'value', type: 'value', priority: 'value', device: 'value', session: 'value',
+    marker: 'value', tools: 'value', nonreadonly: 'value', 'pushmode-default': 'value', actions: 'value',
+    timeout: 'value', hook: 'value', only: 'value', limit: 'value', channel: 'value', turns: 'value',
+    at: 'value', days: 'value', every: 'value', prompt: 'value', label: 'value', wt: 'value', 'max-runtime': 'value',
+    json: 'boolean', version: 'boolean', help: 'boolean', relogin: 'boolean', service: 'boolean', 'no-service': 'boolean',
+    'dry-run': 'boolean', purge: 'boolean', yes: 'boolean', ping: 'boolean', auto: 'boolean', clear: 'boolean',
+    all: 'boolean', ended: 'boolean', stop: 'boolean', restart: 'boolean', 'no-keep-awake': 'boolean',
+    'no-turn-history': 'boolean', 'install-service': 'boolean', 'uninstall-service': 'boolean',
+    'service-status': 'boolean', 'accepts-exit': 'boolean', global: 'boolean',
+    reset: 'optional',
+};
+/** A yes/no flag was given a value that is neither (`--dry-run=maybe`). */
+class FlagValueError extends Error {
+    flag;
+    value;
+    constructor(flag, value) {
+        super(`--${flag} takes true or false (or nothing, which is true), not "${value}"`);
+        this.flag = flag;
+        this.value = value;
+        this.name = 'FlagValueError';
+    }
+}
+exports.FlagValueError = FlagValueError;
+const ON_WORDS = new Set(['true', '1', 'yes']);
+const OFF_WORDS = new Set(['false', '0', 'no']);
+/**
+ * Is the yes/no flag `name` on? The one reading every consumer of such a flag shares: not given is
+ * off; given bare (`--dry-run`), `=true`, `=1`, `=yes` is on; `=false`, `=0`, `=no` is off; any
+ * other value stops with `FlagValueError`, because a flag read as "not given" is how
+ * `--dry-run=true` removed what it was asked to preview and `--no-turn-history=1` left the
+ * upload on. The boolean parser also takes the word after a flag as its value (`--dry-run yes`),
+ * and that word goes through the same reading. Words are matched without case.
+ * `lenient` reads a value that is neither as off instead of stopping, for the few places
+ * that must answer whatever the flags hold (the usage gate, an error report).
+ */
+const flagOn = (args, name, lenient = false) => {
+    const value = args[name];
+    if (value === undefined || value === false)
+        return false;
+    if (value === true)
+        return true;
+    const word = value.trim().toLowerCase();
+    if (ON_WORDS.has(word))
+        return true;
+    if (OFF_WORDS.has(word))
+        return false;
+    if (lenient)
+        return false;
+    throw new FlagValueError(name, value);
+};
+exports.flagOn = flagOn;
+/** The yes/no flags, from `FLAG_KINDS`. `trust --yes <device>` reads its own value and is not among those checked. */
+const YES_NO_FLAGS = Object.keys(exports.FLAG_KINDS).filter((key) => exports.FLAG_KINDS[key] === 'boolean');
+/** The flags and positional words of argv, and where in argv each positional word stands. */
+const scanArgs = (argv) => {
+    const result = {};
+    const positional = [];
+    const positionalAt = [];
+    const args = argv.slice(2);
+    for (let i = 0; i < args.length; i++) {
+        // `-h` is `--help` before anything reads the words, so it is never a
+        // positional and never a flag's value.
+        const arg = args[i] === '-h' ? '--help' : args[i];
+        // `--` ends the flags: every word after it is a positional, as typed.
+        if (arg === '--') {
+            for (let j = i + 1; j < args.length; j++) {
+                positional.push(args[j]);
+                positionalAt.push(j + 2);
+            }
+            break;
+        }
+        if (!isFlagWord(arg)) {
+            positional.push(arg);
+            positionalAt.push(i + 2);
+            continue;
+        }
+        const eq = arg.indexOf('=');
+        if (eq > 0) {
+            result[arg.slice(2, eq)] = arg.slice(eq + 1);
+            continue;
+        }
+        const key = arg.slice(2);
+        const next = args[i + 1];
+        // `--help` never takes a value: `notify --help foo` and
+        // `uninstall --dry-run -h` both ask for help instead of running.
+        // A `value` flag takes a flag-looking word too; `-h`, `--help` and `--` stay what they are.
+        const takesAnyWord = Object.hasOwn(exports.FLAG_KINDS, key) && exports.FLAG_KINDS[key] === 'value' && next !== '--help';
+        if (key === 'help' || !next || next === '-h' || next === '--' || (isFlagWord(next) && !takesAnyWord)) {
+            result[key] = true;
+        }
+        else {
+            result[key] = next;
+            i++;
+        }
+    }
+    result._command = positional[0] ?? '';
+    result._arg1 = positional[1] ?? '';
+    result._arg2 = positional[2] ?? '';
+    return { result, positional, positionalAt };
+};
+const parseArgs = (argv) => scanArgs(argv).result;
+exports.parseArgs = parseArgs;
+/**
+ * The CLI's flags, and for `send` and `agent send` the words after it. They take everything
+ * after it as the target and the message, verbatim: its flags come from the
+ * part before it only, so a `--base-url` word in a message never redirects the
+ * API key and a `--version` never swallows the send. The one exception is a
+ * help flag where the target goes. The `send` is the positional word the flag
+ * parser itself reads as the command (`send`) or as the one right after `agent`
+ * — never a word that merely looks like it: a flag value can be spelled
+ * `send`, and a message can hold `agent send`.
+ */
+const parseCliArgv = (argv) => {
+    const { result: whole, positional, positionalAt } = scanArgs(argv);
+    const at = positional[0] === 'send' ? positionalAt[0] : positional[0] === 'agent' && positional[1] === 'send' ? positionalAt[1] : -1;
+    if (at < 0)
+        return { args: whole, sendArgv: [] };
+    const args = (0, exports.parseArgs)(argv.slice(0, at + 1));
+    const sendArgv = argv.slice(at + 1);
+    // Where the target goes, a help flag can't be a target: `send --help` is a
+    // help request, not a message to a device named "--help".
+    if (sendArgv[0] === '-h' || sendArgv[0] === '--help')
+        args.help = true;
+    return { args, sendArgv };
+};
+exports.parseCliArgv = parseCliArgv;
+const isHelpWord = (word) => word === '-h' || word === '--help';
+/**
+ * Print usage instead of running anything. A help flag used to run the
+ * command itself, so `notify --help` sent a push and `uninstall --help`
+ * uninstalled. An agent subcommand (`hwip cc`) passes the flags after it to
+ * the agent untouched, so `hwip cc --help` is the agent's help — but a help
+ * flag before it is hwip's own.
+ */
+const asksForUsage = (argv, args, isAgentCommand) => {
+    const command = args._command;
+    if (!command || command === 'help')
+        return true;
+    if (!(0, exports.flagOn)(args, 'help', true))
+        return false;
+    if (!isAgentCommand)
+        return true;
+    const at = argv.indexOf(String(command), 2);
+    return argv.slice(2, at).some(isHelpWord);
+};
+exports.asksForUsage = asksForUsage;
+/** Flags every command accepts: `createHook` and the usage gate read them. */
+exports.GLOBAL_FLAGS = ['key', 'base-url', 'json', 'version', 'help'];
+/**
+ * The flags each command reads, besides the global ones. Commands missing here
+ * (agent subcommands, `sh`, `mcp`) are not checked: an agent subcommand hands
+ * the words after it to the agent, and `send`'s message is never parsed.
+ */
+exports.COMMAND_FLAGS = {
+    install: ['hook', 'only', 'relogin', 'service', 'no-service', 'timeout', 'web-url', 'allow-host'],
+    login: ['timeout', 'web-url', 'allow-host'],
+    uninstall: ['dry-run', 'purge', 'yes'],
+    verify: ['ping', 'ws-url'],
+    'check-update': [],
+    notify: [
+        'title', 'body', 'url', 'type', 'priority', 'device', 'session',
+        'auto', 'marker', 'pushmode-default', 'tools', 'nonreadonly', 'channel',
+    ],
+    channel: [],
+    ask: ['title', 'body', 'actions', 'timeout', 'hook', 'accepts-exit', 'api-key'],
+    'ask-context': ['global'],
+    'file-view': ['global'],
+    agent: ['json', 'turns'],
+    send: [],
+    list: ['limit', 'type'],
+    dismiss: ['all'],
+    rename: ['clear', 'device', 'session'],
+    forget: ['ended'],
+    worktree: ['dry-run'],
+    test: [],
+    trust: ['reset', 'yes'],
+    schedule: ['at', 'days', 'every', 'prompt', 'label', 'wt', 'max-runtime'],
+    listener: [
+        'ws-url', 'stop', 'restart', 'no-keep-awake', 'no-turn-history',
+        'install-service', 'uninstall-service', 'service-status',
+    ],
+    'remote-hook': [],
+};
+/**
+ * Flags the command would ignore, in the order typed. A typo (`--titel`) used
+ * to vanish silently, and the push went out with the default title.
+ */
+const unknownFlags = (args) => {
+    const command = String(args._command);
+    const table = command === 'setup' ? 'install' : command;
+    // Own keys only: `hwip constructor` must not find Object's.
+    if (!Object.hasOwn(exports.COMMAND_FLAGS, table))
+        return [];
+    const known = exports.COMMAND_FLAGS[table];
+    return Object.keys(args).filter((key) => !key.startsWith('_') && !exports.GLOBAL_FLAGS.includes(key) && !known.includes(key));
+};
+exports.unknownFlags = unknownFlags;
+/**
+ * The first yes/no flag of a command that holds a value that is neither yes nor no, as the
+ * words to print, or null. Checked before the command runs: its handlers read the flags with
+ * `flagOn`, which stops on the same values, and by then work may be under way. A command that
+ * hands its words to an agent (or is not in `COMMAND_FLAGS`) is not checked, and neither is
+ * `trust --yes`, whose value is the device it names. `--allow-host` is checked here too (C132): a list that is
+ * no list of host names stops `login` and `install` before an agent picker or a browser, not after.
+ */
+const badFlagValue = (args) => {
+    const command = String(args._command);
+    const table = command === 'setup' ? 'install' : command;
+    if (!Object.hasOwn(exports.COMMAND_FLAGS, table))
+        return null;
+    const read = [...exports.GLOBAL_FLAGS, ...exports.COMMAND_FLAGS[table]];
+    for (const name of YES_NO_FLAGS) {
+        if (!read.includes(name) || (table === 'trust' && name === 'yes'))
+            continue;
+        try {
+            (0, exports.flagOn)(args, name);
+        }
+        catch (err) {
+            if (err instanceof FlagValueError)
+                return err.message;
+            throw err;
+        }
+    }
+    if (read.includes('allow-host')) {
+        const parsed = (0, login_address_js_1.parseAllowHosts)(args['allow-host']);
+        if ('error' in parsed)
+            return parsed.error;
+    }
+    return null;
+};
+exports.badFlagValue = badFlagValue;

package/dist/ask-context-attach.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The attachment a sealed question carries (F3): the original of its context — the masked diff and screen of
+ * `ask-context.ts` — sealed for the devices the question is sealed for.
+ *
+ * What the server sees of it is the same for every sealed question: one attachment, named `file`, of type
+ * `application/octet-stream`, 64 KiB long. A question with nothing to carry (the switch is off, no change and
+ * no screen, git did not answer) gets the same attachment with nothing in it, so neither whether a question has
+ * context nor how much the session changed shows. The real name, type and length are in the sealed body.
+ */
+import { type AskContext } from './ask-context.js';
+import { type AskContextOffBy } from './ask-context-switch.js';
+import type { AskAttachment } from './ask-seal.js';
+import { encryptFileForDevices, type DeviceRecipient, type SealedAskContext } from './crypto.js';
+/** Every attachment is this long before it is sealed: the longest original, so none needs more. */
+export declare const ASK_ATTACHMENT_BYTES: number;
+/** With less of the question's window left than this, nothing is gathered: git and tmux are asked synchronously and may take most of it. */
+export declare const ASK_CONTEXT_MIN_WINDOW_MS = 20000;
+/** What attaching leaves of the question's window, for the question itself to be sent and answered. */
+export declare const ASK_ATTACH_RESERVE_MS = 10000;
+/**
+ * The original as JSON (`{ diff, screen }`, UTF-8) followed by zero bytes up to `ASK_ATTACHMENT_BYTES`; `size`
+ * is where the JSON ends. No context, or an original that does not fit, is all zeros and `size` 0 — and no summary.
+ */
+export declare const padAskOriginal: (ctx: AskContext | null) => {
+    bytes: Buffer;
+    size: number;
+    context?: SealedAskContext;
+};
+export interface AttachDeps {
+    /** The context to carry, or `null`; a throw counts as `null`. */
+    context: () => Promise<AskContext | null>;
+    encrypt: typeof encryptFileForDevices;
+    /** Stores the sealed bytes and returns their `fileKey`. */
+    upload: (sealed: Buffer) => Promise<string>;
+}
+/** Seals and uploads the attachment for `recipients`. Throws when sealing or the upload fails. */
+export declare const attachAskContext: (recipients: DeviceRecipient[], deps: AttachDeps) => Promise<AskAttachment>;
+/**
+ * `attachAskContext`, given up (it rejects, and the question goes without it) once it would eat into the last
+ * `ASK_ATTACH_RESERVE_MS` of a window of `windowMs`: storing the attachment must never hold the question back.
+ * The race cannot cut the synchronous git and tmux reads short; `ASK_CONTEXT_MIN_WINDOW_MS` bounds those.
+ */
+export declare const attachWithinWindow: (recipients: DeviceRecipient[], deps: AttachDeps, windowMs: number) => Promise<AskAttachment>;
+export interface CollectDeps {
+    offBy: (projectDir: string, env: NodeJS.ProcessEnv) => AskContextOffBy | null;
+    /** The screen of a tmux pane, by pane id. */
+    capture: (pane: string) => Promise<string | null>;
+    gather: (cwd: string, screen: string | null) => AskContext | null;
+}
+/**
+ * The context of the session asking from `cwd`: its changes, and the screen of the pane this process runs in
+ * (`TMUX_PANE`; none outside tmux). `off` says why the switch kept it from being read. `windowMs` is what is
+ * left of the question's window.
+ */
+export declare const collectAskContext: (cwd: string, env: NodeJS.ProcessEnv, deps?: CollectDeps, windowMs?: number) => Promise<{
+    context: AskContext | null;
+    off?: AskContextOffBy;
+}>;
+/** Stores sealed attachment bytes with the account and returns their `fileKey`. Throws on any failure. */
+export declare const uploadAskAttachment: (sealed: Buffer, account: {
+    apiKey: string;
+    baseUrl: string;
+}, fetchFn?: typeof fetch) => Promise<string>;
+/**
+ * `AskSealDeps.attach` for real use: this directory's context, sealed with this machine's keys, stored with the
+ * account, within what is left before `deadline`. What goes wrong is said on stderr (stdout is the answer's): a
+ * context that could not be gathered goes as the empty attachment, one that could not be stored not at all.
+ */
+export declare const liveAttach: (account: {
+    apiKey: string;
+    baseUrl: string;
+}, deadline: number, warn: (line: string) => void) => (recipients: DeviceRecipient[]) => Promise<AskAttachment>;
+//# sourceMappingURL=ask-context-attach.d.ts.map

package/dist/ask-context-attach.js

@@ -0,0 +1,151 @@
+"use strict";
+/**
+ * The attachment a sealed question carries (F3): the original of its context — the masked diff and screen of
+ * `ask-context.ts` — sealed for the devices the question is sealed for.
+ *
+ * What the server sees of it is the same for every sealed question: one attachment, named `file`, of type
+ * `application/octet-stream`, 64 KiB long. A question with nothing to carry (the switch is off, no change and
+ * no screen, git did not answer) gets the same attachment with nothing in it, so neither whether a question has
+ * context nor how much the session changed shows. The real name, type and length are in the sealed body.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.liveAttach = exports.uploadAskAttachment = exports.collectAskContext = exports.attachWithinWindow = exports.attachAskContext = exports.padAskOriginal = exports.ASK_ATTACH_RESERVE_MS = exports.ASK_CONTEXT_MIN_WINDOW_MS = exports.ASK_ATTACHMENT_BYTES = void 0;
+const api_js_1 = require("./api.js");
+const ask_context_js_1 = require("./ask-context.js");
+const ask_context_screen_js_1 = require("./ask-context-screen.js");
+const ask_context_switch_js_1 = require("./ask-context-switch.js");
+const crypto_js_1 = require("./crypto.js");
+/** Every attachment is this long before it is sealed: the longest original, so none needs more. */
+exports.ASK_ATTACHMENT_BYTES = ask_context_js_1.ASK_CONTEXT_MAX_BYTES;
+/** What the server is told the attachment is. */
+const WIRE_NAME = 'file';
+const WIRE_TYPE = 'application/octet-stream';
+/** What the sealed body says it is; a reader finds the original by this type. */
+const SEALED_NAME = 'ask-context.json';
+const SEALED_TYPE = 'application/vnd.hwip.ask-context+json';
+/** With less of the question's window left than this, nothing is gathered: git and tmux are asked synchronously and may take most of it. */
+exports.ASK_CONTEXT_MIN_WINDOW_MS = 20_000;
+/** What attaching leaves of the question's window, for the question itself to be sent and answered. */
+exports.ASK_ATTACH_RESERVE_MS = 10_000;
+/** A window this short is a choice (a quick gate), not a failure: it is not warned about. */
+const NO_ROOM = 'too little of the window left to attach the context';
+const UPLOAD_TIMEOUT_MS = 10_000;
+/**
+ * The original as JSON (`{ diff, screen }`, UTF-8) followed by zero bytes up to `ASK_ATTACHMENT_BYTES`; `size`
+ * is where the JSON ends. No context, or an original that does not fit, is all zeros and `size` 0 — and no summary.
+ */
+const padAskOriginal = (ctx) => {
+    const bytes = Buffer.alloc(exports.ASK_ATTACHMENT_BYTES);
+    if (!ctx)
+        return { bytes, size: 0 };
+    const text = Buffer.from(JSON.stringify(ctx.original), 'utf-8');
+    if (text.length > exports.ASK_ATTACHMENT_BYTES)
+        return { bytes, size: 0 };
+    text.copy(bytes);
+    return { bytes, size: text.length, context: ctx.summary };
+};
+exports.padAskOriginal = padAskOriginal;
+/** Seals and uploads the attachment for `recipients`. Throws when sealing or the upload fails. */
+const attachAskContext = async (recipients, deps) => {
+    // No context and a context that failed look the same to the server on purpose; `liveAttach` says which on stderr.
+    const padded = (0, exports.padAskOriginal)(await deps.context().catch(() => null));
+    const sealed = await deps.encrypt(padded.bytes, recipients);
+    const fileKey = await deps.upload(sealed.ciphertext);
+    return {
+        ...(padded.context ? { context: padded.context } : {}),
+        meta: { iv: sealed.iv, name: SEALED_NAME, type: SEALED_TYPE, size: padded.size },
+        file: { fileKey, fileName: WIRE_NAME, fileType: WIRE_TYPE, fileSize: exports.ASK_ATTACHMENT_BYTES, iv: sealed.iv, deviceKeyMap: sealed.deviceKeyMap },
+    };
+};
+exports.attachAskContext = attachAskContext;
+/**
+ * `attachAskContext`, given up (it rejects, and the question goes without it) once it would eat into the last
+ * `ASK_ATTACH_RESERVE_MS` of a window of `windowMs`: storing the attachment must never hold the question back.
+ * The race cannot cut the synchronous git and tmux reads short; `ASK_CONTEXT_MIN_WINDOW_MS` bounds those.
+ */
+const attachWithinWindow = (recipients, deps, windowMs) => {
+    const room = windowMs - exports.ASK_ATTACH_RESERVE_MS;
+    if (room <= 0)
+        return Promise.reject(new Error(NO_ROOM));
+    let timer;
+    const late = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`attaching the context took over ${room} ms`)), room);
+    });
+    return Promise.race([(0, exports.attachAskContext)(recipients, deps), late]).finally(() => clearTimeout(timer));
+};
+exports.attachWithinWindow = attachWithinWindow;
+const LIVE_COLLECT = {
+    offBy: (dir, env) => (0, ask_context_switch_js_1.askContextOffBy)((0, ask_context_switch_js_1.askContextProjectDir)(dir), env),
+    // The id is the target as it is: a session name would be matched by prefix and could name another session's pane.
+    capture: async (pane) => (0, ask_context_screen_js_1.captureAskScreen)(pane, { ...(await (0, ask_context_screen_js_1.liveScreenDeps)()), targetOf: (id) => id }),
+    gather: ask_context_js_1.gatherAskContext,
+};
+/** A tmux pane id, as tmux sets it in `TMUX_PANE` for what runs in the pane. */
+const PANE_ID = /^%\d+$/;
+/**
+ * The context of the session asking from `cwd`: its changes, and the screen of the pane this process runs in
+ * (`TMUX_PANE`; none outside tmux). `off` says why the switch kept it from being read. `windowMs` is what is
+ * left of the question's window.
+ */
+const collectAskContext = async (cwd, env, deps = LIVE_COLLECT, windowMs = Infinity) => {
+    const off = deps.offBy(cwd, env);
+    if (off !== null)
+        return { context: null, off };
+    if (windowMs < exports.ASK_CONTEXT_MIN_WINDOW_MS)
+        return { context: null };
+    const pane = env.TMUX_PANE;
+    const screen = pane !== undefined && PANE_ID.test(pane) ? await deps.capture(pane) : null;
+    return { context: deps.gather(cwd, screen) };
+};
+exports.collectAskContext = collectAskContext;
+/** Stores sealed attachment bytes with the account and returns their `fileKey`. Throws on any failure. */
+const uploadAskAttachment = async (sealed, account, fetchFn = fetch) => {
+    const res = await (0, api_js_1.apiFetch)(fetchFn, (0, api_js_1.apiUrl)(account.baseUrl, '/files/upload-request'), account.apiKey, UPLOAD_TIMEOUT_MS, {
+        method: 'POST',
+        body: JSON.stringify({ fileName: WIRE_NAME, fileType: WIRE_TYPE, fileSize: sealed.length }),
+    });
+    if (!res.ok)
+        throw new Error(`upload-request ${res.status}`);
+    const json = (await res.json());
+    const { uploadUrl, fileKey } = json.data ?? {};
+    if (typeof uploadUrl !== 'string' || typeof fileKey !== 'string')
+        throw new Error('upload-request: unexpected response');
+    // The address is signed for this content type and authenticates itself: no API key goes to the store.
+    const put = await fetchFn(uploadUrl, {
+        method: 'PUT',
+        headers: { 'Content-Type': WIRE_TYPE },
+        body: new Uint8Array(sealed),
+        signal: AbortSignal.timeout(UPLOAD_TIMEOUT_MS),
+        redirect: 'error',
+    });
+    if (!put.ok)
+        throw new Error(`upload ${put.status}`);
+    return fileKey;
+};
+exports.uploadAskAttachment = uploadAskAttachment;
+/**
+ * `AskSealDeps.attach` for real use: this directory's context, sealed with this machine's keys, stored with the
+ * account, within what is left before `deadline`. What goes wrong is said on stderr (stdout is the answer's): a
+ * context that could not be gathered goes as the empty attachment, one that could not be stored not at all.
+ */
+const liveAttach = (account, deadline, warn) => (recipients) => {
+    const windowMs = deadline - Date.now();
+    return (0, exports.attachWithinWindow)(recipients, {
+        context: async () => {
+            try {
+                return (await (0, exports.collectAskContext)(process.cwd(), process.env, LIVE_COLLECT, windowMs)).context;
+            }
+            catch (err) {
+                warn(`the context could not be gathered (${err.message}); the question carries none`);
+                return null;
+            }
+        },
+        encrypt: crypto_js_1.encryptFileForDevices,
+        upload: (sealed) => (0, exports.uploadAskAttachment)(sealed, account),
+    }, windowMs).catch((err) => {
+        if (err.message !== NO_ROOM)
+            warn(`the context was not attached (${err.message}); the question goes without it`);
+        throw err;
+    });
+};
+exports.liveAttach = liveAttach;

package/dist/ask-context-screen.d.ts

@@ -0,0 +1,21 @@
+export interface ScreenDeps {
+    /** The tmux target for a session name; `null` when the name resolves to no pane. */
+    targetOf: (session: string) => string | null;
+    /** Runs tmux with these arguments (the socket flag is the caller's). */
+    tmux: (args: string[]) => {
+        status: number | null;
+        stdout: string;
+    };
+}
+/**
+ * The last `ASK_CONTEXT_SCREEN_WINDOW_LINES` lines of the session's pane (history included), or `null`. `-J` joins
+ * a line the pane wrapped: masking works line by line, and a token wider than the pane would otherwise be cut into
+ * rows, each too short to be read as a token, with its tail left in the clear.
+ */
+export declare const captureAskScreen: (session: string, deps: ScreenDeps) => string | null;
+/**
+ * The real tmux. The listener's log goes quiet first: its tmux socket search prints to stdout, and a
+ * `hwip ask` answer owns stdout (the same step `liveLocalAgentDeps` takes).
+ */
+export declare const liveScreenDeps: () => Promise<ScreenDeps>;
+//# sourceMappingURL=ask-context-screen.d.ts.map

package/dist/ask-context-screen.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.liveScreenDeps = exports.captureAskScreen = void 0;
+const node_child_process_1 = require("node:child_process");
+const ask_context_js_1 = require("./ask-context.js");
+/**
+ * The terminal screen of a session as plain text, for `gatherAskContext`'s `screen` argument. It is the
+ * listener's own `capture-pane` read (tmux `capture-pane -p`, no escapes) as a small function of its own, so
+ * `listener.ts` stays as it is. Nothing is masked here — `composeAskContext` does that, once, over what this
+ * returns. Nothing is sent, and a pane that cannot be read is `null`, never an error.
+ */
+/** The capture that does not answer within this is given up on; a hung server must not hold up a question. It does not cover the socket search `tmuxArgs` does first (the listener's own, with its own probes). */
+const CAPTURE_TIMEOUT_MS = 3_000;
+/** Longest capture that is read; a pane wider or taller than this is not a screen worth sending whole. */
+const CAPTURE_MAX_BYTES = 1024 * 1024;
+/**
+ * The last `ASK_CONTEXT_SCREEN_WINDOW_LINES` lines of the session's pane (history included), or `null`. `-J` joins
+ * a line the pane wrapped: masking works line by line, and a token wider than the pane would otherwise be cut into
+ * rows, each too short to be read as a token, with its tail left in the clear.
+ */
+const captureAskScreen = (session, deps) => {
+    const target = deps.targetOf(session);
+    if (target === null)
+        return null;
+    const run = deps.tmux(['capture-pane', '-p', '-J', '-t', target, '-S', `-${ask_context_js_1.ASK_CONTEXT_SCREEN_WINDOW_LINES}`]);
+    return run.status === 0 ? run.stdout : null;
+};
+exports.captureAskScreen = captureAskScreen;
+/**
+ * The real tmux. The listener's log goes quiet first: its tmux socket search prints to stdout, and a
+ * `hwip ask` answer owns stdout (the same step `liveLocalAgentDeps` takes).
+ */
+const liveScreenDeps = async () => {
+    const { silenceListenerLog, tmuxArgs, tmuxTargetFor } = await import('./listener.js');
+    silenceListenerLog();
+    return {
+        targetOf: tmuxTargetFor,
+        tmux: (args) => {
+            const r = (0, node_child_process_1.spawnSync)('tmux', tmuxArgs(args), {
+                encoding: 'utf-8',
+                stdio: ['ignore', 'pipe', 'ignore'],
+                timeout: CAPTURE_TIMEOUT_MS,
+                maxBuffer: CAPTURE_MAX_BYTES,
+            });
+            return { status: r.error ? null : r.status, stdout: r.stdout ?? '' };
+        },
+    };
+};
+exports.liveScreenDeps = liveScreenDeps;

package/dist/ask-context-switch.d.ts

@@ -0,0 +1,31 @@
+import { type SwitchOffBy } from './project-switch.js';
+/**
+ * The switch for the context a sealed question may carry (`ask-context.ts`): one state file per project and one
+ * for every project. Both are local files in the state directory (`gate.ts`'s, beside `muted-<hash>`) — the
+ * switch never reaches the server or the wire. No file means on: the context is automatic for an account with
+ * E2E on (the user's decision), and this is how a project or the whole machine opts out.
+ */
+export type AskContextOffBy = SwitchOffBy;
+/** The project a question belongs to: the repository root, else the directory itself, so a question asked from a subfolder reads the same switch. */
+export declare const askContextProjectDir: (cwd: string, repoRoot?: (cwd: string) => string | null) => string;
+/** Why the context is off for this project, or `null` when it is on. `HWIP_ASK_CONTEXT=0` turns it off for one run. */
+export declare const askContextOffBy: (dir: string, env?: NodeJS.ProcessEnv) => SwitchOffBy | null;
+export declare const askContextEnabled: (dir: string, env?: NodeJS.ProcessEnv) => boolean;
+/** Turn the context on or off for this project, or for every project. Throws when the state file cannot be written or removed. */
+export declare const setAskContext: (dir: string, on: boolean, scope: import("./project-switch.js").SwitchScope) => void;
+export declare const describeAskContext: (offBy: AskContextOffBy | null) => string;
+export interface AskContextCommandDeps {
+    cwd: () => string;
+    out: (line: string) => void;
+    err: (line: string) => void;
+    env: NodeJS.ProcessEnv;
+    repoRoot: (cwd: string) => string | null;
+}
+export declare const runAskContext: (sub: string | undefined, global: boolean, deps: AskContextCommandDeps) => number;
+/**
+ * `show` prints, as one JSON line, what a question asked from this directory would carry: `{ context, off? }`
+ * (`collectAskContext`). It reads the switch itself, so a caller that only seals (mcp-server's `hwip_ask`) needs
+ * no switch logic of its own. Nothing is sent.
+ */
+export declare const handleAskContext: (args: Record<string, string | boolean>) => Promise<number>;
+//# sourceMappingURL=ask-context-switch.d.ts.map