@hwip/cli 0.1.1 → 0.1.3

package/dist/session-registry.d.ts

@@ -23,6 +23,26 @@ export interface KnownSession {
     agentKind: string;
     project?: string;
     label?: string;
+    /**
+     * Which run of the name this was (hwip docs/session-runs.md): tmux
+     * `session_created` in epoch seconds, as a decimal string. Absent from
+     * entries written before runs were recorded.
+     */
+    runId?: string;
+    /** When that run started (ISO) — the same instant as `runId`. */
+    startedAt?: string;
+    /**
+     * The agent's own id for the conversation this run last had, as the sweep
+     * read it off the live pane — what a resume picks back up. Absent for an
+     * agent whose id this machine cannot read, and in files written before it.
+     */
+    agentSessionId?: string;
+    /**
+     * The later tmux sessions this run went on in (`session_created`, as
+     * `runId`): the same conversation carried on after an `exit` is the same
+     * run (`continuedRunId`). Absent for a run that has had one tmux session.
+     */
+    tmuxRunIds?: string[];
     /** Last time this machine saw the session running. */
     lastSeenAt: string;
 }
@@ -33,12 +53,14 @@ export interface KnownSession {
  * that has run agents for years.
  */
 export declare const MAX_KNOWN_SESSIONS = 100;
+/** Runs kept per name: a slot reused all day would otherwise fill the file with one project. */
+export declare const MAX_RUNS_PER_NAME = 10;
 /** Forgotten after this long unseen — a directory from months ago is more
  *  likely to have moved than to be what the user meant. */
 export declare const KNOWN_SESSION_TTL_MS: number;
 /**
- * What makes two sightings the same remembered run: the tmux name AND the
- * agent that was running under it.
+ * What makes two sightings the same remembered run: the tmux name, the agent
+ * that was running under it, AND the tmux session it ran in (`runId`).
  *
  * Keyed by name alone, a `hwip cc` in a project erased whatever pi had done in
  * the same slot — the ended run left no row to resume and no row to read, and
@@ -48,8 +70,13 @@ export declare const KNOWN_SESSION_TTL_MS: number;
  * NUL rather than a printable separator: a project directory can be called
  * almost anything, and a name holding the separator must not be able to forge
  * another run's key.
+ *
+ * The run id splits two sittings of the same agent in the same slot: closing
+ * `hwip cc` and starting it again is a new conversation, and the record of the
+ * first is a past session of its own. An entry without one (written before
+ * runs were recorded) keys as the empty run.
  */
-export declare const runKey: (name: string, agentKind: string) => string;
+export declare const runKey: (name: string, agentKind: string, runId?: string) => string;
 /** Sessions this machine has seen, newest first, expired ones dropped. */
 export declare const knownSessions: (now?: number) => KnownSession[];
 /** One remembered session, or null when this machine never saw that name.
@@ -65,6 +92,20 @@ export declare const recallSession: (name: string, now?: number) => KnownSession
  * decides whether to fall back to the newest run or refuse.
  */
 export declare const recallRun: (name: string, agentKind: string, now?: number) => KnownSession | null;
+/** tmux sessions remembered per run: an `exit` and `-c` every few minutes all day stays a short list. */
+export declare const MAX_TMUX_RUNS_PER_RUN = 10;
+/**
+ * Which run the tmux session `tmuxRunId` of `name` is (hwip docs/session-runs.md §3).
+ *
+ * Its own, unless it carries on an earlier run: it was already joined to one
+ * (a sweep or a listener restart since), or the agent's conversation
+ * `conversationId` is the one an earlier run of the same name and agent last
+ * had. A tmux session that has had a conversation of its own stays its own run
+ * — a fresh start `/resume`d into an old conversation keeps what it wrote first.
+ */
+export declare const continuedRunId: (entries: readonly KnownSession[], name: string, agentKind: string, tmuxRunId: string, conversationId: string | null | undefined) => string;
+/** The run going on in tmux session `tmuxRunId` of `name`: the one it was joined to, else its own. */
+export declare const runOfTmuxSession: (name: string, tmuxRunId: string, now?: number) => string;
 /**
  * Make this process a reader of the registry: `rememberSessions` writes nothing from here on. For the
  * CLI commands that look at the sweep (`hwip agent list|read`) — the file is the listener's resume
@@ -87,6 +128,16 @@ export declare const rememberSessions: (live: Array<{
     agentKind: string;
     project?: string | null;
     label?: string | null;
+    runId?: string;
+    startedAt?: string;
+    /** The tmux session it runs in; one other than `runId` means the run goes on in it (`continuedRunId`). */
+    tmuxRunId?: string;
+    /**
+     * The conversation a resume may pick up. Absent: not readable this
+     * sweep, so the run keeps the one it had. Null: read, but not this
+     * run's alone to resume — the run forgets it.
+     */
+    agentSessionId?: string | null;
 }>, now?: number) => void;
 /**
  * Forget one session, by name. Returns false when this machine never knew it.
@@ -107,7 +158,8 @@ export type ForgetOutcome =
  | 'forgotten'
 /** Registry entry gone, but the scrollback file would not delete. */
  | 'scrollback_kept';
