@zeph-to/cli 2.15.0 → 2.17.0

package/dist/remote-agents.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.matchAgentByPaneCommand = exports.findAgentBySubcommand = exports.REMOTE_AGENTS = exports.detectCodexSessionName = exports.newestVersionedDb = exports.detectHermesSessionName = exports.sqliteJson = exports.pickRowByProcStart = exports.detectClaudeSessionNameByPid = exports.detectClaudeSessionIdByPid = exports.detectClaudeSessionByPid = exports.collectDescendantPids = exports.psStartTimes = exports.parseProcTable = exports.detectClaudeSessionId = void 0;
+exports.matchAgentByPaneCommand = exports.findAgentBySubcommand = exports.REMOTE_AGENTS = exports.detectCodexSessionName = exports.newestVersionedDb = exports.detectHermesSessionName = exports.sqliteJson = exports.pickRowByProcStart = exports.claudeTranscriptPath = exports.detectClaudeSessionNameByPid = exports.detectClaudeSessionIdByPid = exports.detectClaudeSessionByPid = exports.pidSessionRecordsExist = exports.collectDescendantPids = exports.psStartTimes = exports.parseProcTable = exports.detectClaudeSessionId = void 0;
 /**
  * Remote-control agent registry — the single table behind every
  * `zeph <agent>` subcommand, the listener's pane matching, and the
@@ -248,6 +248,16 @@ const collectDescendantPids = (rootPid) => {
     return descendantCache.set(rootPid, walkDescendants(rootPid, children));
 };
 exports.collectDescendantPids = collectDescendantPids;
+/**
+ * Whether this machine's Claude Code writes `~/.claude/sessions` records at all.
+ *
+ * The difference between "no records anywhere" (an older CC — the mtime
+ * heuristic is the only option) and "records exist, none match this pane" (the
+ * pane is not a Claude session) is the difference between a useful fallback and
+ * a wrong answer, so callers that care ask it explicitly.
+ */
+const pidSessionRecordsExist = () => cachedPidSessionRecords().length > 0;
+exports.pidSessionRecordsExist = pidSessionRecordsExist;
 /**
  * Exact resolution: the session record whose pid lives in the pane's
  * process tree AND whose cwd matches (guards against OS pid reuse
@@ -276,6 +286,54 @@ exports.detectClaudeSessionIdByPid = detectClaudeSessionIdByPid;
  */
 const detectClaudeSessionNameByPid = (panePid, paneCwd, deps = {}) => nonBlank((0, exports.detectClaudeSessionByPid)(panePid, paneCwd, deps)?.name);
 exports.detectClaudeSessionNameByPid = detectClaudeSessionNameByPid;
+/**
+ * The transcript file for the Claude Code session running in a tmux pane.
+ *
+ * Pid first, cwd only as a fallback, and the order is the whole point: the cwd
+ * heuristic picks the newest `*.jsonl` in the directory, so a second `claude`
+ * started in the same repo steals the first one's transcript (the comment above
+ * `detectClaudeSessionIdByPid` records that failure). Live-timeline viewers are
+ * per tmux session, so two sessions in one directory must resolve to two files
+ * or each phone reads the other's work.
+ *
+ * Returns null when this pane is not running Claude Code at all — a Codex or
+ * Gemini pane has no transcript here, and that is an answer, not a failure.
+ */
+const claudeTranscriptPath = (paneCwd, panePid) => {
+    if (!paneCwd)
+        return null;
+    let sessionId = null;
+    if (panePid) {
+        sessionId = (0, exports.detectClaudeSessionIdByPid)(panePid, paneCwd);
+        // Records exist but this pane matched none: the pane is not running
+        // Claude Code, or its record has not landed yet. Falling through to the
+        // mtime heuristic here is what lets a *second* `claude` in the same
+        // directory hand this pane the other session's transcript — and a
+        // viewer reading another session's work is worse than one reading none.
+        // Only an installation that writes no records at all earns the fallback.
+        if (!sessionId && (0, exports.pidSessionRecordsExist)())
+            return null;
+    }
+    sessionId ??= (0, exports.detectClaudeSessionId)(paneCwd);
+    if (!sessionId)
+        return null;
+    // Claude Code flattens the cwd into one directory name by replacing every
+    // `/` AND `.` with `-`: `/Users/x/.claude-mem/y` becomes
+    // `-Users-x--claude-mem-y`. Encoding only the slashes yields a path that
+    // never exists, and the watcher would then poll a missing file forever
+    // without ever saying so.
+    const projectDir = (0, path_1.join)(CLAUDE_PROJECTS_DIR, paneCwd.replace(/[/.]/g, '-'));
+    const path = (0, path_1.join)(projectDir, `${sessionId}.jsonl`);
+    // Prove it before handing it out. The pid path never touches the filesystem,
+    // so without this a mis-encoded directory reads as a healthy silent session.
+    try {
+        return (0, fs_1.statSync)(path).isFile() ? path : null;
+    }
+    catch {
+        return null;
+    }
+};
+exports.claudeTranscriptPath = claudeTranscriptPath;
 // ── Agents whose session store keeps no pid ──────────────────────
 //
 // Hermes and Codex both record a session per cwd with a creation timestamp and
