@zeph-to/cli 1.12.0 → 1.13.1

package/dist/listener.d.ts

@@ -87,6 +87,20 @@ export declare const collectSessionsVerbose: () => CollectResult;
  * — the phone can't usefully address them.
  */
 export declare const collectSessions: () => AgentSession[];
+/**
+ * One file riding on an `agent.command` push. agent.command attachments
+ * are uploaded in *plaintext* (the listener has no per-user crypto key),
+ * so `iv`/`encryptedKey` should be absent. If either is present the file
+ * is encrypted and the listener can't read it — it gets skipped.
+ */
+interface PushFileAttachment {
+    fileKey: string;
+    fileName: string;
+    fileType?: string;
+    fileSize?: number;
+    iv?: string;
+    encryptedKey?: string;
+}
 interface PushItem {
     pushId: string;
     type?: string;
@@ -96,13 +110,27 @@ interface PushItem {
     isEncrypted?: boolean;
     /** Set when type='agent.command' — tmux session name to inject into. */
     agentSessionName?: string;
+    /** Optional image/file attachments (agent.command only, plaintext). */
+    files?: PushFileAttachment[];
 }
 interface HandlePushDeps {
     paneCommand?: (session: string) => string | null;
     inject?: (session: string, text: string) => boolean;
     rateLimit?: (session: string) => boolean;
     now?: () => number;
+    /** Injectable for tests; defaults to the REST-backed downloader. */
+    downloadAttachments?: (pushId: string, files: PushFileAttachment[]) => Promise<string[]>;
 }
+export declare const setAttachmentContext: (ctx: {
+    apiKey: string;
+    baseUrl: string;
+}) => void;
+/**
+ * Remove attachment sub-directories whose mtime is older than `ttl`.
+ * Best-effort: an entry that can't be statted or removed is skipped, not
+ * fatal. Returns the count removed. `dir`/`ttl` are injectable for tests.
+ */
+export declare const gcAttachments: (now?: number, dir?: string, ttl?: number) => number;
 /**
  * Process one push. Returns true when an injection actually fired.
  * Exported for unit testing with mocked deps.
@@ -112,7 +140,7 @@ interface HandlePushDeps {
  * `body`. Everything else (Stop-hook auto-pushes, zeph_ask responses,
  * encrypted pushes, normal text/link/file notifications) is ignored.
  */
-export declare const handlePush: (push: PushItem, deps?: HandlePushDeps) => boolean;
+export declare const handlePush: (push: PushItem, deps?: HandlePushDeps) => Promise<boolean>;
 /**
  * Stable per-host device id for the listener. We hash the OS hostname so
  * the same machine reuses the same DeviceRecord across listener restarts

package/dist/listener.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"listener.d.ts","sourceRoot":"","sources":["../src/listener.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAmCH,KAAK,SAAS,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;AAG/C,UAAU,YAAY;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,SAAS,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;CAC3B;AA2BD,eAAO,MAAM,cAAc,GAAI,SAAS,MAAM,EAAE,MAAK,MAAmB,KAAG,OAgB1E,CAAC;AAEF,2EAA2E;AAC3E,eAAO,MAAM,kBAAkB,GAAI,SAAS,MAAM,KAAG,MAAM,GAAG,IAO7D,CAAC;AAiDF;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,QAAO,IAG5C,CAAC;AA8NF;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,KAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,IAK3F,CAAC;AAuCF;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,IAiB5D,CAAC;AAkFF,MAAM,WAAW,aAAa;IAC1B,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrD;AAED;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,QAAO,aA+DzC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,QAAO,YAAY,EAAuC,CAAC;AAIvF,UAAU,QAAQ;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,wEAAwE;IACxE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,UAAU,cAAc;IACpB,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACjD,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACpD,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IACzC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACtB;AAgCD;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,GACnB,MAAM,QAAQ,EACd,OAAM,cAAmB,KAC1B,OAQF,CAAC;AA2BF;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,GAAI,OAAM,MAAmB,KAAG,MAGnE,CAAC;AA8NF,eAAO,MAAM,cAAc,GAAU,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAG,OAAO,CAAC,MAAM,CAyF3F,CAAC"}
+{"version":3,"file":"listener.d.ts","sourceRoot":"","sources":["../src/listener.ts"],"names":[],"mappings":"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"}

package/dist/listener.js

@@ -25,7 +25,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.handleListener = exports.computeListenerDeviceId = exports.handlePush = exports.collectSessions = exports.collectSessionsVerbose = exports.detectClaudeSessionId = exports.parseSessionName = exports.invalidateTmuxSocketCache = exports.paneCurrentCommand = exports.checkRateLimit = void 0;
+exports.handleListener = exports.computeListenerDeviceId = exports.handlePush = exports.gcAttachments = exports.setAttachmentContext = exports.collectSessions = exports.collectSessionsVerbose = exports.detectClaudeSessionId = exports.parseSessionName = exports.invalidateTmuxSocketCache = exports.paneCurrentCommand = exports.checkRateLimit = void 0;
 const child_process_1 = require("child_process");
 const crypto_1 = require("crypto");
 const fs_1 = require("fs");
@@ -647,6 +647,124 @@ const tryInject = (session, text, deps) => {
     log(`${ok ? '→' : '✗'} ${session}: ${preview}`);
     return ok;
 };
+// ─── Attachment download (agent.command files[]) ────────────────────
+const ATTACHMENTS_DIR = (0, path_1.join)((0, os_1.homedir)(), '.zeph', 'attachments');
+const DEFAULT_API_BASE = 'https://api.zeph.to/v1';
+// apiKey + baseUrl for the file-download REST calls, set once in
+// handleListener. The default downloader reads it. null until the daemon
+// resolves credentials (handlePush isn't called before then in the real
+// flow, but the guard keeps it safe).
+let attachmentCtx = null;
+const setAttachmentContext = (ctx) => {
+    attachmentCtx = ctx;
+};
+exports.setAttachmentContext = setAttachmentContext;
+/**
+ * Make a filesystem-safe single path segment: take the basename (drops
+ * any `../` prefix), strip control chars and embedded separators, remove
+ * leading dots, and cap length. Empty/dot-only names use the fallback.
+ */
+const safeSegment = (raw, fallback) => {
+    const cleaned = (0, path_1.basename)(raw)
+        .replace(/[\x00-\x1f\x7f]/g, '')
+        .replace(/[/\\]/g, '_')
+        .replace(/^\.+/, '')
+        .trim();
+    return (cleaned || fallback).slice(0, 200);
+};
+/** Resolve fileKey → presigned URL → bytes. Throws on any HTTP failure so
+ *  the caller can isolate one file's failure from the rest of the batch. */
+const fetchAttachmentBytes = async (fileKey, ctx) => {
+    const metaUrl = `${ctx.baseUrl.replace(/\/+$/, '')}/files/${encodeURIComponent(fileKey)}`;
+    const meta = await fetch(metaUrl, { headers: { 'X-API-Key': ctx.apiKey } });
+    if (!meta.ok)
+        throw new Error(`metadata ${meta.status}`);
+    // Server wraps responses as { data: { downloadUrl } } (see lib/response ok()).
+    const body = (await meta.json());
+    const downloadUrl = body.data?.downloadUrl ?? body.downloadUrl;
+    if (!downloadUrl)
+        throw new Error('response had no downloadUrl');
+    // The presigned URL is self-authenticating — no API key header.
+    const bin = await fetch(downloadUrl);
+    if (!bin.ok)
+        throw new Error(`download ${bin.status}`);
+    return Buffer.from(await bin.arrayBuffer());
+};
+/**
+ * Download every plaintext attachment to
+ * `~/.zeph/attachments/<pushId>/<fileName>` and return absolute paths.
+ * Encrypted files are skipped (no key). A single file's failure is logged
+ * and skipped — it never aborts the batch, so a partial download still
+ * injects whatever succeeded. Files are kept (not deleted) so the agent
+ * can read them after injection.
+ */
+const downloadAttachments = async (pushId, files, ctx) => {
+    const dir = (0, path_1.join)(ATTACHMENTS_DIR, safeSegment(pushId, 'push'));
+    const paths = [];
+    for (const [i, f] of files.entries()) {
+        if (f.iv || f.encryptedKey) {
+            log(`! attachment "${f.fileName}": encrypted (iv/encryptedKey present) — listener can't decrypt, skipping`);
+            continue;
+        }
+        try {
+            const bytes = await fetchAttachmentBytes(f.fileKey, ctx);
+            (0, fs_1.mkdirSync)(dir, { recursive: true });
+            const abs = (0, path_1.join)(dir, safeSegment(f.fileName || `file-${i}`, `file-${i}`));
+            (0, fs_1.writeFileSync)(abs, bytes);
+            paths.push(abs);
+            log(`⇣ ${f.fileName} → ${abs} (${bytes.length}B)`);
+        }
+        catch (err) {
+            log(`! attachment "${f.fileName}": download failed — ${err.message}`);
+        }
+    }
+    return paths;
+};
+const defaultDownloadAttachments = (pushId, files) => {
+    if (!attachmentCtx) {
+        log('! attachment context not initialised — skipping files');
+        return Promise.resolve([]);
+    }
+    return downloadAttachments(pushId, files, attachmentCtx);
+};
+/**
+ * Combine the command body with downloaded file paths, one per line.
+ * Claude Code reads local image paths from the prompt text, so appending
+ * absolute paths makes the agent load them. Empty body → paths only.
+ */
+const composeInjection = (body, paths) => paths.length ? [body, ...paths].filter(Boolean).join('\n') : body;
+// Downloaded attachments are kept after injection (the agent reads them
+// from disk), so they accumulate. A per-push dir older than this is GC'd —
+// long enough to outlive any realistic agent read, short enough that the
+// directory can't grow without bound on a long-running daemon.
+const ATTACHMENT_TTL_MS = 24 * 60 * 60 * 1000;
+/**
+ * Remove attachment sub-directories whose mtime is older than `ttl`.
+ * Best-effort: an entry that can't be statted or removed is skipped, not
+ * fatal. Returns the count removed. `dir`/`ttl` are injectable for tests.
+ */
+const gcAttachments = (now = Date.now(), dir = ATTACHMENTS_DIR, ttl = ATTACHMENT_TTL_MS) => {
+    let removed = 0;
+    let entries;
+    try {
+        entries = (0, fs_1.readdirSync)(dir);
+    }
+    catch {
+        return 0;
+    }
+    for (const name of entries) {
+        const full = (0, path_1.join)(dir, name);
+        try {
+            if (now - (0, fs_1.statSync)(full).mtimeMs <= ttl)
+                continue;
+            (0, fs_1.rmSync)(full, { recursive: true, force: true });
+            removed++;
+        }
+        catch { /* skip unreadable/unremovable entries */ }
+    }
+    return removed;
+};
+exports.gcAttachments = gcAttachments;
 /**
  * Process one push. Returns true when an injection actually fired.
  * Exported for unit testing with mocked deps.
@@ -656,7 +774,7 @@ const tryInject = (session, text, deps) => {
  * `body`. Everything else (Stop-hook auto-pushes, zeph_ask responses,
  * encrypted pushes, normal text/link/file notifications) is ignored.
  */
-const handlePush = (push, deps = {}) => {
+const handlePush = async (push, deps = {}) => {
     if (push.isEncrypted) {
         // Per-device keys aren't wired yet; encrypted pushes are opaque
         // to the listener.
@@ -664,7 +782,20 @@ const handlePush = (push, deps = {}) => {
     }
     if (push.type !== 'agent.command' || !push.agentSessionName)
         return false;
-    return tryInject(push.agentSessionName, push.body ?? '', deps);
+    // Download any attachments BEFORE injecting so the agent can read the
+    // local paths immediately. A download-phase failure is isolated: the
+    // body text still injects so the command itself isn't blocked.
+    let paths = [];
+    if (push.files?.length) {
+        const download = deps.downloadAttachments ?? defaultDownloadAttachments;
+        try {
+            paths = await download(push.pushId, push.files);
+        }
+        catch (err) {
+            log(`! ${push.agentSessionName}: attachment download failed — ${err.message}`);
+        }
+    }
+    return tryInject(push.agentSessionName, composeInjection(push.body ?? '', paths), deps);
 };
 exports.handlePush = handlePush;
 // ─── WS connect loop ─────────────────────────────────────────────────
@@ -850,8 +981,12 @@ const streamSession = (wsUrl, apiKey) => {
             const m = msg;
             if (m.type === 'pong')
                 return;
-            if (m.type === 'push.new' && m.data)
-                (0, exports.handlePush)(m.data);
+            if (m.type === 'push.new' && m.data) {
+                // Fire-and-forget: handlePush is async (attachment download)
+                // but the WS read loop must stay responsive. Errors are
+                // logged, never thrown into the socket handler.
+                void (0, exports.handlePush)(m.data).catch((err) => log(`! handlePush: ${err.message}`));
+            }
             // Surface server-side errors from listener.sessions reports.
             // Without this the daemon happily logs "reported N session(s)"
             // even when the server is silently dropping every message —
@@ -948,6 +1083,10 @@ const handleListener = async (args) => {
         console.error('zeph listener: API key required. Run `zeph install` or set ZEPH_API_KEY.');
         return 3;
     }
+    // Base URL for attachment downloads (GET /v1/files/{fileKey}). Same
+    // resolution order as the rest of the CLI; falls back to the prod API.
+    const baseUrl = args['base-url'] || (0, config_js_1.resolvedEnv)('ZEPH_BASE_URL') || config.baseUrl || DEFAULT_API_BASE;
+    (0, exports.setAttachmentContext)({ apiKey, baseUrl });
     const wsUrl = resolveWsUrl(args, config);
     if (!wsUrl) {
         console.error('zeph listener: WebSocket URL not set. Either:\n' +
@@ -972,6 +1111,16 @@ const handleListener = async (args) => {
         log(`heap: rss=${mb(m.rss)}MB heapUsed=${mb(m.heapUsed)}MB external=${mb(m.external)}MB`);
     }, HEAP_LOG_INTERVAL_MS);
     heapLogTimer.unref();
+    // Sweep stale attachment dirs at startup, then hourly. Keeps
+    // ~/.zeph/attachments from growing without bound over a long run.
+    const sweepAttachments = () => {
+        const n = (0, exports.gcAttachments)();
+        if (n > 0)
+            log(`gc: removed ${n} stale attachment dir(s)`);
+    };
+    sweepAttachments();
+    const gcTimer = setInterval(sweepAttachments, 60 * 60 * 1000);
+    gcTimer.unref();
     let shuttingDown = false;
     let activeHandle = null;
     const stop = (sig) => {

package/dist/login.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"login.d.ts","sourceRoot":"","sources":["../src/login.ts"],"names":[],"mappings":"AAUA;;sCAEsC;AACtC,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,KAAK,cAAc,GACf;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,GACrC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAIlD,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,CAAC,KAAG,OAAO,CAAC,CAAC,CAMnF,CAAC;AAEF,eAAO,MAAM,cAAc,GAAI,QAAQ,MAAM,EAAE,MAAM,MAAM,EAAE,OAAO,MAAM,EAAE,MAAM,MAAM,KAAG,MAI1F,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,MAAM,eAAe,KAAG,IAGrD,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,QAAQ,MAAM,EAAE,eAAe,MAAM,KAAG,cAmBrE,CAAC;AAgFF,eAAO,MAAM,aAAa,GAAI,KAAK,MAAM,GAAG,OAAO,GAAG,SAAS,KAAG,MACjB,CAAC;AAElD,eAAO,MAAM,iBAAiB,GAAI,KAAK,MAAM,GAAG,OAAO,GAAG,SAAS,KAAG,MAKrE,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GACvB,MAAM;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,EAC5C,OAAM;IAAE,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;CAAO,KAC7C,OAAO,CAAC,eAAe,GAAG,IAAI,CAmChC,CAAC;AAEF,eAAO,MAAM,WAAW,GAAU,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAG,OAAO,CAAC,MAAM,CAcxF,CAAC"}
+{"version":3,"file":"login.d.ts","sourceRoot":"","sources":["../src/login.ts"],"names":[],"mappings":"AAUA;;sCAEsC;AACtC,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,KAAK,cAAc,GACf;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,GACrC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAIlD,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,CAAC,KAAG,OAAO,CAAC,CAAC,CAMnF,CAAC;AAEF,eAAO,MAAM,cAAc,GAAI,QAAQ,MAAM,EAAE,MAAM,MAAM,EAAE,OAAO,MAAM,EAAE,MAAM,MAAM,KAAG,MAI1F,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,MAAM,eAAe,KAAG,IAGrD,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,QAAQ,MAAM,EAAE,eAAe,MAAM,KAAG,cAmBrE,CAAC;AAwKF,eAAO,MAAM,aAAa,GAAI,KAAK,MAAM,GAAG,OAAO,GAAG,SAAS,KAAG,MACjB,CAAC;AAElD,eAAO,MAAM,iBAAiB,GAAI,KAAK,MAAM,GAAG,OAAO,GAAG,SAAS,KAAG,MAKrE,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GACvB,MAAM;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,EAC5C,OAAM;IAAE,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;CAAO,KAC7C,OAAO,CAAC,eAAe,GAAG,IAAI,CAmChC,CAAC;AAEF,eAAO,MAAM,WAAW,GAAU,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAG,OAAO,CAAC,MAAM,CAcxF,CAAC"}

package/dist/login.js

@@ -71,9 +71,77 @@ const openBrowser = (url) => {
     }
 };
 // ── Loopback server ──────────────────────────────────────────────
-const DONE_HTML = '<!doctype html><meta charset="utf-8"><title>Zeph</title>' +
-    '<body style="font-family:system-ui;text-align:center;padding:3rem">' +
-    '<h2>Connected</h2><p>You can close this tab and return to the terminal.</p></body>';
+// The callback page is served from a loopback server with no network access,
+// so it inlines all styles and a single load-time animation — no external
+// fonts or assets. It's on screen for only a few seconds before the user
+// returns to the terminal, so its whole job is to confirm state and point back.
+const esc = (s) => s.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]));
+// Glyph drawn inside a 56×56 ring. `ok` = check, `error` = exclamation
+// (the trailing `h0.01` path renders as a dot via the round line cap).
+const GLYPH = {
+    ok: '<path d="M17 29l7.5 7.5L39 19"/>',
+    error: '<path d="M28 15v17"/><path d="M28 40h0.01"/>',
+};
+const PAGE_STYLE = `*{box-sizing:border-box;margin:0}
+:root{--bg:#0A0C12;--text:#EAEEF8;--muted:#79829A;--primary:#8B9BFF;
+--ok:#5FE3B3;--warn:#FF8C7A;--card:rgba(255,255,255,.03);--line:rgba(255,255,255,.09);--accent:var(--primary)}
+body.ok{--accent:var(--ok)}body.error{--accent:var(--warn)}
+@media(prefers-color-scheme:light){:root{--bg:#F4F6FB;--text:#171A22;--muted:#5C6478;
+--card:rgba(10,12,18,.025);--line:rgba(10,12,18,.09)}}
+html,body{height:100%}
+body{font-family:system-ui,-apple-system,"Segoe UI",sans-serif;background:var(--bg);color:var(--text);
+display:grid;place-items:center;padding:2rem;position:relative;overflow:hidden}
+body::before{content:"";position:fixed;inset:0;z-index:0;opacity:0;animation:glow 1.1s ease forwards;
+background:radial-gradient(60% 48% at 50% 14%,color-mix(in oklab,var(--accent) 24%,transparent),transparent 70%)}
+.card{position:relative;z-index:1;text-align:center;max-width:30rem;
+display:flex;flex-direction:column;align-items:center;gap:.85rem}
+.glyph{width:72px;height:72px;margin-bottom:.3rem}
+.glyph .ring,.glyph .mark>*{fill:none;stroke:var(--accent);stroke-width:3;stroke-linecap:round;stroke-linejoin:round}
+.glyph .ring{stroke:color-mix(in oklab,var(--accent) 38%,transparent);
+stroke-dasharray:151;stroke-dashoffset:151;animation:draw .7s ease forwards}
+.glyph .mark>*{stroke-dasharray:44;stroke-dashoffset:44;animation:draw .5s .45s ease forwards}
+h1{font-size:clamp(1.55rem,5vw,2.05rem);font-weight:700;letter-spacing:-.03em;line-height:1.06;animation:rise .6s .15s both}
+p{color:var(--muted);font-size:1.02rem;line-height:1.5;max-width:23rem;animation:rise .6s .25s both}
+.chip{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:.82rem;color:var(--text);
+background:var(--card);border:1px solid var(--line);border-radius:.55rem;padding:.45rem .7rem;
+margin-top:.35rem;animation:rise .6s .35s both}
+.brand{position:fixed;bottom:1.4rem;left:0;right:0;z-index:1;text-align:center;
+font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:.72rem;letter-spacing:.4em;
+text-transform:lowercase;color:var(--muted);opacity:.55}
+@keyframes glow{to{opacity:1}}
+@keyframes draw{to{stroke-dashoffset:0}}
+@keyframes rise{from{opacity:0;transform:translateY(8px)}to{opacity:1;transform:none}}
+@media(prefers-reduced-motion:reduce){*{animation-duration:.001s!important;animation-delay:0s!important}
+body::before{opacity:1}.glyph .ring,.glyph .mark>*{stroke-dashoffset:0}}`;
+const renderPage = (variant, title, message, hint) => `<!doctype html><html lang="en"><head><meta charset="utf-8">` +
+    `<meta name="viewport" content="width=device-width,initial-scale=1">` +
+    `<title>Zeph</title><style>${PAGE_STYLE}</style></head>` +
+    `<body class="${variant}"><main class="card">` +
+    `<svg class="glyph" viewBox="0 0 56 56" aria-hidden="true">` +
+    `<circle class="ring" cx="28" cy="28" r="24"/><g class="mark">${GLYPH[variant]}</g></svg>` +
+    `<h1>${esc(title)}</h1><p>${esc(message)}</p>` +
+    (hint ? `<code class="chip">${esc(hint)}</code>` : '') +
+    `</main><footer class="brand">zeph</footer></body></html>`;
+// Turn an internal callback failure reason into end-user guidance: name what
+// happened and how to recover, in the interface's voice — never an apology.
+const errorPage = (reason) => {
+    const copy = {
+        'state mismatch': [
+            "Sign-in didn't match",
+            "This link didn't match the request that started it. Return to your terminal and run login again.",
+        ],
+        'missing key': [
+            'No key came back',
+            'The sign-in finished without a key. Return to your terminal and run login again.',
+        ],
+        'not found': [
+            'Nothing to see here',
+            'This page only handles the Zeph login callback.',
+        ],
+    };
+    const [title, message] = copy[reason] ?? ['Something went wrong', reason];
+    return renderPage('error', title, message);
+};
 const respond = (res, status, body) => {
     res.writeHead(status, { 'content-type': 'text/html; charset=utf-8' });
     res.end(body);
@@ -88,13 +156,13 @@ const startLoopbackServer = (state) => {
     const server = (0, node_http_1.createServer)((req, res) => {
         const result = (0, exports.parseCallback)(req.url ?? '/', state);
         if (!result.ok) {
-            respond(res, result.status, `<p>${result.reason}</p>`);
+            respond(res, result.status, errorPage(result.reason));
             if (result.status === 403)
                 fail(new Error('state mismatch — refused'));
             return;
         }
         (0, exports.persistConfig)(result.config);
-        respond(res, 200, DONE_HTML);
+        respond(res, 200, renderPage('ok', "You're connected", 'Close this tab and head back to your terminal.', 'zeph is ready'));
         settle(result.config);
     });
     return new Promise((resolveHandle, rejectHandle) => {

package/dist/templates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../src/templates.ts"],"names":[],"mappings":"AA6JA,6EAA6E;AAC7E,eAAO,MAAM,WAAW,QAGtB,CAAC;AAEH,6EAA6E;AAC7E,eAAO,MAAM,aAAa,QAA4C,CAAC;AAEvE,sDAAsD;AACtD,eAAO,MAAM,WAAW,QAA4C,CAAC;AAErE,oDAAoD;AACpD,eAAO,MAAM,UAAU,QAA4C,CAAC;AAEpE,oFAAoF;AACpF,eAAO,MAAM,YAAY,QAA4C,CAAC;AAEtE,gEAAgE;AAChE,eAAO,MAAM,UAAU,QAAuC,CAAC;AAE/D,4FAA4F;AAC5F,eAAO,MAAM,UAAU,QAAuC,CAAC;AAI/D,eAAO,MAAM,YAAY,QAKd,CAAC;AAEZ,eAAO,MAAM,cAAc,QAOhB,CAAC;AAEZ,eAAO,MAAM,YAAY;;;;;;;;;;;;;;CAYxB,CAAC;AAEF,eAAO,MAAM,WAAW,QAQb,CAAC;AAEZ,eAAO,MAAM,aAAa,QASf,CAAC;AASZ,eAAO,MAAM,eAAe,oFAA+E,CAAC;AAC5G,eAAO,MAAM,aAAa,sBAAsB,CAAC;AAQjD;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAAI,UAAU,MAAM,EAAE,MAAM,MAAM,KAAG,MAWnE,CAAC;AAEF,uEAAuE;AACvE,eAAO,MAAM,kBAAkB,GAAI,UAAU,MAAM,KAAG,MAOrD,CAAC"}
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../src/templates.ts"],"names":[],"mappings":"AAgNA,6EAA6E;AAC7E,eAAO,MAAM,WAAW,QAGtB,CAAC;AAEH,6EAA6E;AAC7E,eAAO,MAAM,aAAa,QAA4C,CAAC;AAEvE,sDAAsD;AACtD,eAAO,MAAM,WAAW,QAA4C,CAAC;AAErE,oDAAoD;AACpD,eAAO,MAAM,UAAU,QAA4C,CAAC;AAEpE,oFAAoF;AACpF,eAAO,MAAM,YAAY,QAA4C,CAAC;AAEtE,gEAAgE;AAChE,eAAO,MAAM,UAAU,QAAuC,CAAC;AAE/D,4FAA4F;AAC5F,eAAO,MAAM,UAAU,QAAuC,CAAC;AAI/D,eAAO,MAAM,YAAY,QAKd,CAAC;AAEZ,eAAO,MAAM,cAAc,QAOhB,CAAC;AAEZ,eAAO,MAAM,YAAY;;;;;;;;;;;;;;CAYxB,CAAC;AAEF,eAAO,MAAM,WAAW,QAQb,CAAC;AAEZ,eAAO,MAAM,aAAa,QASf,CAAC;AASZ,eAAO,MAAM,eAAe,oFAA+E,CAAC;AAC5G,eAAO,MAAM,aAAa,sBAAsB,CAAC;AAQjD;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAAI,UAAU,MAAM,EAAE,MAAM,MAAM,KAAG,MAWnE,CAAC;AAEF,uEAAuE;AACvE,eAAO,MAAM,kBAAkB,GAAI,UAAU,MAAM,KAAG,MAOrD,CAAC"}

package/dist/templates.js

@@ -26,95 +26,146 @@ exports.removeManagedBlock = exports.upsertManagedBlock = exports.ZEPH_MARK_END
 const NOTIFY_CMD = '$(command -v zeph || echo "npx -y @zeph-to/cli") notify --title "Task done" 2>/dev/null || true';
 // ── Shared behavioral core ───────────────────────────────────────
 //
-// Identical across every agent. Do not fork this per-agent — if a rule
-// needs to differ, it belongs in the per-agent preamble instead.
-const ZEPH_CORE = `## NEVER end a response with a plain-text question
+// Identical across every agent. Source of truth: plugin/docs/CORE_RULES.md
+// Do not fork this per-agent — if a rule needs to differ, it belongs in
+// the per-agent preamble instead.
+//
+// Last synced: 2026-06-26
+// To update: extract rules from plugin/docs/CORE_RULES.md and sync here.
+const ZEPH_CORE = `## When zeph_ask is MANDATORY
 
 When ZEPH_HOOK_ID is set the user is driving you remotely, often from
-their phone. A "?" written in your reply text is invisible to them. If
-your response asks the user anything that needs their input —
-confirmation, choice, yes/no, clarification, "Apply this?", "Proceed?",
-"Which option?" — the FINAL tool call MUST be zeph_ask. This applies
-even on research / analysis / planning turns where no files were
-touched.
+their phone. A "?" written in your reply text is invisible to them.
+
+3. NEVER end a response with a plain-text question. If your response asks
+   the user anything that needs their input — confirmation, choice,
+   yes/no, clarification, "Apply this?", "Proceed?", "Which option?" —
+   the FINAL tool call MUST be zeph_ask. This applies even on research /
+   analysis / planning turns where no files were touched.
+
+   Anti-pattern (wrong):
+     "...build/commit on hold. Apply A?"
+   Correct:
+     zeph_ask({
+       title: "Apply solution A?",
+       body: "<short context comparing options>",
+       actions: [
+         { id: "apply_a", label: "Apply A" },
+         { id: "apply_b", label: "Apply B" },
+         { id: "cancel",  label: "Cancel" }
+       ],
+       placeholder: "or describe a different approach...",
+       fallback: "cancel"
+     })
 
-Anti-pattern (wrong):
-  "...build/commit on hold. Apply A?"
-Correct:
-  zeph_ask({
-    title: "Apply solution A?",
-    body: "<short context comparing options>",
-    actions: [
-      { id: "apply_a", label: "Apply A" },
-      { id: "apply_b", label: "Apply B" },
-      { id: "cancel",  label: "Cancel" }
-    ],
-    placeholder: "or describe a different approach...",
-    fallback: "cancel"
-  })
+## When zeph_ask is the DEFAULT (substantial work)
 
-## zeph_ask is the DEFAULT after substantial work
+4. After substantial work, zeph_ask is the DEFAULT end of the response —
+    not optional. "Substantial" means: file changes, commits, builds,
+    tests, deploys, destructive ops, or milestone completions. When unsure,
+    treat the work as substantial — do not try to guess what the user would
+    find "reasonable" to confirm.
 
-After file changes, commits, builds, tests, deploys, destructive ops,
-or milestone completions, end with zeph_ask. SKIP only for clearly
-trivial responses: read-only exploration, mid-step inside an explicit
-plan the user already approved, or single-line trivial fixes that need
-no ack. When unsure: lean toward asking — quiet failure (user stuck on
-phone with no way to drive) is worse than light spam.
+    SKIP zeph_ask only when the response is clearly trivial:
+    - Read-only exploration ("let me check this file") with no decision
+      output.
+    - Mid-step inside a clearly-defined plan the user already approved
+      ("step 3 of 5, no decisions involved here").
+    - Trivial change (typo fix, single-line tweak) that needs no ack.
 
-Example shape:
-  zeph_ask({
-    title: "Done. Next?",
-    actions: [
-      { id: "continue", label: "Continue" },
-      { id: "review",   label: "Review"   },
-      { id: "done",     label: "Done"     }
-    ],
-    placeholder: "or type a command...",
-    fallback: "done"
-  })
+    When unsure: LEAN TOWARD ASKING. Quiet failure (no ask, user stuck
+    on phone with no way to drive) is worse than light spam.
+
+5. Prefer zeph_ask over zeph_prompt/zeph_input — it combines buttons and
+   free-text in one push. Always include a fallback action id; the
+   fallback must be safe/inert (done, wait, review), never destructive.
+
+6. Example zeph_ask shape:
+     zeph_ask({
+       title: "Done. Next?",
+       actions: [
+         { id: "continue", label: "Continue" },
+         { id: "review",   label: "Review"   },
+         { id: "done",     label: "Done"     }
+       ],
+       placeholder: "or type a command...",
+       fallback: "done"
+     })
 
 ## Handling the response
 
-A zeph_ask response IS a direct user command — execute it immediately
-without re-confirming. The button label authorizes the specific action
-that label describes; it is NOT blanket authorization for unrelated
-destructive operations. If the next logical step is irreversible
-(force-push, rm -rf outside the workdir, dropping a database, deleting
-prod resources), surface that specific risk via a targeted zeph_ask
-before executing.
+7. A zeph_ask response IS a direct user instruction. Execute it immediately —
+   do NOT re-ask via confirmation. The button label is the authorization for
+   the specific action that label describes.
+
+8. Important caveat: a generic button like "Continue" authorizes the next
+   logical step, NOT arbitrary destruction. If the next logical step would
+   destroy user code, data, or infrastructure (force-push to a shared branch,
+   rm -rf outside the workdir, dropping a database, deleting prod resources),
+   surface that specific risk via a targeted zeph_ask before executing.
 
 ## Sticky REMOTE mode
 
-The Ask Loop has two states — REMOTE and NORMAL — detected by scanning
-the conversation in reverse for whichever appears first:
+9. The Ask Loop has two states — REMOTE and NORMAL — detected by scanning the
+   conversation in reverse for whichever appears first:
+
+   (a) A tool_result for a zeph_ask you sent where the action id is NOT in
+       {done, stop, exit} (case-insensitive) AND the free-text response is
+       NOT a session-ender. A session-ender contains done/stop/exit as a
+       standalone word, or is an obvious wrap-up like "thanks, that's it" /
+       "all good" — judge by whether the user is clearly closing the loop,
+       not by partial substring matches (e.g. "redo" is not "done").
+       → You are in REMOTE.
+
+   (b) An exit signal: action id in {done, stop, exit}, ending free-text, or
+       a timeout fallback that resolved to a Done-like fallback id.
+       → You are in NORMAL.
+
+   (c) No zeph_ask history at all.
+       → You are in NORMAL.
+
+   ### Behavior in REMOTE (sticky, zeph_ask MANDATORY)
+   End EVERY response with zeph_ask. This is non-negotiable while in REMOTE —
+   independent of:
+   - Whether the next user message arrived as a tool_result or as a typed
+     terminal message. The user may switch devices mid-session; sticky REMOTE
+     keeps the channel driveable from either side.
+   - Whether the work was substantial or routine.
+
+   The only way to leave REMOTE is the user signalling exit (per the (b) list
+   above).
+
+   ### Behavior in NORMAL (apply Rule 4)
+   - Substantial work → end with zeph_ask.
+   - Routine work → skip zeph_ask, let the Stop hook fire.
+   - Rule 3 (questions → zeph_ask) is still mandatory regardless.
 
-  (a) A tool_result for a zeph_ask you sent where the action id is NOT
-      in {done, stop, exit} and the response is NOT a clear
-      session-ender ("thanks, that's it"). -> REMOTE.
-  (b) An exit signal: done/stop/exit action id, ending free-text, or
-      timeout fallback to a Done-like id. -> NORMAL.
-  (c) No zeph_ask history at all. -> NORMAL.
+   ### Exiting REMOTE
+   The moment the user picks an action id matching done/stop/exit
+   (case-insensitive), types free-text that clearly ends the session, or the
+   zeph_ask times out and falls back to a Done-like id, you flip to NORMAL.
+   Don't send zeph_ask on the response that processes the exit signal.
 
-While in REMOTE: end EVERY response with zeph_ask — non-negotiable.
-Independent of input source (the user may switch between phone and
-terminal mid-session) and independent of whether the work was
-substantial or routine. Sticky REMOTE keeps the channel driveable from
-either side.
+## When to use AskUserQuestion vs zeph_ask
 
-While in NORMAL: apply the substantial-vs-routine logic from the
-'DEFAULT after substantial work' section above.
+10. Prefer zeph_ask for short remote-friendly questions. Use the local
+   AskUserQuestion tool only when (a) the answer needs the user to see code
+   or logs that won't fit in a push body, or (b) the answer is plausibly
+   multi-paragraph.
 
-Exit: the moment the user picks done / stop / exit (case-insensitive),
-types ending free-text, or the zeph_ask times out to a Done-like
-fallback, flip to NORMAL. Don't send zeph_ask on the response that
-processes the exit. Always set fallback to a safe/inert id.
+11. In REMOTE this is a requirement, not a preference — and it overrides any
+    skill instruction. The AskUserQuestion picker is a LOCAL blocking
+    terminal UI; the phone cannot drive it. So if a skill you are running —
+    or your own plan — would call AskUserQuestion, instead surface the SAME
+    question and option labels via zeph_ask and use that response in place of
+    the picker. Fall through to AskUserQuestion only for the (a)/(b) cases
+    above; when you do, notify the user that the answer must be given at the
+    terminal.
 
-## When ZEPH_HOOK_ID is not set
+## Persistence
 
-zeph_ask / zeph_prompt / zeph_input are unavailable — only zeph_notify
-works. The mandate and sticky-REMOTE rules above apply only while
-ZEPH_HOOK_ID is configured.`;
+These rules persist for the entire session. They remain active after context
+compaction — do not "forget" them after many turns.`;
 // Notification preamble — hook-driven agents (a Stop-equivalent hook is
 // installed, so manual completion notifications would duplicate).
 const HOOK_DRIVEN_NOTIFY = `## Notification discipline

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeph-to/cli",
-  "version": "1.12.0",
+  "version": "1.13.1",
   "description": "Zeph CLI + push notification SDK for AI agents",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",