-export declare const forgetSession: (name: string, agentKind?: string) => ForgetOutcome;
+/** `nameRunning`: a run of this name is going right now, so its scrollback stays whether or not the registry has written that run down yet. */
+export declare const forgetSession: (name: string, agentKind?: string, runId?: string, nameRunning?: boolean) => ForgetOutcome;
 /**
  * What the caller was able to find out about a name. `unknown` is not a
  * synonym for ended: it is the terminal failing to answer at all — no tmux to

package/dist/session-registry.js

@@ -16,7 +16,7 @@
  * another program.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.sessionDirectoryExists = exports.knownSessionsPath = exports.isKnownSession = exports.forgetEnded = exports.forgetSession = exports.rememberSessions = exports.keepRegistryUntouched = exports.recallRun = exports.recallSession = exports.knownSessions = exports.runKey = exports.KNOWN_SESSION_TTL_MS = exports.MAX_KNOWN_SESSIONS = void 0;
+exports.sessionDirectoryExists = exports.knownSessionsPath = exports.isKnownSession = exports.forgetEnded = exports.forgetSession = exports.rememberSessions = exports.keepRegistryUntouched = exports.runOfTmuxSession = exports.continuedRunId = exports.MAX_TMUX_RUNS_PER_RUN = exports.recallRun = exports.recallSession = exports.knownSessions = exports.runKey = exports.KNOWN_SESSION_TTL_MS = exports.MAX_RUNS_PER_NAME = 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");
@@ -29,10 +29,13 @@ const private_files_js_1 = require("./private-files.js");
  * that has run agents for years.
  */
 exports.MAX_KNOWN_SESSIONS = 100;
+/** Runs kept per name: a slot reused all day would otherwise fill the file with one project. */
+exports.MAX_RUNS_PER_NAME = 10;
 /** Forgotten after this long unseen — a directory from months ago is more
  *  likely to have moved than to be what the user meant. */
 exports.KNOWN_SESSION_TTL_MS = 30 * 24 * 60 * 60 * 1000;
 const registryPath = () => (0, path_1.join)((0, gate_js_1.stateDir)(), 'known-sessions.json');
+const isTmuxRunIds = (v) => v === undefined || (Array.isArray(v) && v.every((id) => typeof id === 'string'));
 const readAll = () => {
     try {
         const raw = (0, fs_1.readFileSync)(registryPath(), 'utf-8');
@@ -46,7 +49,9 @@ const readAll = () => {
             typeof e.name === 'string' &&
             typeof e.cwd === 'string' &&
             typeof e.agentKind === 'string' &&
-            typeof e.lastSeenAt === 'string');
+            typeof e.lastSeenAt === 'string' &&
+            (e.runId === undefined || typeof e.runId === 'string') &&
+            isTmuxRunIds(e.tmuxRunIds));
     }
     catch {
         return [];
@@ -67,8 +72,8 @@ const writeAll = (entries) => {
     }
 };
 /**
- * What makes two sightings the same remembered run: the tmux name AND the
- * agent that was running under it.
+ * What makes two sightings the same remembered run: the tmux name, the agent
+ * that was running under it, AND the tmux session it ran in (`runId`).
  *
  * Keyed by name alone, a `hwip cc` in a project erased whatever pi had done in
  * the same slot — the ended run left no row to resume and no row to read, and
@@ -78,8 +83,13 @@ const writeAll = (entries) => {
  * NUL rather than a printable separator: a project directory can be called
  * almost anything, and a name holding the separator must not be able to forge
  * another run's key.
+ *
+ * The run id splits two sittings of the same agent in the same slot: closing
+ * `hwip cc` and starting it again is a new conversation, and the record of the
+ * first is a past session of its own. An entry without one (written before
+ * runs were recorded) keys as the empty run.
  */
-const runKey = (name, agentKind) => `${name}\u0000${agentKind}`;
+const runKey = (name, agentKind, runId) => `${name}\u0000${agentKind}\u0000${runId ?? ''}`;
 exports.runKey = runKey;
 /** Sessions this machine has seen, newest first, expired ones dropped. */
 const knownSessions = (now = Date.now()) => readAll()
