@zeph-to/cli 1.27.1 → 2.1.0

package/dist/crypto.js

@@ -1,35 +1,35 @@
 "use strict";
 /**
- * Device-shared encryption for Hook SDK — self-contained ECDH P-256 +
+ * Per-device encryption for the Hook SDK — self-contained ECDH P-256 +
  * AES-256-GCM. Mirrors @zeph/crypto API but bundled inline (no external
  * dependency). Uses Web Crypto API via node:crypto webcrypto — Node.js 18+
  * (the `crypto` global only exists unflagged from Node 19, so we import it).
  *
- * Threat model honesty (do not call this "E2E" without a footnote):
+ * How it works (ADR-0007):
  *
- *   The Zeph backend persists the per-user private key in plaintext so it
- *   can be synced down to a fresh device (fetchServerKeys / uploadServerKeys
- *   below). That means the backend can decrypt any push body — this is NOT
- *   end-to-end in the standard sense. What it gives you is:
- *     • Protection against passive network observers
- *     • Protection against a leaked DB snapshot taken without the key store
- *     • Cross-device readability (all your devices share one keypair)
- *   What it does NOT give you:
- *     • Protection against the Zeph backend itself
- *     • Forward secrecy — encryptPushBodyForSelf / encryptFileForSelf do
- *       ECDH(self, self), which collapses to a static derived key. A single
- *       device compromise (since all your devices share the same keypair)
- *       lets the attacker decrypt every past push for which they have the
- *       ciphertext. The per-message AES key is random, but its wrap key is
- *       static, so wrapped keys are decryptable forever.
+ *   This host holds its own ECDH keypair in ~/.zeph/device-keys.json. The
+ *   private half is generated here and never leaves — the server only ever
+ *   sees public keys. A push is encrypted once with a random AES key, and
+ *   that key is wrapped separately for each of the user's registered devices
+ *   using ECDH(this host, that device). Same keypair the stream frames below
+ *   already used; push and file bodies now share it.
  *
- *   True E2E would require a per-device keypair (server stores only public
- *   keys; senders wrap the message key once per recipient device public
- *   key). That refactor is on the roadmap; until then, treat push bodies as
- *   sensitive-but-not-secret.
+ * What it does not give you:
+ *   • Forward secrecy — the ECDH secret for a given (sender, device) pair is
+ *     static, so a compromise of either private key retroactively opens every
+ *     push wrapped for that pair.
+ *   • Authenticity beyond the key pairing — nothing signs `senderPublicKey`.
+ *
+ * Superseded scheme: a single account-wide keypair whose private half the
+ * backend escrowed so it could sync to new devices. Key escrow was removed
+ * server-side (zeph@8a6d21b) and `GET /users/me/keys` has returned a public
+ * key only ever since. This client used to react by generating a fresh
+ * account keypair and PUTting it back — which overwrote the account public
+ * key and encrypted to a key no device held. Both that upload path and the
+ * account keypair are gone.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.encryptEphemeral = exports.getDevicePublicKey = exports.initDeviceCrypto = exports.encryptFileForSelf = exports.encryptFileForRecipient = exports.encryptPushBodyForSelf = exports.encryptPushBody = exports.disableCrypto = exports.getPublicKey = exports.getKeyPair = exports.initCrypto = void 0;
+exports.decryptEphemeral = exports.encryptEphemeral = exports.getDevicePublicKey = exports.initDeviceCrypto = exports.encryptFileForDevices = exports.encryptPushBodyForDevices = exports.disableCrypto = exports.getPublicKey = exports.getKeyPair = exports.selectRecipients = exports.initCrypto = void 0;
 /// <reference lib="dom" />
 const fs_1 = require("fs");
 const os_1 = require("os");
@@ -91,108 +91,68 @@ const encrypt = async (plaintext, senderPrivateKey, recipientPublicKey) => {
         keyIv: toBase64(keyIv.buffer),
     };
 };
-// ─── File encryption ───
-const encryptFileContent = async (content, senderPrivateKey, recipientPublicKey) => {
-    const buffer = new TextEncoder().encode(content).buffer;
-    const fileKey = await crypto.subtle.generateKey({ name: 'AES-GCM', length: 256 }, true, ['encrypt', 'decrypt']);
-    const iv = crypto.getRandomValues(new Uint8Array(12));
-    const ciphertext = await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, fileKey, buffer);
-    const sharedKey = await deriveAesKey(senderPrivateKey, recipientPublicKey);
-    const rawFileKey = await crypto.subtle.exportKey('raw', fileKey);
-    const keyIv = crypto.getRandomValues(new Uint8Array(12));
-    const encryptedKey = await crypto.subtle.encrypt({ name: 'AES-GCM', iv: keyIv }, sharedKey, rawFileKey);
-    return {
-        ciphertext: Buffer.from(ciphertext),
-        iv: toBase64(iv.buffer),
-        encryptedKey: toBase64(encryptedKey),
-        keyIv: toBase64(keyIv.buffer),
-    };
+const decrypt = async (payload, recipientPrivateKey, senderPublicKey) => {
+    const sharedKey = await deriveAesKey(recipientPrivateKey, senderPublicKey);
+    const rawMessageKey = await crypto.subtle.decrypt({ name: 'AES-GCM', iv: new Uint8Array(fromBase64(payload.keyIv)) }, sharedKey, fromBase64(payload.encryptedKey));
+    const messageKey = await crypto.subtle.importKey('raw', rawMessageKey, { name: 'AES-GCM' }, false, ['decrypt']);
+    const plaintext = await crypto.subtle.decrypt({ name: 'AES-GCM', iv: new Uint8Array(fromBase64(payload.iv)) }, messageKey, fromBase64(payload.ciphertext));
+    return new TextDecoder().decode(plaintext);
 };
-// ─── Key persistence (~/.config/zeph/keys.json) ───
-const KEYS_DIR = (0, path_1.join)((0, os_1.homedir)(), '.config', 'zeph');
-const KEYS_PATH = (0, path_1.join)(KEYS_DIR, 'keys.json');
-const loadStoredKeys = () => {
+// ─── Superseded account keystore ───
+//
+// Held the escrowed account keypair. Nothing reads it any more; it is deleted
+// on sight so a private key the server no longer issues stops sitting on disk.
+const LEGACY_KEYS_PATH = (0, path_1.join)((0, os_1.homedir)(), '.config', 'zeph', 'keys.json');
+const deleteLegacyKeys = () => {
     try {
-        return JSON.parse((0, fs_1.readFileSync)(KEYS_PATH, 'utf-8'));
-    }
-    catch {
-        return null;
+        (0, fs_1.unlinkSync)(LEGACY_KEYS_PATH);
     }
-};
-const storeKeys = (exported) => {
-    (0, fs_1.mkdirSync)(KEYS_DIR, { recursive: true, mode: 0o700 });
-    (0, fs_1.writeFileSync)(KEYS_PATH, JSON.stringify(exported, null, 2), { mode: 0o600 });
+    catch { /* not present — fine */ }
 };
 // ─── Cached state ───
