baychat 0.24.0 → 0.25.0

package/dist/relay/daemon.js

@@ -33,15 +33,23 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RelayDaemon = void 0;
+exports.FRESH_START_SETTLE_MS = exports.RelayDaemon = void 0;
 exports.splitSessionCommands = splitSessionCommands;
 const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
 const net = __importStar(require("net"));
 const path = __importStar(require("path"));
 const config_1 = require("../config");
+const context_report_1 = require("../context-report");
+const codex_context_1 = require("./codex-context");
 const session_commands_1 = require("./session-commands");
 const terminal_pane_1 = require("./terminal-pane");
+const compact_command_1 = require("./compact-command");
+const fresh_start_1 = require("./fresh-start");
+const project_brief_1 = require("./project-brief");
+const project_notes_1 = require("./project-notes");
+const context_notice_1 = require("./context-notice");
+const fresh_start_verify_1 = require("./fresh-start-verify");
 const commands_1 = require("./acp/commands");
 const daemon_glue_1 = require("./acp/daemon-glue");
 const runner_1 = require("./acp/runner");
@@ -73,6 +81,19 @@ class RelayDaemon {
     acpQueue = new turn_queue_1.AcpTurnQueue();
     acp;
     acpAlive;
+    /** How full each session's context is, as its runtime reports it (contract §7). */
+    context;
+    /** Reads each Codex session's own rollout for its context numbers. */
+    codexContext;
+    /** The room each session was last woken in — where its context numbers belong. */
+    lastRoom = new Map();
+    /** Project briefs whose own message was a session command, waiting for the next chat message. */
+    carriedBriefs = new project_brief_1.CarriedBriefs();
+    carriedNotes = new project_notes_1.CarriedNotes();
+    carriedNotices = new context_notice_1.CarriedNotices();
+    /** Fresh-start steps already handled, on disk: a replayed step never runs twice. */
+    handledHandoffs = new fresh_start_verify_1.HandledHandoffs();
+    freshStartOpts;
     acpKeepAlive;
     queue;
     abort = new AbortController();
@@ -206,10 +227,22 @@ class RelayDaemon {
             opts.resolveBinary ??
                 ((name) => (0, runtime_binary_1.resolveRuntimeBinary)(name, (0, runtime_binary_1.currentBinaryEnv)()));
         this.runTurn = opts.runTurn;
+        this.freshStartOpts = opts.freshStart ?? {};
         this.queue = new queue_1.SessionQueue((session, batch) => this.deliver(session, batch), (session, err) => {
             this.lastError = `delivery failed for ${session}: ${errText(err)}`;
             this.log(this.lastError);
         });
+        this.context = new context_report_1.ContextReporter({ auth: () => this.auth, log: (line) => this.log(line) });
+        this.codexContext = new codex_context_1.CodexContextTailer({
+            // Codex sessions this relay can name a thread for, and that the server still lists as live.
+            targets: () => this.registry
+                .all()
+                .filter((t) => t.runtime === "codex" && t.resumeId && (t.attached || this.liveSessions.includes(t.name)))
+                .map((t) => ({ session: t.name, threadId: t.resumeId })),
+            report: (session, event) => this.reportContext(session, event),
+            conversationFor: (session) => this.lastRoom.get(session),
+            log: (line) => this.log(line),
+        });
         this.acpAlive = (0, daemon_glue_1.acpKeepAliveScheduler)(() => (0, daemon_glue_1.keepAcpSessionsAlive)({ registry: this.registry, auth: this.auth, caller: opts.acpCaller, log: this.log }));
         this.acp = new runner_1.AcpSessionRunner({
             registry: this.registry,
@@ -225,6 +258,7 @@ class RelayDaemon {
             onPending: (session, batch, reason) => this.record({ kind: "pending", session, reason }, session, batch),
             runTurn: opts.acpRunTurn,
             caller: opts.acpCaller,
+            reportContext: (session, event) => this.reportContext(session, event),
         });
     }
     async start() {
@@ -250,6 +284,14 @@ class RelayDaemon {
         // handed what the previous one was holding rather than a clean slate.
         this.held.load();
         this.acpQueue.load();
+        // A clear that was being typed when the previous relay stopped: the session may well have been
+        // cleared, so it is reported cleared-but-not-pointed (the server re-arms it), never left to
+        // time out as "not cleared".
+        for (const { handoffId, session } of this.handledHandoffs.interrupted()) {
+            this.log(`fresh start ${handoffId} for ${session} was interrupted mid-clear — reporting it cleared`);
+            this.handledHandoffs.mark(handoffId, "clear", session, "done");
+            void (0, fresh_start_1.postHandoffReport)(auth, session, { handoffId, status: "fresh", reason: "FIRST_PROMPT_FAILED" }, (line) => this.log(line));
+        }
         const sockPath = (0, socket_1.socketPath)();
         if (await (0, socket_1.probeSocket)(sockPath)) {
             throw new Error(`a relay is already listening on ${sockPath} — run \`baychat relay status\``);
@@ -277,6 +319,7 @@ class RelayDaemon {
         writePidFile();
         // After the socket is ours: a relay refused as a duplicate must not keep sessions alive.
         this.acpKeepAlive = (0, daemon_glue_1.startAcpUpkeep)(this.acpAlive.run);
+        this.codexContext.start();
         this.log(`listening on ${sockPath} (pid ${process.pid}) as device "${device.user.name}"`);
         this.log(`${this.registry.all().length} known session target(s)`);
         // The event SOURCE is pluggable (socket preferred, long-poll floor); every
@@ -295,8 +338,11 @@ class RelayDaemon {
                 // never had to route an event to — skipping it re-baselines it at "now".
                 this.watermarks.noteLiveSessions(names);
                 const dropped = this.registry.pruneToLive(names);
-                for (const name of dropped)
+                for (const name of dropped) {
                     this.log(`session ended server-side, dropped: ${name}`);
+                    // A name reused later is a new session: nothing kept for the old one may reach it.
+                    this.forgetCarried(name);
+                }
                 void this.acpAlive.lapsed(this.registry, names);
                 if (registrations)
                     this.applyServerRegistrations(registrations, names);
@@ -388,7 +434,7 @@ class RelayDaemon {
      * apart from silence. A refusal that names its reason is the whole difference between
      * "this feature is broken" and "start your agent inside tmux".
      */
-    async runSessionCommand(session, message, command) {
+    async runSessionCommand(session, message, command, compact = {}) {
         const say = async (text) => {
             if (!this.auth)
                 return;
@@ -411,6 +457,13 @@ class RelayDaemon {
             await say((0, session_commands_1.sessionCommandHelp)());
             return;
         }
+        if (command.id === "compact") {
+            if (compact.refusal)
+                return say(compact.refusal);
+            if (target.acp) {
+                return say(`"${session}" is run by the relay and tidies its own memory; /compact cannot reach it. /new starts it fresh.`);
+            }
+        }
         // `/mode-*`, `/stop`, and what `/status` `/exit` `/clear` `/new` mean with no terminal.
         if (await (0, commands_1.runAcpSessionCommand)(this.acp, session, target, message, command, say))
             return;
@@ -448,7 +501,13 @@ class RelayDaemon {
             await say((0, session_commands_1.noTerminalReason)());
             return;
         }
-        const keys = command.keys?.(target.runtime);
+        let keys = command.keys?.(target.runtime);
+        if (command.id === "compact") {
+            const typed = (0, compact_command_1.compactKeys)(target.runtime, compact.focus);
+            if (!typed.ok)
+                return say(typed.reason);
+            keys = typed.keys;
+        }
         if (!keys) {
             await say(`${command.trigger} has nothing to type for a ${target.runtime} session.`);
             return;
@@ -467,8 +526,158 @@ class RelayDaemon {
             // See `SessionRegistry.clearResume`: the live session's transcript is gone, so the
             // recorded resume id now points at something no half of this session has.
             this.registry.clearResume(session);
+            // …and whatever was kept to show it (briefs, notes deltas, the notice) described that memory.
+            this.forgetCarried(session);
         }
-        await say(`Typed ${keys} into "${session}". Its context is cleared.`);
+        await say(command.id === "compact"
+            ? `Typed ${keys} into "${session}". It is tidying its context now.`
+            : `Typed ${keys} into "${session}". Its context is cleared.`);
+    }
+    /**
+     * One step of "Fresh start with a handoff" (fresh-start.ts).
+     *
+     * `note`: if this relay could clear the session afterwards, the request joins `chat` and wakes
+     * the session like any message; if it could not, the server hears why at once and the session
+     * is never asked. `clear` (sent only once the note is saved): wait until the session is idle,
+     * clear it the way `/clear` and `/new` do, point it at its note, see where that first prompt
+     * landed, and report (fresh-start-verify.ts). A session this machine does not know is left to
+     * the relay that does; a step already handled — a re-served event, a replay after a restart —
+     * is never run twice; a clear past its `expiresAt` is not started.
+     */
+    async runFreshStart(session, message, fresh, chat) {
+        const target = this.registry.get(session);
+        if (!target) {
+            this.log(`fresh start ${fresh.handoffId} for ${session}: not a session on this machine — left to its own relay`);
+            return;
+        }
+        if (this.handledHandoffs.has(fresh.handoffId, fresh.phase)) {
+            this.log(`fresh start ${fresh.handoffId} for ${session}: the ${fresh.phase} step was already handled — ignored`);
+            return;
+        }
+        const done = () => this.handledHandoffs.mark(fresh.handoffId, fresh.phase, session, "done");
+        const report = (outcome) => this.auth ? (0, fresh_start_1.postHandoffReport)(this.auth, session, outcome, (line) => this.log(line)) : Promise.resolve();
+        const plan = (0, fresh_start_1.freshStartPlan)(target);
+        if (plan.kind === "refuse") {
+            this.log(`fresh start ${fresh.handoffId} for ${session} refused: ${plan.reason}`);
+            done();
+            await report({ handoffId: fresh.handoffId, status: "failed", reason: plan.reason });
+            return;
+        }
+        if (fresh.phase === "note") {
+            done();
+            chat.push((0, fresh_start_1.noteRequestAsChat)(message, fresh.handoffId));
+            return;
+        }
+        if (fresh.expiresAt !== undefined && Date.now() > fresh.expiresAt) {
+            // The server has already given up on this step (CLEAR_TIMEOUT); clearing now would clear a
+            // session nobody is watching any more. Nothing is typed.
+            this.log(`fresh start ${fresh.handoffId} for ${session}: the clear step expired before it could start — not cleared`);
+            done();
+            return;
+        }
+        if (plan.kind === "acp") {
+            // No terminal: forget the ACP session and make the note its next prompt, alone; a turn
+            // running now is stopped and its messages wait behind the note (acp/runner.ts).
+            done();
+            this.forgetCarried(session);
+            this.acp.freshStart(session, (0, fresh_start_1.freshStartMessage)(message, fresh), fresh.handoffId);
+            this.log(`fresh start ${fresh.handoffId}: ${session} will start a new ACP session from its note`);
+            await report({ handoffId: fresh.handoffId, status: "fresh" });
+            return;
+        }
+        const pane = target.pane;
+        const opts = this.freshStartOpts;
+        // 1. Not in the middle of a turn: typed then, the clear is queued or refused and the pointer
+        //    lands in the old conversation.
+        const idle = await (0, fresh_start_verify_1.waitForIdle)({
+            sample: () => (opts.samplePane ?? fresh_start_verify_1.samplePane)(pane),
+            attached: () => {
+                const sock = this.attached.get(session);
+                return !!sock && !sock.destroyed;
+            },
+            capMs: opts.idleCapMs,
+            stepMs: opts.idleStepMs,
+        });
+        if (idle === "busy") {
+            this.log(`fresh start ${fresh.handoffId}: ${session} stayed busy — nothing typed; its note is kept`);
+            done();
+            await report({ handoffId: fresh.handoffId, status: "failed", reason: "CLEAR_FAILED" });
+            return;
+        }
+        // 2. Clear. Recorded as started first: a relay that dies from here on reports it on restart.
+        this.handledHandoffs.mark(fresh.handoffId, "clear", session, "started");
+        const typedAt = Date.now();
+        const cleared = await (0, terminal_pane_1.typeIntoPane)(pane, target.runtime, plan.clearKeys, { ownerPid: target.ownerPid });
+        if (!cleared.ok) {
+            this.log(`fresh start ${fresh.handoffId}: could not clear ${session} — ${cleared.reason}`);
+            done();
+            await report({ handoffId: fresh.handoffId, status: "failed", reason: "CLEAR_FAILED" });
+            return;
+        }
+        const oldResumeId = target.resumeId;
+        // Same as `/clear`: the recorded resume id names a transcript this session no longer has, and
+        // anything kept to show it described the old memory.
+        this.registry.clearResume(session);
+        this.forgetCarried(session);
+        // Let the runtime's TUI finish clearing before the first prompt is typed into it.
+        await new Promise((resolve) => setTimeout(resolve, opts.settleMs ?? exports.FRESH_START_SETTLE_MS));
+        const typed = await (0, terminal_pane_1.typeIntoPane)(pane, target.runtime, (0, fresh_start_1.freshStartLine)(fresh.note.id, session), { ownerPid: target.ownerPid });
+        if (!typed.ok) {
+            // Cleared, but not pointed at its note: still fresh (the server must re-arm it), said so.
+            this.log(`fresh start ${fresh.handoffId}: ${session} was cleared but its first prompt was not typed — ${typed.reason}`);
+            done();
+            await report({ handoffId: fresh.handoffId, status: "fresh", reason: "FIRST_PROMPT_FAILED" });
+            return;
+        }
+        // 3. Where did the first prompt land? Only the pointer line names this note.
+        const runtime = target.runtime === "codex" ? "codex" : "claude";
+        const landing = await (opts.awaitPointer ?? fresh_start_verify_1.awaitPointer)({
+            runtime,
+            noteId: fresh.note.id,
+            sinceMs: typedAt - 1_000,
+            ...(oldResumeId ? { oldResumeId } : {}),
+            discovery: this.discovery,
+            timeoutMs: opts.pointerTimeoutMs,
+        });
+        done();
+        if (landing?.kind === "old") {
+            this.log(`fresh start ${fresh.handoffId}: ${plan.clearKeys} did not take in ${session} — its first prompt went to the old conversation`);
+            if (oldResumeId)
+                this.registry.upsert({ name: session, runtime: target.runtime, resumeId: oldResumeId });
+            await report({ handoffId: fresh.handoffId, status: "failed", reason: "CLEAR_FAILED" });
+            return;
+        }
+        if (landing?.kind === "new") {
+            this.registry.upsert({
+                name: session,
+                runtime: target.runtime,
+                resumeId: landing.id,
+                resumeSource: "transcript",
+                resumeEvidence: `the fresh session BayChat pointed at note ${fresh.note.id}`,
+            });
+            this.log(`fresh start ${fresh.handoffId}: ${session} started fresh (${landing.id}) and was pointed at its note`);
+            await report({ handoffId: fresh.handoffId, status: "fresh" });
+            return;
+        }
+        this.log(`fresh start ${fresh.handoffId}: typed ${plan.clearKeys} into ${session}, but could not see the fresh session start`);
+        await report({ handoffId: fresh.handoffId, status: "fresh", reason: "UNVERIFIED" });
+    }
+    /** The session's own context report — and what a new context means for what the relay keeps. */
+    reportContext(session, event) {
+        if (event.event === "session_start")
+            this.forgetCarried(session);
+        this.context.report(session, event);
+    }
+    /**
+     * Forget the briefs, notes deltas and notice kept for this session: it started fresh (a fresh
+     * start, `/clear`, `/new`, a new thread) or ended, so they describe a memory it no longer has —
+     * and a reused name must not inherit them. The server re-sends the whole set after a re-arm.
+     */
+    forgetCarried(session) {
+        this.carriedBriefs.forget(session);
+        this.carriedNotes.forget(session);
+        this.carriedNotices.forget(session);
+        this.acpQueue.forgetCarried(session);
     }
     /**
      * Wait for a session to re-arm its socket, up to `graceMs`.
@@ -501,9 +710,44 @@ class RelayDaemon {
         // obey something its HARNESS owns — `/clear` is read by the runtime's TUI, and no model
         // can run it for itself. So the commands are executed here and everything else wakes
         // the session exactly as it always did.
-        const { commands, chat } = splitSessionCommands(batch);
-        for (const { message, command } of commands) {
-            await this.runSessionCommand(session, message, command);
+        const { commands, chat, dropped } = splitSessionCommands(batch);
+        for (const message of dropped) {
+            this.log(`session command ${message.id} for ${session} dropped: its sender may no longer command this session`);
+        }
+        // What rode on a COMMAND — the project brief, the notes delta, BayChat's notice — never reaches
+        // the session with it (the command is typed, not read), and the server will not send it again;
+        // a WITHDRAWN command's too (the server recorded it as handed whether or not the message is
+        // shown). It moves FORWARD to the next chat message for that room — in this batch, or on disk
+        // until the next one (project-brief.ts, project-notes.ts, context-notice.ts). What was kept
+        // from earlier batches is applied AFTER, underneath: it is older than anything here.
+        const homeless = [];
+        for (const message of [...commands.map((c) => c.message), ...dropped]) {
+            const lost = { message };
+            if (message.projectBrief && !(0, project_brief_1.carryBrief)(message.projectBrief, message.conversationId, chat))
+                lost.brief = message.projectBrief;
+            if (message.projectNotes && !(0, project_notes_1.carryNotes)(message.projectNotes, message, chat))
+                lost.notes = message.projectNotes;
+            if (message.notice && !(0, context_notice_1.carryNotice)(message.notice, chat))
+                lost.notice = message.notice;
+            if (lost.brief || lost.notes || lost.notice)
+                homeless.push(lost);
+        }
+        this.carriedBriefs.apply(session, chat);
+        this.carriedNotes.apply(session, chat);
+        this.carriedNotices.apply(session, chat);
+        for (const { message, brief, notes, notice } of homeless) {
+            if (brief)
+                this.carriedBriefs.keep(session, message.conversationId, brief);
+            if (notes)
+                this.carriedNotes.keep(session, message.conversationId, notes);
+            if (notice)
+                this.carriedNotices.keep(session, notice);
+        }
+        for (const { message, command, focus, refusal, fresh } of commands) {
+            if (fresh)
+                await this.runFreshStart(session, message, fresh, chat);
+            else
+                await this.runSessionCommand(session, message, command, { focus, refusal });
         }
         if (chat.length === 0)
             return;
@@ -1015,6 +1259,9 @@ class RelayDaemon {
     record(outcome, session, batch) {
         if (outcome.kind === "woken") {
             this.delivered += batch.length;
+            const room = batch.at(-1)?.conversationId;
+            if (room)
+                this.lastRoom.set(session, room);
             // The one witness `relay status` may treat as proof that a session is
             // reachable again. A headless turn only counts when it exited cleanly: a
             // spawn that ran and failed delivered nothing, and recording it would
@@ -1261,6 +1508,8 @@ class RelayDaemon {
     }
     async stop() {
         clearInterval(this.acpKeepAlive);
+        this.codexContext.stop();
+        this.context.close();
         this.acp.shutdown();
         this.abort.abort();
         for (const sock of this.attached.values())
@@ -1282,34 +1531,44 @@ class RelayDaemon {
     }
 }
 exports.RelayDaemon = RelayDaemon;
-/**
- * Separate the session commands in a batch from the ordinary chat in it.
- *
- * THREE CONDITIONS, ALL REQUIRED, and each closes a different door:
- *
- *  - `shouldRespond` — the message is addressed to THIS session. Without it, a `/clear`
- *    typed into a group chat that the session merely watches would clear it.
- *  - `commandAuthorized` — the SERVER says this sender may command this session. The relay
- *    never decides that itself (see `RelayMessage.commandAuthorized`), and an absent field
- *    is a no, so an older server can only ever under-permit.
- *  - an exact trigger match — "can you /clear please" is a sentence ABOUT a command and
- *    must reach the agent as one.
- *
- * Anything failing any of them is chat, and wakes the session exactly as it does today.
- */
+/** How long a runtime's TUI is given to clear itself before the fresh session's first prompt. */
+exports.FRESH_START_SETTLE_MS = 1_500;
 function splitSessionCommands(batch) {
     const commands = [];
     const chat = [];
+    const dropped = [];
     for (const message of batch) {
-        const command = message.shouldRespond === true && message.commandAuthorized === true
-            ? (0, session_commands_1.parseSessionCommand)(message.content)
-            : undefined;
-        if (command)
+        const allowed = message.shouldRespond === true && message.commandAuthorized === true;
+        const command = allowed ? (0, session_commands_1.parseSessionCommand)(message.content) : undefined;
+        if (command) {
             commands.push({ message, command });
+            continue;
+        }
+        // A REFUSED /compact is still a command, not chat: a focus carrying a newline or an escape
+        // sequence must not reach the agent as a message it might act on either.
+        const compact = allowed ? (0, compact_command_1.parseCompactCommand)(message.content) : undefined;
+        if (compact?.kind === "compact")
+            commands.push({ message, command: compact_command_1.COMPACT_COMMAND, ...(compact.focus ? { focus: compact.focus } : {}) });
+        else if (compact?.kind === "refused")
+            commands.push({ message, command: compact_command_1.COMPACT_COMMAND, refusal: compact.reason });
+        // The app's "Fresh start": a directed command whose text is never typed (fresh-start.ts).
+        else if (allowed && (0, fresh_start_1.parseFreshStart)(message)) {
+            commands.push({ message, command: fresh_start_1.FRESH_START_COMMAND, fresh: (0, fresh_start_1.parseFreshStart)(message) });
+        }
+        // A DIRECTED command (the app's "Tidy up now": an event that exists on this session's feed
+        // only, `metadata.type: "session.command"`) is never chat. If its authority was withdrawn
+        // between the request and the hand-over, the server says `commandAuthorized: false` — and
+        // the text must then reach the agent neither as keystrokes nor as a message to act on.
+        else if (isDirectedCommand(message))
+            dropped.push(message);
         else
             chat.push(message);
     }
-    return { commands, chat };
+    return { commands, chat, dropped };
+}
+function isDirectedCommand(message) {
+    const metadata = message.metadata;
+    return !!metadata && typeof metadata === "object" && metadata.type === "session.command";
 }
 function writePidFile() {
     try {

package/dist/relay/fresh-start-verify.js

@@ -0,0 +1,237 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HandledHandoffs = void 0;
+exports.samplePane = samplePane;
+exports.waitForIdle = waitForIdle;
+exports.pointerMarker = pointerMarker;
+exports.locatePointer = locatePointer;
+exports.awaitPointer = awaitPointer;
+exports.handledHandoffsPath = handledHandoffsPath;
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const config_1 = require("../config");
+const resume_1 = require("./resume");
+/** What both Claude Code and Codex print in their status line while a turn runs. */
+const BUSY_MARKER = /esc to interrupt/i;
+function execText(file, args) {
+    return new Promise((resolve, reject) => {
+        (0, child_process_1.execFile)(file, args, { timeout: 5_000, encoding: "utf8", maxBuffer: 1024 * 1024 }, (err, stdout) => err ? reject(err) : resolve(stdout));
+    });
+}
+/** Read the bottom of the pane and say whether a turn is running. Never throws. */
+async function samplePane(handle, exec = execText) {
+    try {
+        if (handle.kind === "tmux") {
+            const text = await exec("tmux", ["-S", handle.socket, "capture-pane", "-p", "-t", handle.pane, "-S", "-30"]);
+            return BUSY_MARKER.test(text) ? "busy" : "idle";
+        }
+        if (handle.kind === "screen") {
+            const file = path.join(os.tmpdir(), `baychat-pane-${process.pid}-${Date.now()}.txt`);
+            try {
+                await exec("screen", ["-S", handle.session, "-p", handle.window, "-X", "hardcopy", file]);
+                const text = fs.readFileSync(file, "utf8");
+                return BUSY_MARKER.test(text.split("\n").slice(-30).join("\n")) ? "busy" : "idle";
+            }
+            finally {
+                fs.rmSync(file, { force: true });
+            }
+        }
+        return "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+/**
+ * "idle" once two readings in a row say so; "busy" if a turn is still running at the cap;
+ * "unknown" when the pane could never be read and no socket vouched for the session.
+ */
+async function waitForIdle(opts) {
+    const cap = opts.capMs ?? 60_000;
+    const step = opts.stepMs ?? 1_000;
+    const sleep = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const now = opts.now ?? Date.now;
+    const deadline = now() + cap;
+    let idleRun = 0;
+    let sawBusy = false;
+    for (;;) {
+        const state = await opts.sample();
+        if (state === "idle")
+            idleRun += 1;
+        else
+            idleRun = 0;
+        if (state === "busy")
+            sawBusy = true;
+        if (idleRun >= 2)
+            return "idle";
+        if (state === "unknown" && opts.attached())
+            return "idle";
+        if (now() >= deadline)
+            return sawBusy ? "busy" : state === "unknown" ? "unknown" : "idle";
+        await sleep(step);
+    }
+}
+/** The words only the pointer line carries (fresh-start.ts `freshStartLine`). */
+function pointerMarker(noteId) {
+    return `Your handoff note is note ${noteId}:`;
+}
+async function readTail(file, bytes = 256 * 1024) {
+    const handle = await fs.promises.open(file, "r");
+    try {
+        const { size } = await handle.stat();
+        const start = Math.max(0, size - bytes);
+        const buf = Buffer.alloc(size - start);
+        await handle.read(buf, 0, buf.length, start);
+        return buf.toString("utf8");
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Where the pointer line was written, if anywhere yet. Never throws. */
+async function locatePointer(search) {
+    const marker = pointerMarker(search.noteId);
+    let files;
+    try {
+        files = await (search.list ?? resume_1.transcriptsWrittenSince)(search.runtime, search.sinceMs, search.discovery);
+    }
+    catch {
+        return undefined;
+    }
+    for (const { file, id } of files) {
+        let text;
+        try {
+            text = await (search.readTail ?? readTail)(file);
+        }
+        catch {
+            continue;
+        }
+        if (!text.includes(marker))
+            continue;
+        return search.oldResumeId !== undefined && id === search.oldResumeId ? { kind: "old" } : { kind: "new", id };
+    }
+    return undefined;
+}
+/** `locatePointer`, asked again until the window closes. */
+async function awaitPointer(search) {
+    const sleep = search.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const tries = Math.max(1, Math.ceil((search.timeoutMs ?? 20_000) / (search.stepMs ?? 1_000)));
+    for (let i = 0; i < tries; i++) {
+        const found = await locatePointer(search);
+        if (found)
+            return found;
+        if (i < tries - 1)
+            await sleep(search.stepMs ?? 1_000);
+    }
+    return undefined;
+}
+// ─── Never twice ──────────────────────────────────────────────────────────────────────
+function handledHandoffsPath() {
+    return path.join((0, config_1.configDir)(), "fresh-starts.json");
+}
+/** Kept for two days: far longer than the server's event ring could ever replay a step. */
+const KEEP_MS = 48 * 60 * 60_000;
+/**
+ * Fresh-start steps this relay has already handled, by `<handoffId>:<phase>`. ON DISK, 0600, next
+ * to the relay's other state: the feed replays after a restart, and a replayed `clear` must not
+ * clear a session a second time.
+ */
+class HandledHandoffs {
+    file;
+    now;
+    steps;
+    constructor(file = handledHandoffsPath(), now = Date.now) {
+        this.file = file;
+        this.now = now;
+    }
+    has(handoffId, phase) {
+        return this.load().has(`${handoffId}:${phase}`);
+    }
+    mark(handoffId, phase, session, state) {
+        this.load().set(`${handoffId}:${phase}`, { session, state, at: this.now() });
+        this.save();
+    }
+    /** Clears that were being typed when the relay stopped: `{ handoffId, session }`. */
+    interrupted() {
+        return [...this.load()]
+            .filter(([key, step]) => step.state === "started" && key.endsWith(":clear"))
+            .map(([key, step]) => ({ handoffId: key.slice(0, -":clear".length), session: step.session }));
+    }
+    load() {
+        if (this.steps)
+            return this.steps;
+        this.steps = new Map();
+        let raw;
+        try {
+            raw = JSON.parse(fs.readFileSync(this.file, "utf8"));
+        }
+        catch (err) {
+            if (err.code !== "ENOENT") {
+                process.stderr.write(`baychat relay: could not read handled fresh starts — ${err instanceof Error ? err.message : String(err)}\n`);
+            }
+            return this.steps;
+        }
+        const cutoff = this.now() - KEEP_MS;
+        if (raw && typeof raw === "object") {
+            for (const [key, value] of Object.entries(raw)) {
+                const v = value;
+                if (!v || typeof v.session !== "string" || typeof v.at !== "number" || v.at < cutoff)
+                    continue;
+                if (v.state !== "started" && v.state !== "done")
+                    continue;
+                this.steps.set(key, { session: v.session, state: v.state, at: v.at });
+            }
+        }
+        return this.steps;
+    }
+    save() {
+        const cutoff = this.now() - KEEP_MS;
+        for (const [key, step] of this.steps ?? [])
+            if (step.at < cutoff)
+                this.steps.delete(key);
+        try {
+            fs.mkdirSync(path.dirname(this.file), { recursive: true });
+            fs.writeFileSync(this.file, JSON.stringify(Object.fromEntries(this.steps ?? new Map())), { mode: 0o600 });
+            fs.chmodSync(this.file, 0o600);
+        }
+        catch (err) {
+            process.stderr.write(`baychat relay: could not persist handled fresh starts — ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+    }
+}
+exports.HandledHandoffs = HandledHandoffs;