@@ -101,6 +111,37 @@ exports.recallSession = recallSession;
  */
 const recallRun = (name, agentKind, now = Date.now()) => (0, exports.knownSessions)(now).find((e) => e.name === name && e.agentKind === agentKind) ?? null;
 exports.recallRun = recallRun;
+/** tmux sessions remembered per run: an `exit` and `-c` every few minutes all day stays a short list. */
+exports.MAX_TMUX_RUNS_PER_RUN = 10;
+/** Agents whose own resume is measured to keep the conversation id: Claude Code 2.1.300's `-c` does. */
+const CONTINUING_KINDS = new Set(['claude']);
+/**
+ * Which run the tmux session `tmuxRunId` of `name` is (hwip docs/session-runs.md §3).
+ *
+ * Its own, unless it carries on an earlier run: it was already joined to one
+ * (a sweep or a listener restart since), or the agent's conversation
+ * `conversationId` is the one an earlier run of the same name and agent last
+ * had. A tmux session that has had a conversation of its own stays its own run
+ * — a fresh start `/resume`d into an old conversation keeps what it wrote first.
+ */
+const continuedRunId = (entries, name, agentKind, tmuxRunId, conversationId) => {
+    const ofName = entries.filter((e) => e.name === name && e.agentKind === agentKind && e.runId);
+    const joined = ofName.find((e) => e.runId !== tmuxRunId && e.tmuxRunIds?.includes(tmuxRunId));
+    if (joined?.runId)
+        return joined.runId;
+    if (!conversationId || !CONTINUING_KINDS.has(agentKind))
+        return tmuxRunId;
+    if (ofName.some((e) => e.runId === tmuxRunId && e.agentSessionId))
+        return tmuxRunId;
+    const earlier = ofName
+        .filter((e) => e.agentSessionId === conversationId && Number(e.runId) < Number(tmuxRunId))
+        .sort((a, b) => b.lastSeenAt.localeCompare(a.lastSeenAt))[0];
+    return earlier?.runId ?? tmuxRunId;
+};
+exports.continuedRunId = continuedRunId;
+/** The run going on in tmux session `tmuxRunId` of `name`: the one it was joined to, else its own. */
+const runOfTmuxSession = (name, tmuxRunId, now = Date.now()) => (0, exports.knownSessions)(now).find((e) => e.name === name && e.tmuxRunIds?.includes(tmuxRunId))?.runId ?? tmuxRunId;
+exports.runOfTmuxSession = runOfTmuxSession;
 let readOnly = false;
 /**
  * Make this process a reader of the registry: `rememberSessions` writes nothing from here on. For the
@@ -128,30 +169,68 @@ const rememberSessions = (live, now = Date.now()) => {
     if (usable.length === 0)
         return;
     const seenAt = new Date(now).toISOString();
-    const byRun = new Map((0, exports.knownSessions)(now).map((e) => [(0, exports.runKey)(e.name, e.agentKind), e]));
+    const byRun = new Map((0, exports.knownSessions)(now).map((e) => [(0, exports.runKey)(e.name, e.agentKind, e.runId), e]));
     for (const s of usable) {
-        byRun.set((0, exports.runKey)(s.name, s.agentKind), {
+        // The entry this run had before runs were recorded: same slot and agent,
+        // no run, seen while this run was already going. It is this run, not a
+        // past one, and would otherwise be reported as one.
+        if (s.runId && s.startedAt) {
+            const before = byRun.get((0, exports.runKey)(s.name, s.agentKind));
+            if (before && before.lastSeenAt >= s.startedAt)
+                byRun.delete((0, exports.runKey)(s.name, s.agentKind));
+        }
+        // Carried on in a new tmux session: what an earlier sweep wrote under that session is this run.
+        const continued = !!s.runId && !!s.tmuxRunId && s.tmuxRunId !== s.runId;
+        if (continued)
+            byRun.delete((0, exports.runKey)(s.name, s.agentKind, s.tmuxRunId));
+        const key = (0, exports.runKey)(s.name, s.agentKind, s.runId);
+        // A sweep that could not read the id — the agent has not written its
+        // record yet — keeps the one this run already had. Keyed by run and
+        // directory, so neither another agent taking the name nor the same
+        // agent started elsewhere under it inherits a conversation.
+        const prev = byRun.get(key);
+        const keepPrev = s.agentSessionId === undefined && prev?.cwd === s.cwd;
+        const agentSessionId = s.agentSessionId || (keepPrev ? prev?.agentSessionId : undefined);
+        // A run keeps its first start whichever tmux session it goes on in.
+        const startedAt = continued ? prev?.startedAt ?? s.startedAt : s.startedAt;
+        const tmuxRunIds = continued && s.tmuxRunId
+            ? [...(prev?.tmuxRunIds ?? []).filter((id) => id !== s.tmuxRunId), s.tmuxRunId].slice(-exports.MAX_TMUX_RUNS_PER_RUN)
+            : prev?.tmuxRunIds;
+        byRun.set(key, {
             name: s.name,
             cwd: s.cwd,
             agentKind: s.agentKind,
             ...(s.project ? { project: s.project } : {}),
             ...(s.label ? { label: s.label } : {}),
+            ...(s.runId ? { runId: s.runId } : {}),
+            ...(startedAt ? { startedAt } : {}),
+            ...(agentSessionId ? { agentSessionId } : {}),
+            ...(tmuxRunIds?.length ? { tmuxRunIds } : {}),
             lastSeenAt: seenAt,
         });
     }
+    const perName = new Map();
     const entries = [...byRun.values()]
         .sort((a, b) => b.lastSeenAt.localeCompare(a.lastSeenAt))
+        .filter((e) => {
+        const n = (perName.get(e.name) ?? 0) + 1;
+        perName.set(e.name, n);
+        return n <= exports.MAX_RUNS_PER_NAME;
+    })
         .slice(0, exports.MAX_KNOWN_SESSIONS);
     writeAll(entries);
 };
 exports.rememberSessions = rememberSessions;
-const forgetSession = (name, agentKind) => {
+/** `nameRunning`: a run of this name is going right now, so its scrollback stays whether or not the registry has written that run down yet. */
+const forgetSession = (name, agentKind, runId, nameRunning = false) => {
     const entries = readAll();
-    // With a kind, only that run goes — the phone deletes the row it is looking
-    // at, and a name that held both pi and claude shows two rows. Without one
-    // (an older phone, which sends no kind), the name goes entirely: that is
-    // what the request meant when a name could only mean one run.
-    const kept = entries.filter((e) => e.name !== name || (agentKind ? e.agentKind !== agentKind : false));
+    // With a kind, only that agent's runs go — the phone deletes the row it is
+    // looking at, and a name that held both pi and claude shows two rows. With a
+    // run as well, only that one run. Without a kind (an older phone, which
+    // sends none), the name goes entirely: that is what the request meant when a
+    // name could only mean one run.
+    const doomed = (e) => e.name === name && (!agentKind || e.agentKind === agentKind) && (!runId || e.runId === runId);
+    const kept = entries.filter((e) => !doomed(e));
     if (kept.length === entries.length)
         return 'unknown';
     // The chat's scrollback for that session goes with it. Forgetting a session
@@ -162,7 +241,7 @@ const forgetSession = (name, agentKind) => {
     // Except while another run still answers to the name: the scrollback is per
     // NAME, so deleting the pi row would take the claude row's history with it.
     // The record is gone either way; the file waits for the last run to go.
-    const nameStillHeld = kept.some((e) => e.name === name);
+    const nameStillHeld = nameRunning || kept.some((e) => e.name === name);
     writeAll(kept);
     if (nameStillHeld)
         return 'forgotten';

package/dist/templates.js

@@ -368,6 +368,7 @@ exports.COPILOT_HOOKS = JSON.stringify({
 /** Pi extension source — written to ~/.pi/agent/extensions/hwip.ts (drop-in auto-load). */
 exports.PI_EXTENSION = `// Generated by @hwip/cli — reinstall overwrites; \`hwip uninstall\` removes.
 import { spawn, execFile, execFileSync } from "node:child_process";
+import { statSync } from "node:fs";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 const sh = (cmd: string, cwd: string, stdin?: string): Promise<string> =>
@@ -436,14 +437,21 @@ const SUBAGENT_SESSION = (() => {
 // to the pane the wrapper records as session options (cli config
 // HERDR_SESSION_OPTIONS). Read per report, not once: a reattach from another
 // herdr pane retargets a running pi. No options -> not in herdr -> no-op. herdr's
-// own pi extension reads HERDR_* from the env, which tmux does not pass, so it
-// stays silent here. Same protocol as the Claude Code plugin's hwip-herdr.sh.
+// own pi extension reads HERDR_* from the env, which the wrapper empties for a
+// \`hwip pi\` session (cli wrapper herdrEnvArgs), so it stays silent here: a second
+// report on the pane would replace this one. Same protocol as the Claude Code
+// plugin's hwip-herdr.sh.
 const TMUX_PANE = process.env.TMUX_PANE || "";
 // Set by session_start for the TUI only: a \`pi -p\` or RPC run from a shell in
 // a wrapped pane inherits TMUX_PANE, and must not report (or release) that
 // pane's agent. herdr's own pi extension gates on the same \`ctx.mode\`.
 let herdrTui = false;
 let herdrLast = "";
+// herdr forgets every report when it restarts, and recreates its socket when it
+// starts: the socket's mtime is part of what counts as already sent.
+const herdrBorn = (socket: string): number => {
+  try { return statSync(socket).mtimeMs; } catch { return 0; }
+};
 let herdrSeq = 0;
 // Resolves once herdr is spawned, so session_shutdown can hold pi's exit until
 // the release is on its way.
@@ -454,9 +462,12 @@ const herdr = (state: "idle" | "working" | "blocked" | "release"): Promise<void>
   // it now, in event order, not when tmux answers.
   const seq = herdrSeq = Math.max(Date.now() * 1000, herdrSeq + 1);
   execFile("tmux", ["display-message", "-p", "-t", TMUX_PANE, "#{@hwip_herdr_pane}\\t#{@hwip_herdr_socket}\\t#{@hwip_herdr_bin}"], { timeout: 2000 }, (err, out) => {
-    const [pane, socket, bin] = String(out).trim().split("\\t");
-    if (err || !pane || !socket || herdrLast === pane + " " + state) return resolve();
-    herdrLast = pane + " " + state;
+    // Only the newline off the end: trim() would also eat an empty pane's tab and
+    // read the socket as the pane.
+    const [pane, socket, bin] = String(out).replace(/\\r?\\n$/, "").split("\\t");
+    const sent = pane + " " + state + " " + (socket ? herdrBorn(socket) : 0);
+    if (err || !pane || !socket || herdrLast === sent) return resolve();
+    herdrLast = sent;
     const who = ["--source", "hwip-pi", "--agent", "hwip pi"];
     const args = state === "release"
       ? ["pane", "release-agent", pane, ...who, "--seq", String(seq)]

package/dist/tmux-liveness.d.ts

@@ -11,6 +11,13 @@ import type { SessionLiveness } from './session-registry.js';
  * user's server would otherwise call every live session an ended one.
  */
 export declare const liveSessionNames: () => string[] | null;
+/**
+ * The run (hwip docs/session-runs.md) tmux holds under `name` right now: its
+ * `session_created` in epoch seconds. Null when the name is not running, and
+ * undefined when no tmux answered — a caller that deletes on "another run"
+ * must refuse on that, as it refuses on `unknown` liveness.
+ */
+export declare const liveRunIdOf: (name: string) => string | null | undefined;
 /**
  * The three-state answer, for callers that destroy something on "ended".
  *

package/dist/tmux-liveness.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.sessionExists = exports.sessionLiveness = exports.liveSessionNames = void 0;
+exports.sessionExists = exports.sessionLiveness = exports.liveRunIdOf = exports.liveSessionNames = void 0;
 const child_process_1 = require("child_process");
 const tmux_pane_js_1 = require("./tmux-pane.js");
 const tmux_socket_js_1 = require("./tmux-socket.js");
@@ -27,6 +27,27 @@ const liveSessionNames = () => {
     return (probe.stdout ?? '').split('\n').map((line) => line.trim()).filter(Boolean);
 };
 exports.liveSessionNames = liveSessionNames;
+/**
+ * The run (hwip docs/session-runs.md) tmux holds under `name` right now: its
+ * `session_created` in epoch seconds. Null when the name is not running, and
+ * undefined when no tmux answered — a caller that deletes on "another run"
+ * must refuse on that, as it refuses on `unknown` liveness.
+ */
+const liveRunIdOf = (name) => {
+    const probe = (0, child_process_1.spawnSync)('tmux', (0, tmux_socket_js_1.tmuxArgs)(['list-sessions', '-F', '#{session_name}\t#{session_created}']), {
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    if (probe.error || probe.status !== 0)
+        return undefined;
+    for (const line of (probe.stdout ?? '').split('\n')) {
+        const tab = line.lastIndexOf('\t');
+        if (tab > 0 && line.slice(0, tab) === name)
+            return /^\d{1,12}$/.test(line.slice(tab + 1).trim()) ? line.slice(tab + 1).trim() : undefined;
+    }
+    return null;
+};
+exports.liveRunIdOf = liveRunIdOf;
 /**
  * The three-state answer, for callers that destroy something on "ended".
  *

package/dist/turn-recorder-wire.js

@@ -98,7 +98,7 @@ const createChunkUploader = (opts) => {
         try {
             res = await (0, api_js_1.apiFetch)(fetchFn, (0, api_js_1.apiUrl)(opts.baseUrl, `/sessions/${encodeURIComponent(sessionKey)}/turns`), opts.apiKey, UPLOAD_TIMEOUT_MS, {
                 method: 'POST',
-                body: JSON.stringify({ seq: chunk.seq, firstAt: chunk.firstAt, lastAt: chunk.lastAt, sealed: chunk.sealed }),
+                body: JSON.stringify({ seq: chunk.seq, firstAt: chunk.firstAt, lastAt: chunk.lastAt, ...(chunk.runId ? { runId: chunk.runId } : {}), sealed: chunk.sealed }),
             });
         }
         catch (err) {

package/dist/turn-recorder.d.ts

@@ -80,6 +80,8 @@ export interface RecordableSession {
     path: string;
     /** `RegisteredRemoteAgent.kind` — which projector reads it. */
     kind: string;
+    /** The run (tmux session) writing it (hwip docs/session-runs.md); every chunk read from it carries this. */
+    runId?: string;
 }
 /** A pinned device's key, or this machine's own. */
 export interface RecorderRecipient {
@@ -96,6 +98,8 @@ export interface OutboxChunk {
     seq: number;
     firstAt: string;
     lastAt: string;
+    /** The run the events were recorded in. Absent from chunks made before runs were recorded. */
+    runId?: string;
     sealed: SealedChunk;
 }
 export type UploadOutcome = 
@@ -145,6 +149,8 @@ export interface TurnRecorderDeps {
     /** The newest `seq` the server holds for a session, or null when it cannot be read. After a 409
      *  (the same `seq` under another body) the next chunk is numbered past it. */
     latestSeq?: (sessionKey: string) => Promise<number | null>;
+    /** The seqs a run was just handed, once they are in the outbox: the run's seq block is reported from these (`run-seqs.ts`). */
+    noteSeqs?: (name: string, runId: string, firstSeq: number, lastSeq: number) => void;
     log: (message: string) => void;
     now?: () => number;
 }
@@ -155,6 +161,8 @@ interface SessionState {
     path: string;
     /** The agent kind that wrote it, so a session that is gone after a restart can still be read to its end. */
     kind?: string;
+    /** The run that wrote it, for the same reason: what is read from it after a restart is still that run's. */
+    runId?: string;
     ino: number;
     /** End of the last complete line whose events are in a chunk. */
     offset: number;

package/dist/turn-recorder.js

@@ -107,6 +107,7 @@ const readSessionState = (dir, sessionKey) => {
             sessionKey,
             path: raw.path,
             ...(typeof raw.kind === 'string' ? { kind: raw.kind } : {}),
+            ...(typeof raw.runId === 'string' ? { runId: raw.runId } : {}),
             ino: typeof raw.ino === 'number' ? raw.ino : 0,
             offset: raw.offset,
             ...(raw.cursor !== undefined ? { cursor: raw.cursor } : {}),
@@ -212,6 +213,9 @@ const createTurnRecorder = (deps) => {
     /** The kind that wrote `path`: the file a session has left was written by the kind its state names,
      *  which is not always the kind of the file it writes now. */
     const kindOf = (live, path) => path !== live.source.path ? live.state?.kind ?? live.source.kind : live.source.kind;
+    /** The run that wrote `path`, by the same rule: a file the session has left is the run its state names.
+     *  A new run under the same name keeps the name's `seq` numbering (the server's key) but tags its own. */
+    const runOf = (live, path) => path !== live.source.path ? live.state?.runId ?? live.source.runId : live.source.runId;
     const readerOf = (live, path) => deps.readerFor?.(kindOf(live, path)) ?? null;
     const startTail = (live) => {
         const state = live.state;
@@ -267,6 +271,7 @@ const createTurnRecorder = (deps) => {
         };
         const fallbackAt = new Date(now()).toISOString();
         const chunks = [];
+        const runId = runOf(live, live.tailPath);
         let seq = base.seq;
         try {
             for (const page of pages) {
@@ -274,7 +279,7 @@ const createTurnRecorder = (deps) => {
                 const firstAt = eventAt(page, 'first', fallbackAt);
                 const lastAt = eventAt(page, 'last', fallbackAt);
                 const sealed = await deps.seal(JSON.stringify({ sessionKey: live.sessionKey, seq, events: page }), recipients);
-                chunks.push({ seq, firstAt, lastAt, sealed });
+                chunks.push({ seq, firstAt, lastAt, ...(runId ? { runId } : {}), sealed });
             }
         }
         catch (err) {
@@ -291,6 +296,7 @@ const createTurnRecorder = (deps) => {
             ...base,
             path: live.tailPath,
             kind: kindOf(live, live.tailPath),
+            runId,
             ino: live.tail.ino,
             offset: committed,
             cursor: live.tail.cursor,
@@ -300,6 +306,8 @@ const createTurnRecorder = (deps) => {
         };
         if (!persist(live, next))
             return;
+        if (runId && chunks.length)
+            deps.noteSeqs?.(live.name, runId, chunks[0].seq, seq);
         live.pending = [];
         live.pendingBytes = 0;
         live.hasPrompt = false;
@@ -615,7 +623,7 @@ const createTurnRecorder = (deps) => {
             const state = (0, exports.readSessionState)(deps.dir, sessionKey);
             if (!state)
                 continue;
-            sessions.set(name, newLive(name, { path: state.path, kind: state.kind ?? '' }, now()));
+            sessions.set(name, newLive(name, { path: state.path, kind: state.kind ?? '', ...(state.runId ? { runId: state.runId } : {}) }, now()));
         }
     };
     /**

package/dist/wrapper.d.ts

@@ -20,12 +20,20 @@ export declare const detectProjectName: () => string;
  * session (measured on tmux 3.5a).
  */
 export declare const sessionSidecarArgs: (session: string, projectDir: string, label?: string) => string[];
+export declare const herdrSessionArgs: (session: string, env?: NodeJS.ProcessEnv) => string[];
 /**
- * tmux commands, chained after `new -A`, that point config
- * `HERDR_SESSION_OPTIONS` at the herdr pane this attach runs in, or clear them
- * outside herdr.
+ * `new-session -e` flags for config `HERDR_ENV_VARS`, so herdr's native integration
+ * in the agent reports to the herdr pane this launch attaches from — or, empty, to no
+ * pane at all: for an agent hwip reports itself (`HERDR_SELF_REPORTING_KINDS`), a
+ * detached launch, or a launch from outside herdr. Without them the agent inherits the
+ * tmux server's global env and reports to a pane that is gone. Session env, so a later
+ * split pane gets the same. A reattach does not move a running agent's env: herdr's
+ * integrations keep the pane the session was created from. `new-session -e` is tmux 3.2;
+ * an older tmux gets none, as before.
  */
-export declare const herdrSessionArgs: (session: string, env?: NodeJS.ProcessEnv) => string[];
+export declare const herdrEnvArgs: (agentKind: string | undefined, env: NodeJS.ProcessEnv, tmuxVersion: string) => string[];
+/** `tmux -V`, read once per process; empty when tmux does not answer. */
+export declare const installedTmuxVersion: () => string;
 /**
  * `hwip-<project>` — the canonical tmux session base name. tmux itself turns
  * `.` and `:` into `_` when it creates a session (3.5a: `hwip-foo.bar` becomes

package/dist/wrapper.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.handleShellSession = exports.shellTargets = exports.readShellSessionState = exports.planShellSession = exports.handleAgentSession = exports.tmuxMissingMessage = exports.inPaneNote = exports.handOffExec = exports.ensureListenerRunning = exports.takeListenerLaunchMarker = exports.listenerVersionDrifted = exports.targetForAgent = exports.splitAgentOptions = exports.sanitizeLabel = exports.findAvailableSession = exports.firstFreeSession = exports.tmuxSessionName = exports.herdrSessionArgs = exports.sessionSidecarArgs = exports.detectProjectName = exports.detectProjectDir = exports.safeBasename = void 0;
+exports.handleShellSession = exports.shellTargets = exports.readShellSessionState = exports.planShellSession = exports.handleAgentSession = exports.tmuxMissingMessage = exports.inPaneNote = exports.handOffExec = exports.ensureListenerRunning = exports.takeListenerLaunchMarker = exports.listenerVersionDrifted = exports.targetForAgent = exports.splitAgentOptions = exports.sanitizeLabel = exports.findAvailableSession = exports.firstFreeSession = exports.tmuxSessionName = exports.installedTmuxVersion = exports.herdrEnvArgs = exports.herdrSessionArgs = exports.sessionSidecarArgs = exports.detectProjectName = exports.detectProjectDir = exports.safeBasename = void 0;
 /**
  * `hwip cc` / `hwip codex` / `hwip gemini` — spawn an agent inside a named
  * tmux session so the resident listener (`hwip listener`) can address it
@@ -79,14 +79,52 @@ exports.sessionSidecarArgs = sessionSidecarArgs;
  * `HERDR_SESSION_OPTIONS` at the herdr pane this attach runs in, or clear them
  * outside herdr.
  */
+const inHerdr = (env) => env.HERDR_ENV === '1' && !!env.HERDR_PANE_ID && !!env.HERDR_SOCKET_PATH;
 const herdrSessionArgs = (session, env = process.env) => {
-    const inHerdr = env.HERDR_ENV === '1' && !!env.HERDR_PANE_ID && !!env.HERDR_SOCKET_PATH;
+    const attached = inHerdr(env);
     return Object.entries(config_js_1.HERDR_SESSION_OPTIONS).flatMap(([name, option]) => {
-        const value = inHerdr ? env[name] : undefined;
+        const value = attached ? env[name] : undefined;
         return [';', 'set-option', ...(value ? [] : ['-u']), '-t', sessionOptionTarget(session), option, ...(value ? [value] : [])];
     });
 };
 exports.herdrSessionArgs = herdrSessionArgs;
+/**
+ * `new-session -e` flags for config `HERDR_ENV_VARS`, so herdr's native integration
+ * in the agent reports to the herdr pane this launch attaches from — or, empty, to no
+ * pane at all: for an agent hwip reports itself (`HERDR_SELF_REPORTING_KINDS`), a
+ * detached launch, or a launch from outside herdr. Without them the agent inherits the
+ * tmux server's global env and reports to a pane that is gone. Session env, so a later
+ * split pane gets the same. A reattach does not move a running agent's env: herdr's
+ * integrations keep the pane the session was created from. `new-session -e` is tmux 3.2;
+ * an older tmux gets none, as before.
+ */
+const herdrEnvArgs = (agentKind, env, tmuxVersion) => {
+    if (!sessionEnvSupported(tmuxVersion))
+        return [];
+    const native = inHerdr(env) && !config_js_1.HERDR_SELF_REPORTING_KINDS.has(agentKind ?? '');
+    return config_js_1.HERDR_ENV_VARS.flatMap((name) => ['-e', `${name}=${native ? env[name] ?? '' : ''}`]);
+};
+exports.herdrEnvArgs = herdrEnvArgs;
+/** `tmux -V` says 3.2 or later (`new-session -e`); a development build (`next-3.7`, `master`) is newer. */
+const sessionEnvSupported = (version) => {
+    if (/\b(master|next-)/.test(version))
+        return true;
+    const m = version.match(/(\d+)\.(\d+)/);
+    if (!m)
+        return false;
+    const [major, minor] = [Number(m[1]), Number(m[2])];
+    return major > 3 || (major === 3 && minor >= 2);
+};
+let tmuxVersionCache;
+/** `tmux -V`, read once per process; empty when tmux does not answer. */
+const installedTmuxVersion = () => {
+    if (tmuxVersionCache === undefined) {
+        const ver = (0, child_process_1.spawnSync)('tmux', ['-V'], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000 });
+        tmuxVersionCache = (ver.stdout ?? '').trim();
+    }
+    return tmuxVersionCache;
+};
+exports.installedTmuxVersion = installedTmuxVersion;
 /**
  * The option target for one session by exact name. `=` stops a prefix match;
  * the trailing `:` makes `show-options`/`set-option`, which read `-t` as a
@@ -300,10 +338,13 @@ const targetForAgent = (agent, extra, agentKind, opts = {}) => {
     // would otherwise get a session named for one tree running in another.
     const sidecar = (0, exports.sessionSidecarArgs)(session, projectDir, opts.label);
     if (opts.detach) {
-        return { kind: 'tmux-detached', cmd: 'tmux', args: ['new', '-d', '-s', session, '-c', projectDir, shellCmd, ...sidecar], session };
+        // Attached to no herdr pane: blank, whatever pane this command was typed in.
+        const herdrEnv = (0, exports.herdrEnvArgs)(agentKind, {}, (0, exports.installedTmuxVersion)());
+        return { kind: 'tmux-detached', cmd: 'tmux', args: ['new', '-d', '-s', session, '-c', projectDir, ...herdrEnv, shellCmd, ...sidecar], session };
     }
-    // `tmux new -A`: attach if the named session exists, else create it.
-    return { kind: 'tmux-new', cmd: 'tmux', args: ['new', '-A', '-s', session, shellCmd, ...sidecar, ...(0, exports.herdrSessionArgs)(session)], session };
+    // `tmux new -A`: attach if the named session exists, else create it. `-e` applies only when it creates.
+    const herdrEnv = (0, exports.herdrEnvArgs)(agentKind, process.env, (0, exports.installedTmuxVersion)());
+    return { kind: 'tmux-new', cmd: 'tmux', args: ['new', '-A', '-s', session, ...herdrEnv, shellCmd, ...sidecar, ...(0, exports.herdrSessionArgs)(session)], session };
 };
 exports.targetForAgent = targetForAgent;
 // ── Background listener auto-start ────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hwip/cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Hwip CLI + push notification SDK for AI agents",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -43,7 +43,21 @@
       "main"
     ],
     "plugins": [
-      "@semantic-release/commit-analyzer",
+      [
+        "@semantic-release/commit-analyzer",
+        {
+          "releaseRules": [
+            {
+              "breaking": true,
+              "release": "patch"
+            },
+            {
+              "type": "feat",
+              "release": "patch"
+            }
+          ]
+        }
+      ],
       "@semantic-release/release-notes-generator",
       "@semantic-release/npm",
       "@semantic-release/github"