-let cachedKeyPair = null;
-let cachedExportedPublicKey = null;
-let cachedOwnPublicKey = null;
+/**
+ * Whether the account has opted into E2E (`encryptionEnabled`, ADR-0008).
+ * Kept separate from the device keypair because that keypair also backs
+ * stream frames, which are encrypted regardless — reading its presence as
+ * consent would turn push encryption on for everyone.
+ */
+let pushCryptoEnabled = false;
+let cachedLegacyPublicKey = null;
 let initPromise = null;
 /**
- * Initialize crypto: sync keys with server, then fallback to local/generate.
- * Server is source of truth for per-user key pair.
- * Safe to call concurrently — deduplicates to single init.
- * Returns the exported public key (Base64 SPKI).
+ * Initialize push/file encryption.
+ *
+ * Encryption turns on only when the account has explicitly opted in —
+ * `encryptionEnabled` from `GET /users/me/keys` is the single authoritative
+ * signal (ADR-0008). Server unreachable or flag off leaves it off and every
+ * send goes out in the clear.
+ *
+ * When it is on, this delegates to the per-device keypair: nothing is asked
+ * of the server but the flag, and nothing is ever uploaded.
+ *
+ * Safe to call concurrently — deduplicates to a single init.
+ * Returns this host's public key when encryption is active, '' otherwise.
  */
 const initCrypto = (apiKey, baseUrl) => {
     if (initPromise)
         return initPromise;
     initPromise = (async () => {
-        // Try local cache first
-        const stored = loadStoredKeys();
-        // Try server sync if API key available
-        if (apiKey) {
-            const serverResult = await fetchServerKeys(apiKey, baseUrl);
-            // Server says encryption disabled — skip crypto init
-            if (serverResult && !serverResult.encryptionEnabled) {
-                cachedKeyPair = null;
-                cachedExportedPublicKey = null;
-                cachedOwnPublicKey = null;
-                return '';
-            }
-            if (serverResult?.keys) {
-                // Server has keys — adopt them (server is source of truth)
-                if (!stored || stored.publicKey !== serverResult.keys.publicKey) {
-                    storeKeys(serverResult.keys);
-                }
-                cachedKeyPair = await importKeyPair(serverResult.keys);
-                cachedExportedPublicKey = serverResult.keys.publicKey;
-                cachedOwnPublicKey = cachedKeyPair.publicKey;
-                return serverResult.keys.publicKey;
-            }
-            // Server has no keys
-            if (stored) {
-                // Upload local keys to server
-                await uploadServerKeys(stored, apiKey, baseUrl);
-                cachedKeyPair = await importKeyPair(stored);
-                cachedExportedPublicKey = stored.publicKey;
-                cachedOwnPublicKey = cachedKeyPair.publicKey;
-                return stored.publicKey;
-            }
-            // No keys anywhere — generate + upload
-            const keyPair = await generateKeyPair();
-            const exported = await exportKeyPair(keyPair);
-            storeKeys(exported);
-            await uploadServerKeys(exported, apiKey, baseUrl);
-            cachedKeyPair = keyPair;
-            cachedExportedPublicKey = exported.publicKey;
-            cachedOwnPublicKey = keyPair.publicKey;
-            return exported.publicKey;
+        // Local-only mode (no apiKey): used by tests and offline setups. There is
+        // no flag to consult, so encryption stays off rather than being inferred.
+        if (!apiKey) {
+            pushCryptoEnabled = false;
+            return '';
         }
-        // No API key — local-only mode
-        if (stored) {
-            cachedKeyPair = await importKeyPair(stored);
-            cachedExportedPublicKey = stored.publicKey;
-            cachedOwnPublicKey = cachedKeyPair.publicKey;
-            return stored.publicKey;
+        const state = await fetchEncryptionState(apiKey, baseUrl);
+        if (state)
+            deleteLegacyKeys();
+        if (!state?.encryptionEnabled) {
+            pushCryptoEnabled = false;
+            return '';
         }
-        const keyPair = await generateKeyPair();
-        const exported = await exportKeyPair(keyPair);
-        storeKeys(exported);
-        cachedKeyPair = keyPair;
-        cachedExportedPublicKey = exported.publicKey;
-        cachedOwnPublicKey = keyPair.publicKey;
-        return exported.publicKey;
+        const publicKey = await (0, exports.initDeviceCrypto)();
+        pushCryptoEnabled = true;
+        return publicKey;
     })().catch((err) => {
         initPromise = null;
         throw err;
@@ -200,44 +160,74 @@ const initCrypto = (apiKey, baseUrl) => {
     return initPromise;
 };
 exports.initCrypto = initCrypto;
-const fetchServerKeys = async (apiKey, baseUrl) => {
+const fetchEncryptionState = async (apiKey, baseUrl) => {
     try {
         const url = `${(baseUrl ?? 'https://api.zeph.to/v1').replace(/\/$/, '')}/users/me/keys`;
         const res = await fetch(url, { headers: { 'X-API-Key': apiKey } });
         if (!res.ok)
             return null;
         const json = await res.json();
-        const keys = json.data?.encryptionKeys;
-        const encryptionEnabled = json.data?.encryptionEnabled ?? (keys ? true : false);
+        cachedLegacyPublicKey = json.data?.encryptionKeys?.publicKey ?? null;
         return {
-            keys: keys?.publicKey && keys?.privateKey ? keys : null,
-            encryptionEnabled,
+            encryptionEnabled: json.data?.encryptionEnabled === true,
+            legacyPublicKey: cachedLegacyPublicKey,
         };
     }
     catch {
         return null;
     }
 };
-// SECURITY: only the PUBLIC key is ever sent to the server. The server
-// rejects private-key uploads outright (per-device E2E — escrow removed),
-// and a private key must never leave this host. Sending the full
-// ExportedKeyPair previously leaked the private key onto the wire on every
-// init and the rejection was swallowed silently. The per-device migration
-// (see ADR-0007) reworks this path; until then, register the public key only.
-const uploadServerKeys = async (keys, apiKey, baseUrl) => {
-    try {
-        const url = `${(baseUrl ?? 'https://api.zeph.to/v1').replace(/\/$/, '')}/users/me/keys`;
-        await fetch(url, {
-            method: 'PUT',
-            headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json' },
-            body: JSON.stringify({ publicKey: keys.publicKey }),
-        });
+/**
+ * Keep only devices this host can actually encrypt for.
+ *
+ * A device without a public key has never run a build that registers one, and
+ * a device still advertising the account-wide key has not migrated to
+ * per-device E2E — wrapping for either produces a push it cannot open, which
+ * is worse than sending plaintext it can read.
+ */
+const selectRecipients = (devices) => devices
+    .filter((d) => !!d.publicKey && d.publicKey !== cachedLegacyPublicKey)
+    .map(({ deviceId, publicKey }) => ({ deviceId, publicKey }));
+exports.selectRecipients = selectRecipients;
+/**
+ * Wrap one raw AES key for every recipient device.
+ *
+ * The payload is encrypted once and only the wrapped key repeats, so an
+ * attachment costs one S3 object regardless of device count. A recipient
+ * whose public key will not import is dropped rather than failing the send —
+ * one broken device record must not silence every push.
+ */
+const wrapForDevices = async (rawKey, senderPrivateKey, recipients) => {
+    const entries = await Promise.all(recipients.map(async ({ deviceId, publicKey }) => {
+        try {
+            const sharedKey = await deriveAesKey(senderPrivateKey, await importPublicKey(publicKey));
+            const keyIv = crypto.getRandomValues(new Uint8Array(12));
+            const wrapped = await crypto.subtle.encrypt({ name: 'AES-GCM', iv: keyIv }, sharedKey, rawKey);
+            return [
+                deviceId,
+                JSON.stringify({ encryptedKey: toBase64(wrapped), keyIv: toBase64(keyIv.buffer) }),
+            ];
+        }
+        catch (err) {
+            console.error(`[Crypto] Skipping device ${deviceId} — unusable public key:`, err);
+            return null;
+        }
+    }));
+    const keyMap = {};
+    for (const entry of entries) {
+        if (entry)
+            keyMap[entry[0]] = entry[1];
     }
-    catch { /* non-critical */ }
+    if (Object.keys(keyMap).length === 0)
+        throw new Error('No recipient device accepted the wrapped key');
+    return keyMap;
 };
-const getKeyPair = () => cachedKeyPair;
+// Gated on the account opt-in, not on the keypair's existence: the same
+// keypair backs stream frames, which are encrypted regardless, so presence
+// alone would turn push encryption on for accounts that never asked.
+const getKeyPair = () => (pushCryptoEnabled ? deviceKeyPair : null);
 exports.getKeyPair = getKeyPair;
-const getPublicKey = () => cachedExportedPublicKey;
+const getPublicKey = () => (pushCryptoEnabled ? deviceExportedPublicKey : null);
 exports.getPublicKey = getPublicKey;
 /**
  * Drop the cached keys so every later send goes out as plaintext.
@@ -251,73 +241,55 @@ exports.getPublicKey = getPublicKey;
  * circuits on `cryptoInitialized`. A restart after an upgrade re-adopts them.
  */
 const disableCrypto = () => {
-    cachedKeyPair = null;
-    cachedExportedPublicKey = null;
-    cachedOwnPublicKey = null;
+    pushCryptoEnabled = false;
 };
 exports.disableCrypto = disableCrypto;
 /**
- * Encrypt push body for a recipient.
- * Returns fields ready to merge into the sendPush payload.
- */
-const encryptPushBody = async (input, recipientPublicKeyRaw) => {
-    if (!cachedKeyPair || !cachedExportedPublicKey)
-        throw new Error('Crypto not initialized');
-    const recipientKey = await importPublicKey(recipientPublicKeyRaw);
-    const payload = await encrypt(JSON.stringify({ title: input.title, body: input.body, url: input.url }), cachedKeyPair.privateKey, recipientKey);
-    return {
-        body: JSON.stringify({ ciphertext: payload.ciphertext, iv: payload.iv }),
-        encryptedKey: JSON.stringify({ encryptedKey: payload.encryptedKey, keyIv: payload.keyIv }),
-        senderPublicKey: cachedExportedPublicKey,
-        isEncrypted: true,
-    };
-};
-exports.encryptPushBody = encryptPushBody;
-/**
- * Encrypt push body for self (all own devices).
+ * Encrypt a push body for the given recipient devices.
+ *
+ * Returns the wire fields the API expects: `body` carries the ciphertext and
+ * IV, `deviceKeyMap` the per-device wrapped keys, `senderPublicKey` the half
+ * recipients need to derive the same secret back.
  */
-const encryptPushBodyForSelf = async (input) => {
-    if (!cachedKeyPair || !cachedExportedPublicKey || !cachedOwnPublicKey)
+const encryptPushBodyForDevices = async (input, recipients) => {
+    if (!deviceKeyPair || !deviceExportedPublicKey)
         throw new Error('Crypto not initialized');
-    const payload = await encrypt(JSON.stringify({ title: input.title, body: input.body, url: input.url }), cachedKeyPair.privateKey, cachedOwnPublicKey);
+    const messageKey = await crypto.subtle.generateKey({ name: 'AES-GCM', length: 256 }, true, ['encrypt', 'decrypt']);
+    const iv = crypto.getRandomValues(new Uint8Array(12));
+    const ciphertext = await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, messageKey, new TextEncoder().encode(JSON.stringify({ title: input.title, body: input.body, url: input.url })));
+    const rawMessageKey = await crypto.subtle.exportKey('raw', messageKey);
     return {
-        body: JSON.stringify({ ciphertext: payload.ciphertext, iv: payload.iv }),
-        encryptedKey: JSON.stringify({ encryptedKey: payload.encryptedKey, keyIv: payload.keyIv }),
-        senderPublicKey: cachedExportedPublicKey,
+        body: JSON.stringify({ ciphertext: toBase64(ciphertext), iv: toBase64(iv.buffer) }),
+        deviceKeyMap: await wrapForDevices(rawMessageKey, deviceKeyPair.privateKey, recipients),
+        senderPublicKey: deviceExportedPublicKey,
         isEncrypted: true,
     };
 };
-exports.encryptPushBodyForSelf = encryptPushBodyForSelf;
+exports.encryptPushBodyForDevices = encryptPushBodyForDevices;
 /**
- * Encrypt file content for a recipient.
- * Returns encrypted buffer + key material for file attachment metadata.
+ * Encrypt file content for the given recipient devices.
  */
-const encryptFileForRecipient = async (content, recipientPublicKeyRaw) => {
-    if (!cachedKeyPair)
+const encryptFileForDevices = async (content, recipients) => {
+    if (!deviceKeyPair)
         throw new Error('Crypto not initialized');
-    const recipientKey = await importPublicKey(recipientPublicKeyRaw);
-    const result = await encryptFileContent(content, cachedKeyPair.privateKey, recipientKey);
-    return {
-        ciphertext: result.ciphertext,
-        iv: result.iv,
-        encryptedKey: JSON.stringify({ encryptedKey: result.encryptedKey, keyIv: result.keyIv }),
-    };
-};
-exports.encryptFileForRecipient = encryptFileForRecipient;
-/**
- * Encrypt file content for self (all own devices).
- */
-const encryptFileForSelf = async (content) => {
-    if (!cachedKeyPair || !cachedOwnPublicKey)
-        throw new Error('Crypto not initialized');
-    const result = await encryptFileContent(content, cachedKeyPair.privateKey, cachedOwnPublicKey);
+    // Binary content must be encrypted byte for byte — running a Buffer through
+    // TextEncoder would UTF-8 mangle every non-ASCII byte. Today's only caller
+    // passes markdown, so this is a guard against the first binary sender rather
+    // than a live fix (the MCP twin took that bug in production).
+    const buffer = typeof content === 'string'
+        ? new TextEncoder().encode(content)
+        : new Uint8Array(content.buffer, content.byteOffset, content.byteLength);
+    const fileKey = await crypto.subtle.generateKey({ name: 'AES-GCM', length: 256 }, true, ['encrypt', 'decrypt']);
+    const iv = crypto.getRandomValues(new Uint8Array(12));
+    const ciphertext = await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, fileKey, buffer);
+    const rawFileKey = await crypto.subtle.exportKey('raw', fileKey);
     return {
-        ciphertext: result.ciphertext,
-        iv: result.iv,
-        encryptedKey: JSON.stringify({ encryptedKey: result.encryptedKey, keyIv: result.keyIv }),
+        ciphertext: Buffer.from(ciphertext),
+        iv: toBase64(iv.buffer),
+        deviceKeyMap: await wrapForDevices(rawFileKey, deviceKeyPair.privateKey, recipients),
     };
 };
-exports.encryptFileForSelf = encryptFileForSelf;
+exports.encryptFileForDevices = encryptFileForDevices;
 const DEVICE_KEYS_DIR = (0, path_1.join)((0, os_1.homedir)(), '.zeph');
 const DEVICE_KEYS_PATH = (0, path_1.join)(DEVICE_KEYS_DIR, 'device-keys.json');
 let deviceKeyPair = null;
@@ -377,3 +349,25 @@ const encryptEphemeral = async (plaintext, recipientPublicKeyRaw) => {
     return { ...payload, senderPublicKey: deviceExportedPublicKey };
 };
 exports.encryptEphemeral = encryptEphemeral;
+/**
+ * Open an ephemeral envelope addressed to this device — the exact inverse of
+ * encryptEphemeral, and of the web's `encrypt` from @zeph/crypto, which
+ * produces the same five fields.
+ *
+ * Rejects rather than returning null: AES-GCM is authenticated, so a throw
+ * here means the envelope was sealed for another key, tampered with, or is not
+ * an envelope at all. Callers must treat every rejection as a refusal — there
+ * is no partial result to fall back on. Requires initDeviceCrypto().
+ *
+ * Note that opening an envelope proves only that its sender holds the private
+ * half of `senderPublicKey`; nothing signs that field, so it authenticates the
+ * key pairing and not the sender. A caller that needs to know *which* peer
+ * sent this must compare `senderPublicKey` against a key it already trusts.
+ */
+const decryptEphemeral = async (payload) => {
+    if (!deviceKeyPair)
+        throw new Error('Device crypto not initialized');
+    const senderKey = await importPublicKey(payload.senderPublicKey);
+    return decrypt(payload, deviceKeyPair.privateKey, senderKey);
+};
+exports.decryptEphemeral = decryptEphemeral;

package/dist/gate.d.ts

@@ -19,6 +19,11 @@ export interface GateVerdict {
  * (most non-Claude agents pass no counts): in normal mode the push still
  * fires — preserving the historical always-push behavior of the dumb
  * hooks — while quiet/loud now work everywhere.
+ *
+ * These defaults cannot rescue a quiet dial: quiet only lets a `high` marker
+ * through, and a hook with no turn facts has no marker either. That is why
+ * the installed templates pass `--pushmode-default normal` (see templates.ts)
+ * — for them quiet is not a lower volume, it is permanent silence.
  */
 export declare const GATE_DEFAULTS: {
     readonly toolCount: 2;
@@ -41,6 +46,46 @@ export declare const remoteMarkerPath: (hash: string) => string;
 export declare const remoteDigest: (text: string) => string;
 /** True when the user ran /zeph-mute for this project. */
 export declare const isMuted: (dir: string) => boolean;
-/** The user's session push-mode dial (/zeph-quiet | /zeph-loud), default normal. */
-export declare const readPushMode: (dir: string) => GatePushMode;
+/**
+ * Push mode for an install that has never set a dial. The twin is
+ * plugin/hooks/gate.sh's missing-5th-argument default; the shared vectors
+ * never reach either one (every vector passes pushMode explicitly), so both
+ * sides pin it in their own tests.
+ */
+export declare const PUSHMODE_DEFAULT: GatePushMode;
+/**
+ * `notify` flag naming the push mode to assume when the project has no dial.
+ * Written by templates.ts into every hook-driven agent's completion hook and
+ * read back in cli.ts — shared so the two can never drift apart.
+ */
+export declare const PUSHMODE_DEFAULT_FLAG = "pushmode-default";
+/**
+ * The user's session push-mode dial (/zeph-quiet | /zeph-loud | /zeph-normal).
+ *
+ * Three failure shapes, three answers — "no dial" is the only one that gets
+ * the quiet default:
+ *   - no dial file          → `fallback` (PUSHMODE_DEFAULT unless the caller
+ *                             overrides it with --pushmode-default)
+ *   - unusable dial file    → normal. A missing project hash, an unreadable
+ *                             file, or a garbled/empty value is a broken
+ *                             setting, and resolving breakage to silence
+ *                             leaves the user with no symptom to debug. The
+ *                             point of the new default is quiet, not hidden
+ *                             errors.
+ *   - readable dial file    → whatever it says.
+ */
+export declare const readPushMode: (dir: string, fallback?: GatePushMode) => GatePushMode;
+/**
+ * Push mode for a `--auto` notify: the user's dial if they set one, otherwise
+ * the mode named by `--pushmode-default`, otherwise the built-in quiet.
+ *
+ * The dial outranks the flag deliberately. The flag exists so an agent whose
+ * hook cannot participate in the heuristic still pushes out of the box; if it
+ * outranked the dial, `/zeph-quiet` would silently do nothing for that agent.
+ *
+ * A flag value that isn't one of the three modes resolves to `normal`, not to
+ * the quiet default — same rule as a garbled dial file. A caller that passes
+ * nonsense has a bug, and answering a bug with silence hides it.
+ */
+export declare const autoPushMode: (dir: string, flag: string | boolean | undefined) => GatePushMode;
 //# sourceMappingURL=gate.d.ts.map

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;;;;;GAKG;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,oFAAoF;AACpF,eAAO,MAAM,YAAY,GAAI,KAAK,MAAM,KAAG,YAU1C,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;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"}

package/dist/gate.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.readPushMode = 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.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.
  *
@@ -30,6 +30,11 @@ const path_1 = require("path");
  * (most non-Claude agents pass no counts): in normal mode the push still
  * fires — preserving the historical always-push behavior of the dumb
  * hooks — while quiet/loud now work everywhere.
+ *
+ * These defaults cannot rescue a quiet dial: quiet only lets a `high` marker
+ * through, and a hook with no turn facts has no marker either. That is why
+ * the installed templates pass `--pushmode-default normal` (see templates.ts)
+ * — for them quiet is not a lower volume, it is permanent silence.
  */
 exports.GATE_DEFAULTS = {
     toolCount: 2,
@@ -133,14 +138,41 @@ const isMuted = (dir) => {
     return hash !== null && findStateFile('muted', hash) !== null;
 };
 exports.isMuted = isMuted;
-/** The user's session push-mode dial (/zeph-quiet | /zeph-loud), default normal. */
-const readPushMode = (dir) => {
+/**
+ * Push mode for an install that has never set a dial. The twin is
+ * plugin/hooks/gate.sh's missing-5th-argument default; the shared vectors
+ * never reach either one (every vector passes pushMode explicitly), so both
+ * sides pin it in their own tests.
+ */
+exports.PUSHMODE_DEFAULT = 'quiet';
+/**
+ * `notify` flag naming the push mode to assume when the project has no dial.
+ * Written by templates.ts into every hook-driven agent's completion hook and
+ * read back in cli.ts — shared so the two can never drift apart.
+ */
+exports.PUSHMODE_DEFAULT_FLAG = 'pushmode-default';
+/**
+ * The user's session push-mode dial (/zeph-quiet | /zeph-loud | /zeph-normal).
+ *
+ * Three failure shapes, three answers — "no dial" is the only one that gets
+ * the quiet default:
+ *   - no dial file          → `fallback` (PUSHMODE_DEFAULT unless the caller
+ *                             overrides it with --pushmode-default)
+ *   - unusable dial file    → normal. A missing project hash, an unreadable
+ *                             file, or a garbled/empty value is a broken
+ *                             setting, and resolving breakage to silence
+ *                             leaves the user with no symptom to debug. The
+ *                             point of the new default is quiet, not hidden
+ *                             errors.
+ *   - readable dial file    → whatever it says.
+ */
+const readPushMode = (dir, fallback = exports.PUSHMODE_DEFAULT) => {
     const hash = (0, exports.projectHash)(dir);
     if (!hash)
         return 'normal';
     const file = findStateFile('pushmode', hash);
     if (!file)
-        return 'normal';
+        return fallback;
     try {
         return (0, exports.normalizePushMode)((0, fs_1.readFileSync)(file, 'utf-8').replace(/\s+/g, ''));
     }
@@ -149,3 +181,17 @@ const readPushMode = (dir) => {
     }
 };
 exports.readPushMode = readPushMode;
+/**
+ * Push mode for a `--auto` notify: the user's dial if they set one, otherwise
+ * the mode named by `--pushmode-default`, otherwise the built-in quiet.
+ *
+ * The dial outranks the flag deliberately. The flag exists so an agent whose
+ * hook cannot participate in the heuristic still pushes out of the box; if it
+ * outranked the dial, `/zeph-quiet` would silently do nothing for that agent.
+ *
+ * A flag value that isn't one of the three modes resolves to `normal`, not to
+ * the quiet default — same rule as a garbled dial file. A caller that passes
+ * nonsense has a bug, and answering a bug with silence hides it.
+ */
+const autoPushMode = (dir, flag) => (0, exports.readPushMode)(dir, typeof flag === 'string' ? (0, exports.normalizePushMode)(flag) : exports.PUSHMODE_DEFAULT);
+exports.autoPushMode = autoPushMode;