@zeph-to/cli 2.2.0 → 2.3.1

package/README.md

@@ -4,6 +4,7 @@
 [![downloads](https://img.shields.io/npm/dm/@zeph-to/cli.svg)](https://www.npmjs.com/package/@zeph-to/cli)
 [![node](https://img.shields.io/node/v/@zeph-to/cli.svg)](https://nodejs.org)
 [![license](https://img.shields.io/npm/l/@zeph-to/cli.svg)](./LICENSE)
+[![docs](https://img.shields.io/badge/docs-docs.zeph.to-1f6feb)](https://docs.zeph.to)
 
 **Your agent works, hits a decision, and asks your phone. You tap a button (or type a reply), and the answer lands back in the live session — so the agent keeps going.**
 
@@ -19,6 +20,8 @@
 
 Part of the Zeph toolchain: [`@zeph-to/mcp-server`](https://github.com/zeph-to/mcp-server) (the MCP tools your agent calls, e.g. `zeph_ask`) · [`zeph-to/plugin`](https://github.com/zeph-to/plugin) (Claude Code plugin bundling hooks + MCP + rules) · the [Zeph app](https://zeph.to) on your phone.
 
+> **New here?** [docs.zeph.to](https://docs.zeph.to) walks the whole setup — one command on this machine, the app on your phone, and a restart. The reference below assumes that is already done.
+
 ## Quick Start
 
 Install the CLI globally, then run setup:
@@ -354,10 +357,26 @@ into a shell-adjacent pane). The defense is layered:
    prompt is still in front of every destructive tool call. The phone
    can *talk* but can't approve `rm -rf` for you.
 
-The transport (WS) is currently authenticated by API key + `push:read`
-scope and is **not** end-to-end encrypted in v1 — your Zeph backend
-sees the message plaintext. If you self-host or trust your backend,
-that's fine. If you don't, hold off until per-device E2E ships.
+The transport (WS) is authenticated by API key + `push:read` scope.
+Whether your backend also reads what crosses it depends on encryption
+being on:
+
+- **Encryption off — the default.** The phone has no device keypair to
+  hand the listener, so pane frames and the messages you type both
+  cross the relay in plaintext.
+- **Encryption on.** The phone sends its device public key when it
+  subscribes, every pane frame comes back inside an ECDH P-256 +
+  AES-256-GCM envelope, and your keystrokes are sealed for this
+  listener with their `seq`/`epoch` stamps embedded in the ciphertext,
+  so the relay can't replay one. A frame that fails to encrypt is
+  dropped, never downgraded.
+
+Two gaps either way. A message sent while no live stream is open falls
+back to REST, which is plaintext to the server — that includes every
+`@<session>` command from the agent chat. And the sealed channel buys
+confidentiality against a *passive* relay only: each side learns the
+other's key from the wire, so a backend that mints its own keypair can
+pose as the listener.
 
 ## CLI Usage
 
@@ -619,15 +638,20 @@ session.
 
 ## Encryption
 
-Push bodies and long-body attachments are encrypted with AES-256-GCM.
-This host holds its own ECDH P-256 keypair in `~/.zeph/device-keys.json`
-— generated on first use, and the private half never leaves the machine.
-Each push is encrypted once, and its AES key is wrapped separately for
-every device on your account using ECDH against that device's public
-key.
-
-Toggle encryption in the Zeph app (Settings → Encryption); when it is
-off, the CLI sends plaintext. No configuration needed.
+End-to-end encryption is **off by default** and turning it on needs
+Zeph Pro. The switch is in the app under Settings → E2E Encryption;
+until you flip it, every push leaves this host in plaintext. If the
+account later loses Pro the server answers `PRO_REQUIRED` and the CLI
+resends the same push in the clear. No configuration either way.
+
+With it on, push bodies and long-body attachments are encrypted with
+AES-256-GCM. This host holds its own ECDH P-256 keypair in
+`~/.zeph/device-keys.json` — generated on first use, and the private
+half never leaves the machine; the backend stores public keys only and
+rejects a private-key upload. Each push is encrypted once, and its AES
+key is wrapped separately for every device on your account using ECDH
+against that device's public key. The title and URL move inside the
+ciphertext with the body.
 
 **Threat model:** against a passive backend — a leaked snapshot, an
 operator reading the table — the stored ciphertext and wrapped keys are
@@ -636,9 +660,13 @@ useless, so push contents stay private. Three limits worth knowing:
 - **No protection from an active malicious operator.** Recipient public
   keys come from `GET /devices` on that same server, unsigned and
   unpinned. A backend that injects a device record carrying its own key
-  gets the message key wrapped for it, and reads everything. Closing
-  this needs out-of-band device verification (ADR-0007 Phase 4, not
-  built).
+  gets the message key wrapped for it, and reads everything. The Zeph
+  app ships the counter-measure — compare device fingerprints, mark a
+  device verified, and strict mode then wraps only for verified
+  devices — but it defaults off, its verified list is per browser
+  profile, and this CLI does not consult it: `selectRecipients` asks
+  only whether a device has a public key, and whether that key is the
+  legacy account-wide one (ADR-0007 Phase 4).
 - **No forward secrecy.** The ECDH secret for a given sender/device pair
   is static, so compromising either private key opens every past push
   wrapped for that pair.

package/dist/ask.d.ts

@@ -0,0 +1,52 @@
+export interface AskAction {
+    id: string;
+    label: string;
+}
+export interface AskOptions {
+    apiKey: string;
+    baseUrl: string;
+    hookId: string;
+    title: string;
+    body?: string;
+    actions?: AskAction[];
+    timeoutSeconds: number;
+}
+/** Injected so the poll loop is testable without a clock or a network. */
+export interface AskDeps {
+    fetchFn: typeof fetch;
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+}
+export type AskOutcome = {
+    readonly answered: true;
+    readonly actionId: string;
+} | {
+    readonly answered: true;
+    readonly value: string;
+} | {
+    readonly answered: false;
+    readonly error?: string;
+};
+/**
+ * `id:Label` pairs, comma separated. The label may contain colons — only the
+ * first one separates, so `go:Deploy: prod` keeps its punctuation. A bare
+ * segment becomes its own label, which is what someone typing `--actions ok`
+ * means.
+ */
+export declare const parseActions: (spec?: string) => AskAction[];
+/**
+ * Ask, then wait. Resolves when the user answers or the deadline passes —
+ * never rejects.
+ */
+export declare const requestApproval: (opts: AskOptions, deps: AskDeps) => Promise<AskOutcome>;
+/** Wall-clock deps for real use. */
+export declare const liveDeps: () => AskDeps;
+/**
+ * `zeph ask --title … [--body …] [--actions id:Label,…] [--timeout 60]`
+ *
+ * Prints one JSON object and nothing else, so a hook can pipe it straight into
+ * `jq`. Exit code 0 means answered, 1 means not — a shell caller that only
+ * wants approve/deny can read `$?` and skip the JSON entirely.
+ */
+export declare const handleAsk: (args: Record<string, string | boolean>) => Promise<number>;
+//# sourceMappingURL=ask.d.ts.map

package/dist/ask.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask.d.ts","sourceRoot":"","sources":["../src/ask.ts"],"names":[],"mappings":"AA+BA,MAAM,WAAW,SAAS;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,SAAS,EAAE,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CAC1B;AAED,0EAA0E;AAC1E,MAAM,WAAW,OAAO;IACpB,OAAO,EAAE,OAAO,KAAK,CAAC;IACtB,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC;AAED,MAAM,MAAM,UAAU,GAChB;IAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACtD;IAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5D;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,KAAG,SAAS,EAcrD,CAAC;AAoCF;;;GAGG;AACH,eAAO,MAAM,eAAe,GAAU,MAAM,UAAU,EAAE,MAAM,OAAO,KAAG,OAAO,CAAC,UAAU,CAmCzF,CAAC;AAEF,oCAAoC;AACpC,eAAO,MAAM,QAAQ,QAAO,OAI1B,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,GAAU,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAG,OAAO,CAAC,MAAM,CAkCtF,CAAC"}

package/dist/ask.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleAsk = exports.liveDeps = exports.requestApproval = exports.parseActions = void 0;
+/**
+ * `zeph ask` — put a question on the user's phone and block until they answer.
+ *
+ * Why this lives in the CLI at all: hooks are shell scripts, and a shell script
+ * cannot call an MCP tool. `zeph_ask` (mcp-server) already does this for the
+ * model; a hook that needs to wait for a person — an approval gate in front of
+ * a dangerous command — has no way to reach it. This is that path.
+ *
+ * It returns ONE shape for every outcome, including failure. A hook standing in
+ * front of `rm -rf` cannot handle an exception, and an approval gate that
+ * throws has stopped being a gate: unreachable server, bad key, and silence all
+ * come back as `answered: false` so the caller makes the same decision it would
+ * have made on a refusal.
+ *
+ * No WebSocket fast path, unlike mcp-server's poll. A hook run is seconds long
+ * and dies with the tool call, so a socket would cost a handshake it cannot
+ * amortise; plain polling is the whole protocol here.
+ */
+const config_js_1 = require("./config.js");
+/** Server-side hook trigger + event read. Kept narrow on purpose — this
+ *  module needs two routes, not an API client. */
+const TRIGGER_PATH = (hookId) => `/hooks/${hookId}/trigger`;
+const EVENT_PATH = (hookId, eventId) => `/hooks/${hookId}/events/${eventId}`;
+/** Poll cadence. Fast enough that a tap feels immediate, slow enough that a
+ *  10-minute wait is not thousands of requests. */
+const POLL_INTERVAL_MS = 1_000;
+/** Per-request bound, well under any sane overall deadline. */
+const REQUEST_TIMEOUT_MS = 10_000;
+/**
+ * `id:Label` pairs, comma separated. The label may contain colons — only the
+ * first one separates, so `go:Deploy: prod` keeps its punctuation. A bare
+ * segment becomes its own label, which is what someone typing `--actions ok`
+ * means.
+ */
+const parseActions = (spec) => {
+    if (!spec)
+        return [];
+    return spec
+        .split(',')
+        .map((seg) => seg.trim())
+        .filter((seg) => seg.length > 0)
+        .map((seg) => {
+        const idx = seg.indexOf(':');
+        if (idx === -1)
+            return { id: seg, label: seg };
+        const id = seg.slice(0, idx).trim();
+        const label = seg.slice(idx + 1).trim();
+        return { id, label: label || id };
+    })
+        .filter((a) => a.id.length > 0);
+};
+exports.parseActions = parseActions;
+const errorMessage = (err) => err instanceof Error ? err.message : String(err);
+const callApi = async (deps, opts, method, path, body) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    try {
+        const headers = { 'X-API-Key': opts.apiKey };
+        if (body)
+            headers['Content-Type'] = 'application/json';
+        const res = await deps.fetchFn(`${opts.baseUrl}${path}`, {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined,
+            signal: controller.signal,
+        });
+        const json = (await res.json());
+        if (!res.ok)
+            throw new Error(json.error?.message ?? `HTTP ${res.status}`);
+        return json;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};
+/**
+ * Ask, then wait. Resolves when the user answers or the deadline passes —
+ * never rejects.
+ */
+const requestApproval = async (opts, deps) => {
+    const deadline = deps.now() + opts.timeoutSeconds * 1000;
+    let eventId;
+    try {
+        const trigger = await callApi(deps, opts, 'POST', TRIGGER_PATH(opts.hookId), {
+            title: opts.title,
+            body: opts.body,
+            actions: opts.actions,
+            timeout: opts.timeoutSeconds,
+            hookType: 'combo',
+        });
+        const id = trigger.data?.eventId;
+        if (!id)
+            return { answered: false, error: 'no eventId in trigger response' };
+        eventId = id;
+    }
+    catch (err) {
+        // The question never reached the phone; there is nothing to wait for.
+        return { answered: false, error: errorMessage(err) };
+    }
+    while (deps.now() < deadline) {
+        try {
+            const event = await callApi(deps, opts, 'GET', EVENT_PATH(opts.hookId, eventId));
+            const response = event.data?.response;
+            if (response?.actionId)
+                return { answered: true, actionId: response.actionId };
+            if (response?.value)
+                return { answered: true, value: response.value };
+        }
+        catch {
+            // One failed poll is not an answer and not a refusal — the user may
+            // still be reaching for their phone. Keep waiting; the deadline is
+            // what ends this loop.
+        }
+        await deps.sleep(POLL_INTERVAL_MS);
+    }
+    return { answered: false };
+};
+exports.requestApproval = requestApproval;
+/** Wall-clock deps for real use. */
+const liveDeps = () => ({
+    fetchFn: fetch,
+    now: () => Date.now(),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+});
+exports.liveDeps = liveDeps;
+/**
+ * `zeph ask --title … [--body …] [--actions id:Label,…] [--timeout 60]`
+ *
+ * Prints one JSON object and nothing else, so a hook can pipe it straight into
+ * `jq`. Exit code 0 means answered, 1 means not — a shell caller that only
+ * wants approve/deny can read `$?` and skip the JSON entirely.
+ */
+const handleAsk = async (args) => {
+    const config = (0, config_js_1.loadConfig)();
+    // `resolvedEnv`, not `process.env`: a hook environment can hand us a literal
+    // unexpanded `${ZEPH_API_KEY}`, which is truthy and would beat the config
+    // file. Auth then fails, this returns `answered: false`, and the approval
+    // hook maps that to DENY — a command blocked for a reason that has nothing
+    // to do with the user. Every other command in cli.ts resolves env this way.
+    const apiKey = args['api-key'] || (0, config_js_1.resolvedEnv)('ZEPH_API_KEY') || config.apiKey;
+    const hookId = args.hook || (0, config_js_1.resolvedEnv)('ZEPH_HOOK_ID') || config.hookId;
+    const title = args.title || '';
+    if (!apiKey || !hookId || !title) {
+        const missing = [!title && '--title', !apiKey && 'an API key', !hookId && 'a hook id']
+            .filter(Boolean).join(', ');
+        process.stdout.write(JSON.stringify({ answered: false, error: `missing ${missing}` }) + '\n');
+        return 1;
+    }
+    const timeoutSeconds = Number(args.timeout ?? 60);
+    const outcome = await (0, exports.requestApproval)({
+        apiKey,
+        baseUrl: (config.baseUrl ?? 'https://api.zeph.to/v1').replace(/\/$/, ''),
+        hookId,
+        title,
+        body: args.body,
+        actions: (0, exports.parseActions)(args.actions),
+        timeoutSeconds: Number.isFinite(timeoutSeconds) && timeoutSeconds > 0 ? timeoutSeconds : 60,
+    }, (0, exports.liveDeps)());
+    process.stdout.write(JSON.stringify(outcome) + '\n');
+    return outcome.answered ? 0 : 1;
+};
+exports.handleAsk = handleAsk;

package/dist/cli.js

@@ -9,6 +9,7 @@ const login_js_1 = require("./login.js");
 const uninstall_js_1 = require("./uninstall.js");
 const verify_js_1 = require("./verify.js");
 const check_update_js_1 = require("./check-update.js");
+const ask_js_1 = require("./ask.js");
 const wrapper_js_1 = require("./wrapper.js");
 const listener_js_1 = require("./listener.js");
 const config_js_1 = require("./config.js");
@@ -68,6 +69,10 @@ Commands:
   verify          Check installation health across detected agents
   check-update    Check whether a newer Zeph version is available
   notify          Send a push notification
+  ask             Ask the phone a question and WAIT for the answer
+                  (--title, --body, --actions id:Label,…, --timeout secs)
+                  Prints one JSON line; exit 0 answered, 1 not. Built for
+                  hooks, which cannot call the MCP zeph_ask tool.
   list            List recent push notifications
   dismiss <id>    Dismiss a push notification (or --all)
   rename <name>   Set this agent session's display name in the app
@@ -462,6 +467,8 @@ const main = async () => {
             return (0, check_update_js_1.handleCheckUpdate)(args);
         case 'notify':
             return handleNotify(args);
+        case 'ask':
+            return (0, ask_js_1.handleAsk)(args);
         case 'list':
             return handleList(args);
         case 'dismiss':

package/dist/gate.d.ts

@@ -44,6 +44,35 @@ export declare const remoteMarkerPath: (hash: string) => string;
  * the bash reader keeps, and both sides must hash identical bytes.
  */
 export declare const remoteDigest: (text: string) => string;
+/**
+ * How long REMOTE stays live without a refresh. Generous on purpose: the state
+ * is refreshed on every phone prompt and every answered `zeph_ask`, so it only
+ * has to outlive a working session, never an idle user. It is the backstop and
+ * not the usual exit — a terminal-typed prompt, a Done-like answer and the
+ * model's `<!-- zeph: exit -->` all delete the file outright. What none of them
+ * covers is a session that simply died: there is no SessionEnd hook, so without
+ * a TTL a crash or Ctrl-C would latch REMOTE forever.
+ */
+export declare const REMOTE_TTL_SEC = 14400;
+/** State path for a project hash: `<stateDir>/remote-active-<cksum(dir)>`. */
+export declare const remoteStatePath: (hash: string) => string;
+/**
+ * True while REMOTE is live for this project. State that is expired or
+ * unparseable is deleted on sight — the same housekeeping a stale entry
+ * marker gets, since state that can never flag again is dead weight.
+ */
+export declare const isRemoteActive: (dir: string, now?: () => number) => boolean;
+/**
+ * Enter REMOTE, or push its expiry back. Best-effort by contract: the prompt
+ * hooks that call this must never fail a prompt over state IO.
+ */
+export declare const touchRemoteActive: (dir: string, now?: () => number) => void;
+/**
+ * Leave REMOTE. Best-effort like its twin: an absent file is success, and the
+ * caller is a hook with its own job to finish. Bash twin: gate.sh
+ * zeph_remote_clear.
+ */
+export declare const clearRemoteActive: (dir: string) => void;
 /** True when the user ran /zeph-mute for this project. */
 export declare const isMuted: (dir: string) => boolean;
 /**

package/dist/gate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":"AAyBA,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAC3D,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEvD,MAAM,WAAW,SAAS;IACxB,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,gBAAgB,EAAE,MAAM,CAAC;IACzB,yDAAyD;IACzD,YAAY,EAAE,OAAO,CAAC;IACtB,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,YAAY,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAAC;CAC7B;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa;;;;CAIhB,CAAC;AAEX,eAAO,MAAM,eAAe,GAAI,KAAK,MAAM,GAAG,SAAS,KAAG,UACS,CAAC;AAEpE,eAAO,MAAM,iBAAiB,GAAI,KAAK,MAAM,GAAG,SAAS,KAAG,YACR,CAAC;AAErD,eAAO,MAAM,UAAU,GAAI,OAAO,SAAS,KAAG,WAW7C,CAAC;AAeF,eAAO,MAAM,QAAQ,QAAO,MACoD,CAAC;AA2BjF,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,IAOlD,CAAC;AAWF,+EAA+E;AAC/E,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,KAAG,MAA4C,CAAC;AAE7F;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,KAAG,MAG1B,CAAC;AAEnB,0DAA0D;AAC1D,eAAO,MAAM,OAAO,GAAI,KAAK,MAAM,KAAG,OAGrC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,YAAsB,CAAC;AAEtD;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AAExD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,YAAY,GACvB,KAAK,MAAM,EACX,WAAU,YAA+B,KACxC,YAUF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY,GAAI,KAAK,MAAM,EAAE,MAAM,MAAM,GAAG,OAAO,GAAG,SAAS,KAAG,YACW,CAAC"}
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":"AAyBA,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAC3D,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEvD,MAAM,WAAW,SAAS;IACxB,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,gBAAgB,EAAE,MAAM,CAAC;IACzB,yDAAyD;IACzD,YAAY,EAAE,OAAO,CAAC;IACtB,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,YAAY,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAAC;CAC7B;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa;;;;CAIhB,CAAC;AAEX,eAAO,MAAM,eAAe,GAAI,KAAK,MAAM,GAAG,SAAS,KAAG,UACS,CAAC;AAEpE,eAAO,MAAM,iBAAiB,GAAI,KAAK,MAAM,GAAG,SAAS,KAAG,YACR,CAAC;AAErD,eAAO,MAAM,UAAU,GAAI,OAAO,SAAS,KAAG,WAW7C,CAAC;AAeF,eAAO,MAAM,QAAQ,QAAO,MACoD,CAAC;AA2BjF,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,IAOlD,CAAC;AAWF,+EAA+E;AAC/E,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,KAAG,MAA4C,CAAC;AAE7F;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,KAAG,MAG1B,CAAC;AAiBnB;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,QAAQ,CAAC;AAEpC,8EAA8E;AAC9E,eAAO,MAAM,eAAe,GAAI,MAAM,MAAM,KAAG,MACJ,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,cAAc,GAAI,KAAK,MAAM,EAAE,MAAK,MAAM,MAAiB,KAAG,OAsB1E,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAAI,KAAK,MAAM,EAAE,MAAK,MAAM,MAAiB,KAAG,IAS7E,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,KAAK,MAAM,KAAG,IAQ/C,CAAC;AAEF,0DAA0D;AAC1D,eAAO,MAAM,OAAO,GAAI,KAAK,MAAM,KAAG,OAGrC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,YAAsB,CAAC;AAEtD;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AAExD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,YAAY,GACvB,KAAK,MAAM,EACX,WAAU,YAA+B,KACxC,YAUF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY,GAAI,KAAK,MAAM,EAAE,MAAM,MAAM,GAAG,OAAO,GAAG,SAAS,KAAG,YACW,CAAC"}

package/dist/gate.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.autoPushMode = exports.readPushMode = exports.PUSHMODE_DEFAULT_FLAG = exports.PUSHMODE_DEFAULT = exports.isMuted = exports.remoteDigest = exports.remoteMarkerPath = exports.projectHash = exports.stateDir = exports.decidePush = exports.normalizePushMode = exports.normalizeMarker = exports.GATE_DEFAULTS = void 0;
+exports.autoPushMode = exports.readPushMode = exports.PUSHMODE_DEFAULT_FLAG = exports.PUSHMODE_DEFAULT = exports.isMuted = exports.clearRemoteActive = exports.touchRemoteActive = exports.isRemoteActive = exports.remoteStatePath = exports.REMOTE_TTL_SEC = exports.remoteDigest = exports.remoteMarkerPath = exports.projectHash = exports.stateDir = exports.decidePush = exports.normalizePushMode = exports.normalizeMarker = exports.GATE_DEFAULTS = void 0;
 /**
  * Push-gate decision — the portable half of the Zeph Stop-hook logic.
  *
@@ -132,6 +132,99 @@ const remoteDigest = (text) => (0, crypto_1.createHash)('sha256')
     .update(text.replace(/^[ \t\r\n\f\v]+|[ \t\r\n\f\v]+$/g, ''))
     .digest('hex');
 exports.remoteDigest = remoteDigest;
+// ── Sticky REMOTE state ──────────────────────────────────────────
+//
+// The marker above is a ONE-SHOT entry signal, consumed the moment a prompt
+// matches it. REMOTE outlives that turn — the user can answer from the phone
+// and then type at the terminal — so the mode itself lives in
+// `remote-active-<hash>`, holding the epoch second it was last confirmed.
+// Keeping it in a file is also what lets it survive context compaction.
+// Bash twin: plugin/hooks/gate.sh zeph_remote_active / zeph_remote_touch.
+//
+// Deliberately not routed through findStateFile. That helper also honors a
+// legacy /tmp copy so files written by older versions keep working; this kind
+// has never had a /tmp writer, so the branch could only ever match something
+// stale — and since the refresh always writes the XDG path, such a file would
+// never expire.
+/**
+ * How long REMOTE stays live without a refresh. Generous on purpose: the state
+ * is refreshed on every phone prompt and every answered `zeph_ask`, so it only
+ * has to outlive a working session, never an idle user. It is the backstop and
+ * not the usual exit — a terminal-typed prompt, a Done-like answer and the
+ * model's `<!-- zeph: exit -->` all delete the file outright. What none of them
+ * covers is a session that simply died: there is no SessionEnd hook, so without
+ * a TTL a crash or Ctrl-C would latch REMOTE forever.
+ */
+exports.REMOTE_TTL_SEC = 14400;
+/** State path for a project hash: `<stateDir>/remote-active-<cksum(dir)>`. */
+const remoteStatePath = (hash) => (0, path_1.join)((0, exports.stateDir)(), `remote-active-${hash}`);
+exports.remoteStatePath = remoteStatePath;
+/**
+ * True while REMOTE is live for this project. State that is expired or
+ * unparseable is deleted on sight — the same housekeeping a stale entry
+ * marker gets, since state that can never flag again is dead weight.
+ */
+const isRemoteActive = (dir, now = Date.now) => {
+    const hash = (0, exports.projectHash)(dir);
+    if (!hash)
+        return false;
+    const file = (0, exports.remoteStatePath)(hash);
+    let raw;
+    try {
+        raw = (0, fs_1.readFileSync)(file, 'utf-8').trim();
+    }
+    catch {
+        return false;
+    }
+    // Digits only, matching the bash twin's `case "$ts" in *[!0-9]*)`. Number()
+    // alone is looser than that test — it reads '1e10' as ten billion, so a file
+    // bash would sweep would live on here as a far-future timestamp.
+    const fresh = /^\d+$/.test(raw) && Math.floor(now() / 1000) - Number(raw) <= exports.REMOTE_TTL_SEC;
+    if (!fresh) {
+        try {
+            (0, fs_1.unlinkSync)(file);
+        }
+        catch {
+            /* best-effort housekeeping */
+        }
+    }
+    return fresh;
+};
+exports.isRemoteActive = isRemoteActive;
+/**
+ * Enter REMOTE, or push its expiry back. Best-effort by contract: the prompt
+ * hooks that call this must never fail a prompt over state IO.
+ */
+const touchRemoteActive = (dir, now = Date.now) => {
+    const hash = (0, exports.projectHash)(dir);
+    if (!hash)
+        return;
+    try {
+        (0, fs_1.mkdirSync)((0, exports.stateDir)(), { recursive: true });
+        (0, fs_1.writeFileSync)((0, exports.remoteStatePath)(hash), `${Math.floor(now() / 1000)}\n`);
+    }
+    catch {
+        /* a hook must never fail on state IO */
+    }
+};
+exports.touchRemoteActive = touchRemoteActive;
+/**
+ * Leave REMOTE. Best-effort like its twin: an absent file is success, and the
+ * caller is a hook with its own job to finish. Bash twin: gate.sh
+ * zeph_remote_clear.
+ */
+const clearRemoteActive = (dir) => {
+    const hash = (0, exports.projectHash)(dir);
+    if (!hash)
+        return;
+    try {
+        (0, fs_1.unlinkSync)((0, exports.remoteStatePath)(hash));
+    }
+    catch {
+        /* already gone, or unwritable — the prompt still goes through */
+    }
+};
+exports.clearRemoteActive = clearRemoteActive;
 /** True when the user ran /zeph-mute for this project. */
 const isMuted = (dir) => {
     const hash = (0, exports.projectHash)(dir);