@@ -437,6 +495,7 @@ const REMOTE_AGENT_TABLE = [
         resolveSessionId: (paneCwd, panePid) => (panePid !== undefined ? (0, exports.detectClaudeSessionIdByPid)(panePid, paneCwd) : null)
             ?? (0, exports.detectClaudeSessionId)(paneCwd),
         resolveSessionName: (paneCwd, panePid) => panePid !== undefined ? (0, exports.detectClaudeSessionNameByPid)(panePid, paneCwd) : null,
+        resolveTranscript: (paneCwd, panePid) => (0, exports.claudeTranscriptPath)(paneCwd, panePid),
     },
     {
         kind: 'codex',

package/dist/session-registry.d.ts

@@ -66,7 +66,14 @@ export declare const rememberSessions: (live: Array<{
  * running, so nothing re-adds an entry for a session that has ended. Running
  * that name again is what brings it back, which is also the only way back.
  */
-export declare const forgetSession: (name: string) => boolean;
+export type ForgetOutcome = 
+/** This machine never had a record under that name. */
+'unknown'
+/** Registry entry and chat scrollback both gone. */
+ | 'forgotten'
+/** Registry entry gone, but the scrollback file would not delete. */
+ | 'scrollback_kept';
+export declare const forgetSession: (name: string) => ForgetOutcome;
 /** Whether the registry knows this name — the resume whitelist check. */
 export declare const isKnownSession: (name: string, now?: number) => boolean;
 /** Test seam: the file this module reads and writes. */

package/dist/session-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-registry.d.ts","sourceRoot":"","sources":["../src/session-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,MAAM,WAAW,YAAY;IACzB,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,GAAG,EAAE,MAAM,CAAC;IACZ,gFAAgF;IAChF,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,MAAM,CAAC;AACtC;2DAC2D;AAC3D,eAAO,MAAM,oBAAoB,QAA2B,CAAC;AAsC7D,0EAA0E;AAC1E,eAAO,MAAM,aAAa,GAAI,MAAK,MAAmB,KAAG,YAAY,EAGJ,CAAC;AAElE,6EAA6E;AAC7E,eAAO,MAAM,aAAa,GAAI,MAAM,MAAM,EAAE,MAAK,MAAmB,KAAG,YAAY,GAAG,IAC3B,CAAC;AAE5D;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,GACzB,MAAM,KAAK,CAAC;IACR,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB,CAAC,EACF,MAAK,MAAmB,KACzB,IAmBF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,MAAM,KAAG,OAM5C,CAAC;AAEF,yEAAyE;AACzE,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,EAAE,MAAK,MAAmB,KAAG,OACnC,CAAC;AAEtC,wDAAwD;AACxD,eAAO,MAAM,iBAAiB,QA9GL,MA8GoB,CAAC;AAE9C,0EAA0E;AAC1E,eAAO,MAAM,sBAAsB,GAAI,OAAO,YAAY,KAAG,OAAgC,CAAC"}
+{"version":3,"file":"session-registry.d.ts","sourceRoot":"","sources":["../src/session-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAOH,MAAM,WAAW,YAAY;IACzB,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,GAAG,EAAE,MAAM,CAAC;IACZ,gFAAgF;IAChF,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,MAAM,CAAC;AACtC;2DAC2D;AAC3D,eAAO,MAAM,oBAAoB,QAA2B,CAAC;AAsC7D,0EAA0E;AAC1E,eAAO,MAAM,aAAa,GAAI,MAAK,MAAmB,KAAG,YAAY,EAGJ,CAAC;AAElE,6EAA6E;AAC7E,eAAO,MAAM,aAAa,GAAI,MAAM,MAAM,EAAE,MAAK,MAAmB,KAAG,YAAY,GAAG,IAC3B,CAAC;AAE5D;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,GACzB,MAAM,KAAK,CAAC;IACR,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB,CAAC,EACF,MAAK,MAAmB,KACzB,IAmBF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,aAAa;AACrB,uDAAuD;AACrD,SAAS;AACX,oDAAoD;GAClD,WAAW;AACb,qEAAqE;GACnE,iBAAiB,CAAC;AAExB,eAAO,MAAM,aAAa,GAAI,MAAM,MAAM,KAAG,aAU5C,CAAC;AAEF,yEAAyE;AACzE,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,EAAE,MAAK,MAAmB,KAAG,OACnC,CAAC;AAEtC,wDAAwD;AACxD,eAAO,MAAM,iBAAiB,QA1HL,MA0HoB,CAAC;AAE9C,0EAA0E;AAC1E,eAAO,MAAM,sBAAsB,GAAI,OAAO,YAAY,KAAG,OAAgC,CAAC"}

package/dist/session-registry.js

@@ -17,6 +17,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.sessionDirectoryExists = exports.knownSessionsPath = exports.isKnownSession = exports.forgetSession = exports.rememberSessions = exports.recallSession = exports.knownSessions = exports.KNOWN_SESSION_TTL_MS = exports.MAX_KNOWN_SESSIONS = void 0;
 const fs_1 = require("fs");
 const path_1 = require("path");
+const turn_ring_js_1 = require("./turn-ring.js");
 const gate_js_1 = require("./gate.js");
 /**
  * Ceiling on remembered sessions. tmux names come from a small reused pool
@@ -100,25 +101,17 @@ const rememberSessions = (live, now = Date.now()) => {
     writeAll(entries);
 };
 exports.rememberSessions = rememberSessions;
-/**
- * Forget one session, by name. Returns false when this machine never knew it.
- *
- * This is what deleting a past session means on the machine that ran it: the
- * entry leaves the file, so the phone stops being offered the session AND —
- * since this file is the resume whitelist — stops being able to start it.
- * That is the intended pair, not a side effect.
- *
- * It stays forgotten: `rememberSessions` only writes down sessions that are
- * running, so nothing re-adds an entry for a session that has ended. Running
- * that name again is what brings it back, which is also the only way back.
- */
 const forgetSession = (name) => {
     const entries = readAll();
     const kept = entries.filter((e) => e.name !== name);
     if (kept.length === entries.length)
-        return false;
+        return 'unknown';
     writeAll(kept);
-    return true;
+    // The chat's scrollback for that session goes with it. Forgetting a session
+    // everywhere except the one file that holds a week of its prompts and tool
+    // targets is not forgetting it — and a failure to delete that file has to
+    // reach the person who asked, not stay in a swallowed catch.
+    return (0, turn_ring_js_1.removeTurnRing)(name) ? 'forgotten' : 'scrollback_kept';
 };
 exports.forgetSession = forgetSession;
 /** Whether the registry knows this name — the resume whitelist check. */

package/dist/templates.d.ts

@@ -1,3 +1,5 @@
+/** Grace before the pi extension turns an unanswered prompt into a push. Exported for the tests. */
+export declare const PI_PROMPT_GRACE_MS = 10000;
 /** Cursor — written to ~/.cursor/rules/zeph.mdc (needs .mdc frontmatter). No prompt hook. */
 export declare const CURSOR_RULE: string;
 /** Windsurf — appended into ~/.codeium/windsurf/memories/global_rules.md. No prompt hook. */
@@ -12,7 +14,7 @@ export declare const COPILOT_RULE: string;
 export declare const CLINE_RULE: string;
 /** Aider — standalone conventions file via .aider.conf.yml `read:` (no Stop hook, no prompt hook). */
 export declare const AIDER_RULE: string;
-/** Pi — managed block in ~/.pi/agent/AGENTS.md. Extension = Stop-equivalent + prompt hook (PI_EXTENSION). */
+/** Pi — managed block in ~/.pi/agent/AGENTS.md. Extension = Stop-equivalent + prompt hook + waiting-on-you push (PI_EXTENSION). */
 export declare const PI_RULE: string;
 /** OpenCode — managed block in ~/.config/opencode/AGENTS.md. Stop hook via plugin, no prompt hook (v1). */
 export declare const OPENCODE_RULE: string;

package/dist/templates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../src/templates.ts"],"names":[],"mappings":"AA4KA,6FAA6F;AAC7F,eAAO,MAAM,WAAW,QAKtB,CAAC;AAEH,6FAA6F;AAC7F,eAAO,MAAM,aAAa,QAIxB,CAAC;AAEH,0FAA0F;AAC1F,eAAO,MAAM,WAAW,QAAyE,CAAC;AAElG,uFAAuF;AACvF,eAAO,MAAM,UAAU,QAAyE,CAAC;AAEjG,oGAAoG;AACpG,eAAO,MAAM,YAAY,QAIvB,CAAC;AAEH,gFAAgF;AAChF,eAAO,MAAM,UAAU,QAIrB,CAAC;AAEH,sGAAsG;AACtG,eAAO,MAAM,UAAU,QAIrB,CAAC;AAEH,6GAA6G;AAC7G,eAAO,MAAM,OAAO,QAIlB,CAAC;AAEH,2GAA2G;AAC3G,eAAO,MAAM,aAAa,QAIxB,CAAC;AAIH,eAAO,MAAM,YAAY,QAKd,CAAC;AAEZ,eAAO,MAAM,cAAc,QAOhB,CAAC;AAEZ,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;CAuBxB,CAAC;AAYF,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;CASvB,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,OAAO,KAAG,OAUhD,CAAC;AAEF,eAAO,MAAM,aAAa,QASf,CAAC;AAQZ,2FAA2F;AAC3F,eAAO,MAAM,YAAY,QAsDxB,CAAC;AAEF,kGAAkG;AAClG,eAAO,MAAM,eAAe,QAwG3B,CAAC;AASF,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":"AA+FA,oGAAoG;AACpG,eAAO,MAAM,kBAAkB,QAAS,CAAC;AAoHzC,6FAA6F;AAC7F,eAAO,MAAM,WAAW,QAKtB,CAAC;AAEH,6FAA6F;AAC7F,eAAO,MAAM,aAAa,QAIxB,CAAC;AAEH,0FAA0F;AAC1F,eAAO,MAAM,WAAW,QAAyE,CAAC;AAElG,uFAAuF;AACvF,eAAO,MAAM,UAAU,QAAyE,CAAC;AAEjG,oGAAoG;AACpG,eAAO,MAAM,YAAY,QAIvB,CAAC;AAEH,gFAAgF;AAChF,eAAO,MAAM,UAAU,QAIrB,CAAC;AAEH,sGAAsG;AACtG,eAAO,MAAM,UAAU,QAIrB,CAAC;AAEH,mIAAmI;AACnI,eAAO,MAAM,OAAO,QAKlB,CAAC;AAEH,2GAA2G;AAC3G,eAAO,MAAM,aAAa,QAIxB,CAAC;AAIH,eAAO,MAAM,YAAY,QAKd,CAAC;AAEZ,eAAO,MAAM,cAAc,QAOhB,CAAC;AAEZ,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;CAuBxB,CAAC;AAYF,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;CASvB,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,OAAO,KAAG,OAUhD,CAAC;AAEF,eAAO,MAAM,aAAa,QASf,CAAC;AAQZ,2FAA2F;AAC3F,eAAO,MAAM,YAAY,QAgJxB,CAAC;AAEF,kGAAkG;AAClG,eAAO,MAAM,eAAe,QAwG3B,CAAC;AASF,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,7 +26,7 @@
 // Keeping this in one place means a rule change lands everywhere at once
 // and the agents can't drift apart.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.removeManagedBlock = exports.upsertManagedBlock = exports.ZEPH_MARK_END = exports.ZEPH_MARK_START = exports.OPENCODE_PLUGIN = exports.PI_EXTENSION = exports.COPILOT_HOOKS = exports.isZephHookGroup = exports.CODEX_HOOKS = exports.GEMINI_HOOKS = exports.WINDSURF_HOOKS = exports.CURSOR_HOOKS = exports.OPENCODE_RULE = exports.PI_RULE = exports.AIDER_RULE = exports.CLINE_RULE = exports.COPILOT_RULE = exports.CODEX_RULE = exports.GEMINI_RULE = exports.WINDSURF_RULE = exports.CURSOR_RULE = void 0;
+exports.removeManagedBlock = exports.upsertManagedBlock = exports.ZEPH_MARK_END = exports.ZEPH_MARK_START = exports.OPENCODE_PLUGIN = exports.PI_EXTENSION = exports.COPILOT_HOOKS = exports.isZephHookGroup = exports.CODEX_HOOKS = exports.GEMINI_HOOKS = exports.WINDSURF_HOOKS = exports.CURSOR_HOOKS = exports.OPENCODE_RULE = exports.PI_RULE = exports.AIDER_RULE = exports.CLINE_RULE = exports.COPILOT_RULE = exports.CODEX_RULE = exports.GEMINI_RULE = exports.WINDSURF_RULE = exports.CURSOR_RULE = exports.PI_PROMPT_GRACE_MS = void 0;
 const gate_js_1 = require("./gate.js");
 const zeph_core_generated_js_1 = require("./zeph-core.generated.js");
 // Graceful resolution: prefer the installed `zeph` CLI, but fall back to
@@ -43,8 +43,9 @@ const zeph_core_generated_js_1 = require("./zeph-core.generated.js");
 // `--pushmode-default normal` is what keeps the first half of that true. The
 // built-in default for a project with no dial is quiet, and quiet only lets a
 // `high` Push Signal marker through — a marker these hooks have no way to
-// emit. Without the flag they would install and then never push again. The
-// user's own dial still outranks it, so /zeph-quiet keeps working here.
+// emit — or a turn the user was away for (presence.ts). Without the flag they
+// would install and then stay silent whenever the user is at the terminal.
+// The user's own dial still outranks it, so /zeph-quiet keeps working here.
 //
 // Older installed `zeph` versions parse both flags as unknown booleans and
 // ignore them — graceful backward compatibility, and for `--pushmode-default`
@@ -72,6 +73,19 @@ const TURN_FACT_FLAGS = ` --${gate_js_1.TOOL_COUNT_FLAG} \${tools} --${gate_js_1
 // stderr is discarded; `|| true` keeps a broken install from ever blocking
 // a prompt.
 const remoteHookCmd = (agent) => `$(command -v zeph || echo "npx -y @zeph-to/cli") remote-hook ${agent} 2>/dev/null || true`;
+// One-off `high` push from the pi extension — a prompt left waiting (the twin
+// of the plugin's zeph-ask.sh) or a turn that died on an error. `high` gets
+// through the quiet dial, and plain `notify` (no --auto) means only a mute
+// stops it. Title and body arrive as env vars, never spliced into the string:
+// the body can carry the model's own bash command or a provider error.
+const highNotifyCmd = '$(command -v zeph || echo "npx -y @zeph-to/cli") notify'
+    + ' --title "$ZEPH_PUSH_TITLE" --body "$ZEPH_PUSH_BODY" --priority high 2>/dev/null || true';
+// The pi turn's Push Signal marker, as a JS template placeholder (single quotes:
+// `${marker}` must reach the artifact unexpanded). The artifact only ever
+// assigns it a word the marker regex captured, or "none".
+const PUSH_SIGNAL_FLAG = ' --marker ${marker}';
+/** Grace before the pi extension turns an unanswered prompt into a push. Exported for the tests. */
+exports.PI_PROMPT_GRACE_MS = 10_000;
 // ── Shared behavioral core ───────────────────────────────────────
 //
 // GENERATED from plugin/docs/CORE_RULES.md — see src/zeph-core.generated.ts
@@ -136,10 +150,31 @@ tool instead — same semantics:
   unreachable) is a Done-like outcome — treat it as NORMAL.
 - zeph_notify → \`zeph notify --title "…" --body "…" [--priority high]\`
 - AskUserQuestion → pi's own terminal prompt.`;
+// Push Signal preamble — pi only. The shared core has no Push Signal section:
+// Claude Code gets it from the plugin's SessionStart hook, per push dial. The
+// pi extension reads the same markers (PI_EXTENSION, message_end), so pi's
+// rules carry a dial-independent version here.
+const PI_PUSH_SIGNAL = `## Push Signal — steer the end-of-turn push
+
+When a turn ends, the zeph extension decides whether to push by tool volume
+and the user's push dial. Put ONE marker anywhere in your final response to
+override that for this turn. The extension removes it before the message is
+shown or kept:
+
+- \`<!-- zeph: high -->\` — push at high priority. The only marker that gets
+  through the quiet dial, so use it whenever the user must act: you ended the
+  turn with a question for them, or you are blocked on a decision only they
+  can make. Never on routine completions.
+- \`<!-- zeph: push -->\` — push a turn the heuristic would skip.
+- \`<!-- zeph: skip -->\` — no push for a turn not worth a ping.
+
+No marker → the heuristic: fewer than 2 tool calls, or only read-only ones,
+stays silent. Markers are lowercase and exact.`;
 /** Assemble a full rule document from optional frontmatter + preambles + core. */
 const buildRule = (opts) => {
     const fm = opts.frontmatter ? `${opts.frontmatter}\n\n` : '';
     const tools = opts.toolAccess ? `${opts.toolAccess}\n\n` : '';
+    const signal = opts.pushSignal ? `${opts.pushSignal}\n\n` : '';
     const entry = opts.remoteEntry ? `${opts.remoteEntry}\n\n` : '';
     return `${fm}# Zeph — Remote-Control Rules
 
@@ -149,7 +184,7 @@ the user.
 
 ${opts.notify}
 
-${tools}${entry}${opts.core}
+${tools}${signal}${entry}${opts.core}
 `;
 };
 // ── Per-agent rule documents ─────────────────────────────────────
@@ -192,10 +227,11 @@ exports.AIDER_RULE = buildRule({
     remoteEntry: REMOTE_ENTRY_NO_HOOK,
     core: zeph_core_generated_js_1.ZEPH_CORE_RULE_ONLY,
 });
-/** Pi — managed block in ~/.pi/agent/AGENTS.md. Extension = Stop-equivalent + prompt hook (PI_EXTENSION). */
+/** Pi — managed block in ~/.pi/agent/AGENTS.md. Extension = Stop-equivalent + prompt hook + waiting-on-you push (PI_EXTENSION). */
 exports.PI_RULE = buildRule({
     notify: HOOK_DRIVEN_NOTIFY,
     toolAccess: PI_TOOL_ACCESS,
+    pushSignal: PI_PUSH_SIGNAL,
     core: zeph_core_generated_js_1.ZEPH_CORE_HOOK_DRIVEN,
 });
 /** OpenCode — managed block in ~/.config/opencode/AGENTS.md. Stop hook via plugin, no prompt hook (v1). */
@@ -319,20 +355,108 @@ const sh = (cmd: string, cwd: string, stdin?: string): Promise<string> =>
 // an unknown tool errs toward pushing rather than toward silence.
 const READ_ONLY = new Set(["read", "grep", "find", "ls"]);
 
+// How long a blocking prompt may stay open before it becomes a push. An answer
+// inside the window means the user is at the terminal, and a guard extension
+// can raise several prompts a turn — pushing each one at once would be noise.
+const PROMPT_GRACE_MS = ${exports.PI_PROMPT_GRACE_MS};
+
+// Push Signal markers — the pattern the Claude Code Stop hook reads
+// (plugin/hooks/zeph-stop.sh MARKER_RE). pi's markdown renders an HTML comment
+// as plain text, so message_end also strips it from what the user sees.
+const MARKER_RE = /<!--[ \\t]*zeph:[ \\t]*(skip|push|high)[ \\t]*-->/g;
+
+const projectOf = (cwd: string): string => cwd.split("/").pop() || cwd;
+
+// Fire-and-forget: never block pi on the notify network call.
+const pushHigh = (cwd: string, title: string, body: string): void => {
+  const env = {
+    ...process.env,
+    ZEPH_PUSH_TITLE: title,
+    ZEPH_PUSH_BODY: body.length > 200 ? body.slice(0, 199) + "…" : body,
+  };
+  const child = spawn("sh", ["-c", ${JSON.stringify(highNotifyCmd)}], { cwd, env, stdio: "ignore", detached: true });
+  child.on("error", () => {});
+  child.unref();
+};
+
 export default function (pi: ExtensionAPI) {
   // Turn facts for the push gate. One agent per process, so plain counters
   // suffice — no session keying.
   let tools = 0;
   let nonReadonly = 0;
+  // The tool call in flight. tool_execution_start fires before pi runs the
+  // tool_call handlers, so a guard's prompt always finds its own call here.
+  let running: { toolName: string; args: any } | undefined;
+  let promptTimer: ReturnType<typeof setTimeout> | undefined;
+  // A prompt only counts inside a turn. Outside one it is a dialog the user
+  // opened at the terminal themselves (/caveman config, a settings picker).
+  let agentRunning = false;
+  // This turn's Push Signal, and why its last assistant message stopped.
+  let marker = "none";
+  let stop: { reason: string; error?: string } | undefined;
 
+  pi.on("agent_start", () => {
+    agentRunning = true;
+  });
+  pi.on("message_end", (event) => {
+    const message = event.message;
+    if (message.role !== "assistant") return;
+    stop = { reason: message.stopReason, error: message.errorMessage };
+    let found = false;
+    const content = message.content.map((part) => {
+      if (part.type !== "text") return part;
+      const text = part.text.replace(MARKER_RE, (_match: string, word: string) => {
+        marker = word;
+        found = true;
+        return "";
+      });
+      return text === part.text ? part : { ...part, text: text.trimEnd() };
+    });
+    if (found) return { message: { ...message, content } };
+  });
+  pi.on("tool_execution_start", (event) => {
+    running = event;
+  });
   pi.on("tool_execution_end", (event) => {
+    running = undefined;
     tools += 1;
     if (!READ_ONLY.has(event.toolName)) nonReadonly += 1;
   });
+  // Waiting-on-you: pi fires ui_prompt_start for every blocking extension
+  // dialog (select/confirm/input/editor/custom — bash guards, ask-user tools).
+  // A custom dialog carries no title, so name the call that raised it instead.
+  pi.on("ui_prompt_start", (event, ctx) => {
+    clearTimeout(promptTimer);
+    if (!agentRunning) return;
+    const command = running?.toolName === "bash" ? running.args?.command : undefined;
+    const body = event.title
+      ?? (typeof command === "string" ? "$ " + command : undefined)
+      ?? (running ? running.toolName + " is waiting for your answer" : "Waiting for your input");
+    promptTimer = setTimeout(() => {
+      promptTimer = undefined;
+      pushHigh(ctx.cwd, "pi asks: " + projectOf(ctx.cwd), body);
+    }, PROMPT_GRACE_MS);
+    promptTimer.unref?.();
+  });
+  pi.on("ui_prompt_end", () => {
+    clearTimeout(promptTimer);
+    promptTimer = undefined;
+  });
   // Stop-equivalent: agent_settled fires once per user turn, after retries/compaction.
   // Fire-and-forget: never block pi's turn-end on the notify network call.
   pi.on("agent_settled", (_event, ctx) => {
-    const child = spawn("sh", ["-c", ${notifyCmdLiteral(TURN_FACT_FLAGS)}], { cwd: ctx.cwd, stdio: "ignore", detached: true });
+    agentRunning = false;
+    clearTimeout(promptTimer);
+    promptTimer = undefined;
+    // Esc (at the terminal, or a key sent from the phone): whoever stopped the
+    // turn is already looking at it.
+    if (stop?.reason === "aborted") return;
+    // A turn that died on a provider error is a blocker, not a completion.
+    if (stop?.reason === "error") {
+      pushHigh(ctx.cwd, "pi stopped: " + projectOf(ctx.cwd), stop.error || "The model request failed");
+      return;
+    }
+    const child = spawn("sh", ["-c", ${notifyCmdLiteral(TURN_FACT_FLAGS + PUSH_SIGNAL_FLAG)}], { cwd: ctx.cwd, stdio: "ignore", detached: true });
     child.on("error", () => {});
     child.unref();
   });
@@ -342,6 +466,8 @@ export default function (pi: ExtensionAPI) {
   pi.on("before_agent_start", async (event, ctx) => {
     tools = 0;
     nonReadonly = 0;
+    marker = "none";
+    stop = undefined;
     const out = await sh(${JSON.stringify(remoteHookCmd('pi'))}, ctx.cwd,
       JSON.stringify({ prompt: event.prompt, cwd: ctx.cwd }));
     try {

package/dist/test-state-dir.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Point `stateDir()` at a throwaway directory for the length of one suite.
+ *
+ * Both files that keep state under `stateDir()` need this and both had rolled
+ * it by hand, restore-else-delete included. Modules that read the env at call
+ * time (`gate.ts`'s `stateDir`) can be imported normally; only ones that freeze
+ * a path at module scope need the dynamic-import dance.
+ */
+export declare const withTmpStateDir: (prefix: string) => (() => string);
+//# sourceMappingURL=test-state-dir.d.ts.map

package/dist/test-state-dir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-state-dir.d.ts","sourceRoot":"","sources":["../src/test-state-dir.ts"],"names":[],"mappings":"AAKA;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAAI,QAAQ,MAAM,KAAG,CAAC,MAAM,MAAM,CAa7D,CAAC"}

package/dist/test-state-dir.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withTmpStateDir = void 0;
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const vitest_1 = require("vitest");
+/**
+ * Point `stateDir()` at a throwaway directory for the length of one suite.
+ *
+ * Both files that keep state under `stateDir()` need this and both had rolled
+ * it by hand, restore-else-delete included. Modules that read the env at call
+ * time (`gate.ts`'s `stateDir`) can be imported normally; only ones that freeze
+ * a path at module scope need the dynamic-import dance.
+ */
+const withTmpStateDir = (prefix) => {
+    let dir = '';
+    const original = process.env.XDG_STATE_HOME;
+    (0, vitest_1.beforeEach)(() => {
+        dir = (0, fs_1.mkdtempSync)((0, path_1.join)((0, os_1.tmpdir)(), prefix));
+        process.env.XDG_STATE_HOME = dir;
+    });
+    (0, vitest_1.afterEach)(() => {
+        (0, fs_1.rmSync)(dir, { recursive: true, force: true });
+        if (original === undefined)
+            delete process.env.XDG_STATE_HOME;
+        else
+            process.env.XDG_STATE_HOME = original;
+    });
+    return () => dir;
+};
+exports.withTmpStateDir = withTmpStateDir;

package/dist/transcript-tail.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Claude Code session transcript (`~/.claude/projects/<hash>/<uuid>.jsonl`) →
+ * the small events the agent chat timeline draws.
+ *
+ * Two pure pieces, deliberately split: reading bytes off a growing file, and
+ * deciding what of it is worth putting on the wire. Neither touches the socket,
+ * so both are testable without tmux, WebSocket, or a clock.
+ *
+ * Everything here is sized by what a real transcript actually contains, measured
+ * 2026-09-08 over 1443 files in `~/.claude/projects`: the largest file was
+ * 75.9 MB (p90 1.1 MB) and the longest single line 915,292 bytes. Those two
+ * numbers are why the reader starts near the end and refuses oversized lines
+ * before parsing them — a tail that starts at byte 0, or that hands a ~1 MB
+ * string to `JSON.parse` and only then decides to drop it, has already paid the
+ * cost the cap exists to avoid.
+ */
+/**
+ * How far back from the end of the file the first read starts.
+ *
+ * Not zero: a fresh viewer that sees nothing until the *next* tool call is a
+ * blank screen for whoever just picked up their phone mid-turn. Not the whole
+ * file either — that is up to 75.9 MB. A fixed window from the end costs the
+ * same on an 8 KB transcript and a 76 MB one.
+ */
+export declare const TRANSCRIPT_BACKFILL_BYTES: number;
+/** Ceiling on one tick's read, so a burst of appends cannot be swallowed whole. */
+export declare const MAX_TAIL_BYTES_PER_TICK: number;
+/**
+ * A line longer than this is abandoned unparsed, the reader skipping to the next
+ * newline. The measured worst case is a 915 KB `tool_result`, whose body this
+ * module drops anyway — buffering one to completion would be paying megabytes to
+ * learn a tool id.
+ */
+export declare const MAX_TRANSCRIPT_LINE_CHARS: number;
+/**
+ * Ceiling on a tool's label — its name, and the short string saying what it
+ * acted on. A path or a one-line description; anything longer is a runaway
+ * input, not a label.
+ */
+export declare const MAX_EVENT_FIELD_CHARS = 512;
+/**
+ * Ceiling on prose — what the agent wrote, and what the person asked.
+ *
+ * Deliberately far above the label cap: 512 characters is a filename, and
+ * applying it here cut every reply off mid-sentence. 5000 is what the
+ * completion push already carries for the same text (`zeph-stop.sh`), so the
+ * live lane and the push that replaces it agree on how much of a reply is
+ * worth sending.
+ */
+export declare const MAX_EVENT_TEXT_CHARS = 5000;
+/**
+ * Where the reader is in one file.
+ *
+ * `size`/`mtimeMs` are the skip check: when neither moved there is nothing to
+ * read, and the tick returns without allocating. Since idle is this watcher's
+ * normal state, that check is what keeps it off the GC's back.
+ */
+export interface TailState {
+    readonly offset: number;
+    readonly size: number;
+    readonly mtimeMs: number;
+    /** Which file this offset belongs to. A new inode is a new file at the same path. */
+    readonly ino: number;
+    /** Bytes after the last newline seen — an incomplete line, held for the next tick. */
+    readonly carry: string;
+    /** Inside an oversized line: discard bytes until the next newline. */
+    readonly resyncing: boolean;
+}
+export interface TailRead {
+    /** Whole lines, in file order. Never includes a partial line. */
+    readonly lines: string[];
+    readonly state: TailState;
+    readonly bytesRead: number;
+    /** Lines abandoned for exceeding MAX_TRANSCRIPT_LINE_CHARS. */
+    readonly droppedLines: number;
+}
+/**
+ * No state yet. `null` rather than a sentinel-filled record: "never read this
+ * file" and "read it and got nothing" are different, and an out-of-band value
+ * that has to stay below every real offset is a trap for the next `>=`.
+ */
+export declare const initialTailState: () => TailState | null;
+/**
+ * Read what was appended since `prev`, or `null` when there is nothing to do —
+ * the file is unreadable, or neither its size nor its mtime moved.
+ *
+ * `null` is the common case (an idle session) and is deliberately allocation
+ * free: no buffer, no string, no array.
+ */
+export declare const readTranscriptDelta: (path: string, prev: TailState | null) => TailRead | null;
+/**
+ * What the timeline draws. Stateless by design: a `tool_result` arrives as its
+ * own event rather than mutating an earlier one, because the call it answers is
+ * routinely in a previous tick's batch — merging by `id` is the viewer's job,
+ * and it is the only side that holds the whole turn.
+ */
+/**
+ * `at` is the transcript entry's own timestamp, carried so the viewer can place
+ * a live turn among the pushes in time order instead of parking the whole live
+ * block below them — where a message sent while reading lands above the turn it
+ * answers.
+ */
+export type TurnEvent = {
+    at?: string;
+} & ({
+    kind: 'tool';
+    id: string;
+    name: string;
+    target?: string;
+} | {
+    kind: 'tool_result';
+    id: string;
+    ok: boolean;
+} | {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'prompt';
+    text: string;
+});
+/**
+ * Turn raw JSONL lines into wire events.
+ *
+ * Nothing a tool read or wrote survives this function: only the tool's name, a
+ * short label for what it acted on, and whether it worked. That is the whole
+ * privacy story of the feature — the transcript holds file contents and command
+ * output, and this is the one place that decides none of it leaves the machine.
+ *
+ * `sinceLastPrompt` is for the backfill window: finished turns already exist in
+ * the chat as their completion pushes, so replaying them would double every
+ * message. Only the turn still in flight is new information.
+ *
+ * The prompt a person typed IS carried, unlike anything a tool read or wrote.
+ * It is their own words, it is the same class of content the completion push
+ * already sends, and without it the timeline is a list of tool names with no
+ * record of what was asked.
+ *
+ * Everything here — the block shapes, the entry types, `TARGET_KEYS` — is Claude
+ * Code's transcript format. Supporting another agent (pi, Codex) means a
+ * projector of its own alongside this one, reached the way `REMOTE_AGENTS`
+ * already reaches per-agent session resolvers; `turn-watch` takes the reader as
+ * a dependency and needs no change for it.
+ */
+export declare const projectTranscriptEntries: (lines: readonly string[], opts?: {
+    sinceLastPrompt?: boolean;
+}) => TurnEvent[];
+//# sourceMappingURL=transcript-tail.d.ts.map

package/dist/transcript-tail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcript-tail.d.ts","sourceRoot":"","sources":["../src/transcript-tail.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,QAAa,CAAC;AAEpD,mFAAmF;AACnF,eAAO,MAAM,uBAAuB,QAAa,CAAC;AAElD;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,QAAc,CAAC;AAErD;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAEzC;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qFAAqF;IACrF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,sFAAsF;IACtF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,sEAAsE;IACtE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,QAAQ;IACrB,iEAAiE;IACjE,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,+DAA+D;IAC/D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CACjC;AAoBD;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,QAAO,SAAS,GAAG,IAAY,CAAC;AAE7D;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,GAAI,MAAM,MAAM,EAAE,MAAM,SAAS,GAAG,IAAI,KAAG,QAAQ,GAAG,IAuHrF,CAAC;AAIF;;;;;GAKG;AACH;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG;IAAE,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,CACpC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC3D;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,OAAO,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CACrC,CAAC;AA4HF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,wBAAwB,GACjC,OAAO,SAAS,MAAM,EAAE,EACxB,OAAM;IAAE,eAAe,CAAC,EAAE,OAAO,CAAA;CAAO,KACzC,SAAS,EAwDX,CAAC"}