charness 0.0.0-stage → 3.1.0

package/dist/utils/jsonStreamHost.js

@@ -0,0 +1,438 @@
+"use strict";
+/**
+ * @description Host layout + IO primitives for the json-stream Claude backend's
+ * EXTERNAL process transport (plan 2026-07-05-jsonstream-restart-isolation).
+ *
+ * The `claude -p … stream-json` process is NOT a bot child any more: a `#!/bin/sh`
+ * wrapper hosts it inside a detached tmux session, with stdio rerouted to files
+ * under `DATA_DIR/jsonstream/<serialized key with ":" → "_">/` (Telegram:
+ * `<chatId>_<threadId>`):
+ *
+ *   stdin.fifo    ← the bot's control/user-turn writes (claude holds it `0<>`,
+ *                   i.e. open read-write on fd 0, so a bot restart — the writer
+ *                   dying — never EOFs claude's stdin; proven by the P1 probe)
+ *   stdout.jsonl  ← append-only stream-json event log the bot TAILS from a byte
+ *                   offset (deltas keep landing while the bot is down)
+ *   stderr.log    ← passive; read only for spawn-fail / exit diagnostics
+ *   pid, exitcode ← written by the wrapper; the adapter's poll tick uses them
+ *                   for exit detection (pid-alive + exitcode file)
+ *   wrapper.sh    ← the generated host script itself
+ *   question.json ← the pending AskUserQuestion control_request (written when
+ *                   surfaced, removed when resolved) so an adopt after a bot
+ *                   restart can still answer it over the FIFO
+ *
+ * Everything here is either pure decision logic (tail offsets, wrapper text,
+ * name codecs) or a thin fs primitive (FIFO open/write, pid/exitcode readers)
+ * — the orchestration lives in `adapters/claudeJsonStreamAdapter.ts`.
+ */
+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.stderrTailMaxChars = exports.stdoutOversizeWarnBytes = exports.fifoWriteRetryDelayMs = exports.fifoWriteMaxRetries = exports.fifoOpenRetryDelayMs = exports.fifoOpenMaxTries = exports.pidFilePollIntervalMs = exports.pidFileWaitTimeoutMs = exports.wrapperCdFailExitCode = exports.jsonStreamTmuxPrefix = exports.jsonStreamRootDirName = void 0;
+exports.resolveJsonStreamRoot = resolveJsonStreamRoot;
+exports.resolveJsonStreamSessionDir = resolveJsonStreamSessionDir;
+exports.parseJsonStreamDirName = parseJsonStreamDirName;
+exports.getJsonStreamSessionPaths = getJsonStreamSessionPaths;
+exports.buildJsonStreamTmuxSessionName = buildJsonStreamTmuxSessionName;
+exports.parseJsonStreamTmuxSessionName = parseJsonStreamTmuxSessionName;
+exports.buildWrapperScript = buildWrapperScript;
+exports.readWrapperScriptConfigDir = readWrapperScriptConfigDir;
+exports.openFifoWriterNonBlocking = openFifoWriterNonBlocking;
+exports.writeFifoText = writeFifoText;
+exports.readPidFile = readPidFile;
+exports.readExitCodeFile = readExitCodeFile;
+exports.checkIsPidAlive = checkIsPidAlive;
+exports.waitForPidFile = waitForPidFile;
+exports.readStderrTail = readStderrTail;
+exports.getFileSize = getFileSize;
+exports.readFileByteRange = readFileByteRange;
+exports.resolveAdoptedTail = resolveAdoptedTail;
+exports.createStdoutTailState = createStdoutTailState;
+exports.getStdoutTailDecision = getStdoutTailDecision;
+exports.decodeStdoutTailChunk = decodeStdoutTailChunk;
+exports.getStdoutLineBoundaryOffset = getStdoutLineBoundaryOffset;
+exports.sweepOrphanJsonStreamDirs = sweepOrphanJsonStreamDirs;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const string_decoder_1 = require("string_decoder");
+const promises_1 = require("timers/promises");
+const sessionKey_1 = require("../sessionKey");
+const tmuxSessionName_1 = require("./tmuxSessionName");
+const tmuxExec_1 = require("./tmuxExec");
+const claudeProfiles_1 = require("./claudeProfiles");
+/** Subdirectory of `DATA_DIR` that holds every thread's json-stream host dir. */
+exports.jsonStreamRootDirName = 'jsonstream';
+/** tmux session-name prefix for this backend — distinct from the scrape
+ *  backend's `claude` and the terminal's `term`, so adopt-at-boot scans never
+ *  cross-talk (locked decision). */
+exports.jsonStreamTmuxPrefix = 'cjson';
+/** Exit code the wrapper reports when `cd <workDir>` fails (folder vanished
+ *  between bind and spawn) — claude must never run in the wrong directory. */
+exports.wrapperCdFailExitCode = 96;
+/** How long a fresh spawn waits for the wrapper to write the `pid` file. */
+exports.pidFileWaitTimeoutMs = 5000;
+exports.pidFilePollIntervalMs = 100;
+/** FIFO write-open guard (P1 probe): `O_WRONLY|O_NONBLOCK` raises `ENXIO`
+ *  while nothing holds the read end — a BLOCKING open would hang forever.
+ *  Retried because claude opens its `0<>` end asynchronously during spawn;
+ *  `ENXIO` persisting past the retries means the process is dead. */
+exports.fifoOpenMaxTries = 10;
+exports.fifoOpenRetryDelayMs = 500;
+/** A full FIFO buffer raises `EAGAIN` on a non-blocking write — transient,
+ *  claude drains it. Bounded so a truly wedged reader can't spin forever. */
+exports.fifoWriteMaxRetries = 100;
+exports.fifoWriteRetryDelayMs = 50;
+/** No rotation in v1 (locked decision): the file is per-session and deleted on
+ *  stop/release. Past this size we log ONE warning, never rotate. */
+exports.stdoutOversizeWarnBytes = 256 * 1024 * 1024;
+/** Cap for the stderr excerpt quoted into spawn-fail / unexpected-exit logs. */
+exports.stderrTailMaxChars = 400;
+/** Absolute path of the `jsonstream/` root under a given data dir. */
+function resolveJsonStreamRoot(dataDir) {
+    return path.join(dataDir, exports.jsonStreamRootDirName);
+}
+/**
+ * @description Separator standing in for the serialized key's `:` inside a
+ * directory name — `:` is illegal on some filesystems. Same convention as
+ * `botFileStorage`'s intake dirs.
+ */
+const threadDirSeparator = '_';
+/** The per-thread host dir name — the key slug, for Telegram `<chatId>_<threadId>`. */
+function threadDirName(key) {
+    return (0, sessionKey_1.keyToSlug)(key, threadDirSeparator);
+}
+/** Absolute path of one thread's json-stream host dir. */
+function resolveJsonStreamSessionDir(dataDir, key) {
+    return path.join(resolveJsonStreamRoot(dataDir), threadDirName(key));
+}
+/**
+ * @description Inverse of the host-dir naming for the orphan-dir janitor.
+ * Strictness lives in the connector's codec (mirrors `parseTmuxSessionName`),
+ * so a foreign dir that happens to sit under `jsonstream/` is skipped, never
+ * swept by a mis-parse.
+ */
+function parseJsonStreamDirName(name) {
+    return (0, sessionKey_1.tryKeyFromSlug)(name, threadDirSeparator);
+}
+function getJsonStreamSessionPaths(dir) {
+    return {
+        dir,
+        stdinFifo: path.join(dir, 'stdin.fifo'),
+        stdoutFile: path.join(dir, 'stdout.jsonl'),
+        stderrFile: path.join(dir, 'stderr.log'),
+        pidFile: path.join(dir, 'pid'),
+        exitCodeFile: path.join(dir, 'exitcode'),
+        wrapperFile: path.join(dir, 'wrapper.sh'),
+        questionFile: path.join(dir, 'question.json'),
+    };
+}
+/** tmux session name for a json-stream thread (`cjson-<chatId>-<threadId>`). */
+function buildJsonStreamTmuxSessionName(key) {
+    return (0, tmuxSessionName_1.buildTmuxSessionName)(exports.jsonStreamTmuxPrefix, key);
+}
+/** Inverse of {@link buildJsonStreamTmuxSessionName}; `null` for foreign names. */
+function parseJsonStreamTmuxSessionName(name) {
+    return (0, tmuxSessionName_1.parseTmuxSessionName)(exports.jsonStreamTmuxPrefix, name);
+}
+/**
+ * @description The `#!/bin/sh` host script (exact shape proven by the P1 probe
+ * `p1-probe2.mjs`): background claude with its stdio rerouted to the host files,
+ * record the child pid, then `wait` and record the exit code. `0<>` opens the
+ * stdin FIFO READ-WRITE on fd 0 — the load-bearing trick: claude itself holds a
+ * read end open, so the bot (a plain writer) can die and reconnect freely.
+ * `env -u ANTHROPIC_API_KEY` keeps subscription billing (`apiKeySource:"none"`)
+ * even if the tmux server environment carries a key. With an `environment`
+ * (a tracker conversation, R32) claude gets exactly those variables instead —
+ * `env -i`, so nothing of the tmux server's environment reaches it (no API key
+ * either). A non-default Claude account profile adds `CLAUDE_CONFIG_DIR=<dir>` to
+ * either `env` form (`utils/claudeProfiles.ts`); the default profile adds nothing,
+ * so the wrapper of a topic that never picked an account is byte-identical to
+ * the golden shape. The variable sits in the process environment — not only in
+ * the CLI's own reading of it — so a child `claude` the agent starts inherits the
+ * same account. All embedded strings are single-quoted; `claudePath` must be
+ * ABSOLUTE (tmux server PATH differs).
+ */
+function buildWrapperScript(claudePath, args, workDir, paths, environment = null, configDir = null) {
+    const command = [claudePath, ...args].map(tmuxExec_1.shellSingleQuote).join(' ');
+    const configDirAssignment = configDir === null ? [] : [(0, tmuxExec_1.shellSingleQuote)(`${claudeProfiles_1.claudeConfigDirVariableName}=${configDir}`)];
+    const envCommand = environment === null
+        ? ['env', '-u', 'ANTHROPIC_API_KEY', ...configDirAssignment].join(' ')
+        : ['env', '-i', ...Object.entries(environment).map(([name, value]) => (0, tmuxExec_1.shellSingleQuote)(`${name}=${value}`)), ...configDirAssignment].join(' ');
+    return `#!/bin/sh
+cd ${(0, tmuxExec_1.shellSingleQuote)(workDir)} || exit ${exports.wrapperCdFailExitCode}
+${envCommand} ${command} \\
+  0<> ${(0, tmuxExec_1.shellSingleQuote)(paths.stdinFifo)} >> ${(0, tmuxExec_1.shellSingleQuote)(paths.stdoutFile)} 2>> ${(0, tmuxExec_1.shellSingleQuote)(paths.stderrFile)} &
+CHILD=$!
+echo $CHILD > ${(0, tmuxExec_1.shellSingleQuote)(paths.pidFile)}
+wait $CHILD
+echo $? > ${(0, tmuxExec_1.shellSingleQuote)(paths.exitCodeFile)}
+`;
+}
+/**
+ * @description The `CLAUDE_CONFIG_DIR` a persisted wrapper script starts claude with, `null` for the default
+ * profile or an unreadable script. Read at adopt: the running process keeps the account it was spawned with,
+ * and the bot compares it with the profile its topic has now.
+ */
+function readWrapperScriptConfigDir(wrapperFile) {
+    try {
+        return (0, claudeProfiles_1.parseClaudeConfigDirFromCommand)(fs.readFileSync(wrapperFile, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * @description Open the stdin FIFO for writing WITHOUT ever blocking: a plain
+ * `open(O_WRONLY)` on a FIFO with no reader hangs forever (the P1 probe's first
+ * attempt did exactly that). `O_NONBLOCK` turns "no reader" into `ENXIO`,
+ * retried on a short delay while claude is still coming up. Returns the fd, or
+ * `null` when `ENXIO` persists — i.e. the claude process is NOT holding the
+ * FIFO, so the session is dead.
+ */
+async function openFifoWriterNonBlocking(fifoPath, maxTries = exports.fifoOpenMaxTries) {
+    for (let attempt = 0; attempt < maxTries; attempt++) {
+        try {
+            return fs.openSync(fifoPath, fs.constants.O_WRONLY | fs.constants.O_NONBLOCK);
+        }
+        catch (e) {
+            if (e.code !== 'ENXIO')
+                throw e;
+            await (0, promises_1.setTimeout)(exports.fifoOpenRetryDelayMs);
+        }
+    }
+    return null;
+}
+/**
+ * @description Write `text` to a non-blocking FIFO fd, retrying transient
+ * `EAGAIN` (buffer full — claude drains it) with a bounded backoff and
+ * continuing partial writes (a payload larger than the FIFO buffer lands in
+ * chunks). Anything else (`EPIPE` after claude died, `EBADF` after close)
+ * propagates to the caller's per-session write chain, which logs it.
+ */
+async function writeFifoText(fd, text) {
+    const payload = Buffer.from(text, 'utf8');
+    let written = 0;
+    let retries = 0;
+    while (written < payload.length) {
+        try {
+            written += fs.writeSync(fd, payload, written, payload.length - written);
+        }
+        catch (e) {
+            if (e.code !== 'EAGAIN' || retries >= exports.fifoWriteMaxRetries)
+                throw e;
+            retries += 1;
+            await (0, promises_1.setTimeout)(exports.fifoWriteRetryDelayMs);
+        }
+    }
+}
+/** Parse a `pid`/`exitcode` file: strict digits, `null` for missing/garbage. */
+function readIntFile(filePath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, 'utf8').trim();
+    }
+    catch {
+        return null;
+    }
+    return /^\d+$/.test(raw) ? Number(raw) : null;
+}
+function readPidFile(pidFile) {
+    return readIntFile(pidFile);
+}
+function readExitCodeFile(exitCodeFile) {
+    return readIntFile(exitCodeFile);
+}
+/** `kill(pid, 0)` liveness probe (no signal actually delivered). */
+function checkIsPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Wait (bounded) for the wrapper to write the `pid` file after tmux spawn.
+ *  Returns the pid, or `null` on timeout (spawn diagnostics read stderr). */
+async function waitForPidFile(pidFile, timeoutMs = exports.pidFileWaitTimeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const pid = readPidFile(pidFile);
+        if (pid !== null)
+            return pid;
+        await (0, promises_1.setTimeout)(exports.pidFilePollIntervalMs);
+    }
+    return readPidFile(pidFile);
+}
+/** Last `maxChars` of the passive stderr log — spawn-fail / exit diagnostics
+ *  only (locked decision: no live stderr consumer). Empty when absent. */
+function readStderrTail(stderrFile, maxChars = exports.stderrTailMaxChars) {
+    try {
+        const raw = fs.readFileSync(stderrFile, 'utf8').trim();
+        return raw.length > maxChars ? raw.slice(-maxChars) : raw;
+    }
+    catch {
+        return '';
+    }
+}
+/** File size in bytes, or `null` when the file doesn't exist (yet). */
+function getFileSize(filePath) {
+    try {
+        return fs.statSync(filePath).size;
+    }
+    catch {
+        return null;
+    }
+}
+/** Read the byte range `[startOffset..endOffset)` of a file. May return fewer
+ *  bytes than asked on a race — the tail accounts by ACTUAL bytes consumed. */
+function readFileByteRange(filePath, startOffset, endOffset) {
+    const fd = fs.openSync(filePath, 'r');
+    try {
+        const wanted = endOffset - startOffset;
+        const buffer = Buffer.alloc(wanted);
+        const bytesRead = fs.readSync(fd, buffer, 0, wanted, startOffset);
+        return bytesRead === wanted ? buffer : buffer.subarray(0, bytesRead);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/**
+ * @description Decide where an ADOPT resumes the stdout tail. A persisted offset
+ * is trusted only when it was recorded for the SAME claude session — a foreign /
+ * unknown offset seeds to the current EOF (no backlog flood, the first-migration
+ * case) — and is clamped to the file size (an externally truncated file). The
+ * background-task list persisted with the offset is restored on the same
+ * condition: the frames that built it lie before the offset and will not
+ * replay, so without it an adopted session with a running background task
+ * would read as idle and could be stopped (L-D2). The turn-in-flight flag and
+ * the outstanding tool calls are restored the same way — a turn in a long,
+ * silent tool call leaves no frame after the offset either, and the outstanding
+ * tool is what keeps the busy-idle watchdog from clearing the restored turn.
+ */
+function resolveAdoptedTail(persistedTail, claudeSessionId, stdoutSizeBytes) {
+    if (persistedTail === null || persistedTail.sessionId !== claudeSessionId) {
+        return { startOffset: stdoutSizeBytes, backgroundTaskIds: [], isTurnInFlight: false, outstandingToolUseIds: [], claudeCodeVersion: null };
+    }
+    return {
+        startOffset: Math.min(persistedTail.offsetBytes, stdoutSizeBytes),
+        backgroundTaskIds: persistedTail.backgroundTaskIds ?? [],
+        isTurnInFlight: persistedTail.isTurnInFlight ?? false,
+        outstandingToolUseIds: persistedTail.outstandingToolUseIds ?? [],
+        claudeCodeVersion: persistedTail.claudeCodeVersion ?? null,
+    };
+}
+function createStdoutTailState(startOffsetBytes) {
+    return { consumedBytes: startOffsetBytes, decoderRetainedBytes: 0, decoder: new string_decoder_1.StringDecoder('utf8') };
+}
+/**
+ * @description Decide the next tail action. Does NOT advance offsets on a
+ * `read` — {@link decodeStdoutTailChunk} advances by the bytes ACTUALLY read,
+ * so a short read (race with a concurrent append) self-heals next poll.
+ */
+function getStdoutTailDecision(state, sizeBytes) {
+    if (sizeBytes < state.consumedBytes) {
+        state.consumedBytes = sizeBytes;
+        state.decoderRetainedBytes = 0;
+        state.decoder = new string_decoder_1.StringDecoder('utf8');
+        return { kind: 'reseed' };
+    }
+    if (sizeBytes === state.consumedBytes)
+        return { kind: 'none' };
+    return { kind: 'read', startOffset: state.consumedBytes, endOffset: sizeBytes };
+}
+/**
+ * @description Feed one appended byte chunk through the stateful utf8 decoder.
+ * Returns the decoded text (possibly empty while a multi-byte char is split);
+ * advances `consumedBytes` by the chunk length and re-derives the decoder's
+ * retained-byte count (`retainedNew = retainedPrior + chunkLen - decodedLen`,
+ * clamped defensively — invalid utf8 replacement chars could otherwise skew it
+ * negative).
+ */
+function decodeStdoutTailChunk(state, chunk) {
+    const text = state.decoder.write(chunk);
+    const retained = state.decoderRetainedBytes + chunk.length - Buffer.byteLength(text, 'utf8');
+    state.decoderRetainedBytes = Math.max(0, retained);
+    state.consumedBytes += chunk.length;
+    return text;
+}
+/**
+ * @description The byte offset up to which every COMPLETE line has been
+ * processed — the value persisted across bot restarts. `pendingLineText` is the
+ * line reader's buffered partial line (`ClaudeStreamLineReader.pending`): those
+ * bytes were consumed but not yet processed, so the persisted offset excludes
+ * them and a restarted tail re-reads exactly the unprocessed remainder.
+ */
+function getStdoutLineBoundaryOffset(state, pendingLineText) {
+    return state.consumedBytes - state.decoderRetainedBytes - Buffer.byteLength(pendingLineText, 'utf8');
+}
+/**
+ * @description Janitor: remove `jsonstream/` host dirs whose thread no longer
+ * owns a json-stream session (crash leftovers — the normal stop/release paths
+ * delete the dir themselves, and reattach handles live tmux sessions).
+ * `checkIsThreadOwned` is injected by the bot (persisted json-stream agent row
+ * with a session id, or a currently-active adapter session). Unparseable dir
+ * names are skipped, never swept. Returns the number of dirs removed. Runs at
+ * boot + the daily file sweep.
+ */
+async function sweepOrphanJsonStreamDirs(jsonStreamRoot, checkIsThreadOwned) {
+    let entries;
+    try {
+        entries = await fs.promises.readdir(jsonStreamRoot, { withFileTypes: true });
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT') {
+            console.warn(`[jsonStreamSweep] cannot read ${jsonStreamRoot}:`, e);
+        }
+        return 0;
+    }
+    let removedCount = 0;
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const key = parseJsonStreamDirName(entry.name);
+        if (!key || checkIsThreadOwned(key))
+            continue;
+        try {
+            await fs.promises.rm(path.join(jsonStreamRoot, entry.name), { recursive: true, force: true });
+            removedCount += 1;
+        }
+        catch (e) {
+            console.warn(`[jsonStreamSweep] cannot remove orphan dir ${entry.name}:`, e);
+        }
+    }
+    return removedCount;
+}
+//# sourceMappingURL=jsonStreamHost.js.map

package/dist/utils/jsonStreamHost.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonStreamHost.js","sourceRoot":"","sources":["../../src/utils/jsonStreamHost.ts"],"names":[],"mappings":"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"}

package/dist/utils/keyedTransitionQueue.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @description One session transition at a time per conversation (plan
+ * 2026-10-04-claude-process-lifecycle, L2 review / L3): a start, a resume and an
+ * idle stop of the same key are chained, never run side by side. Two triggers
+ * that hit a sleeping topic together both ask for a resume; the second runs
+ * after the first and finds the session live. A trigger that arrives while the
+ * idle stop runs waits for it, then resumes. A transition that throws does not
+ * block the next one.
+ */
+export declare class KeyedTransitionQueue {
+    /** Per key, a promise that settles (never rejects) once the last queued transition did. */
+    private readonly tails;
+    /** Run `transition` once every transition queued before it for `key` has settled. */
+    run<TResult>(key: string, transition: () => Promise<TResult>): Promise<TResult>;
+    /** Whether a transition of `key` is running or queued. */
+    checkIsInFlight(key: string): boolean;
+}
+//# sourceMappingURL=keyedTransitionQueue.d.ts.map

package/dist/utils/keyedTransitionQueue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyedTransitionQueue.d.ts","sourceRoot":"","sources":["../../src/utils/keyedTransitionQueue.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,qBAAa,oBAAoB;IAC/B,2FAA2F;IAC3F,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoC;IAE1D,qFAAqF;IACrF,GAAG,CAAC,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAW/E,0DAA0D;IAC1D,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;CAGtC"}

package/dist/utils/keyedTransitionQueue.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeyedTransitionQueue = void 0;
+/**
+ * @description One session transition at a time per conversation (plan
+ * 2026-10-04-claude-process-lifecycle, L2 review / L3): a start, a resume and an
+ * idle stop of the same key are chained, never run side by side. Two triggers
+ * that hit a sleeping topic together both ask for a resume; the second runs
+ * after the first and finds the session live. A trigger that arrives while the
+ * idle stop runs waits for it, then resumes. A transition that throws does not
+ * block the next one.
+ */
+class KeyedTransitionQueue {
+    /** Per key, a promise that settles (never rejects) once the last queued transition did. */
+    tails = new Map();
+    /** Run `transition` once every transition queued before it for `key` has settled. */
+    run(key, transition) {
+        const previous = this.tails.get(key) ?? Promise.resolve();
+        const next = previous.then(transition);
+        const settled = next.then(() => undefined, () => undefined);
+        this.tails.set(key, settled);
+        void settled.then(() => {
+            if (this.tails.get(key) === settled)
+                this.tails.delete(key);
+        });
+        return next;
+    }
+    /** Whether a transition of `key` is running or queued. */
+    checkIsInFlight(key) {
+        return this.tails.has(key);
+    }
+}
+exports.KeyedTransitionQueue = KeyedTransitionQueue;
+//# sourceMappingURL=keyedTransitionQueue.js.map

package/dist/utils/keyedTransitionQueue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyedTransitionQueue.js","sourceRoot":"","sources":["../../src/utils/keyedTransitionQueue.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;GAQG;AACH,MAAa,oBAAoB;IAC/B,2FAA2F;IAC1E,KAAK,GAAG,IAAI,GAAG,EAAyB,CAAC;IAE1D,qFAAqF;IACrF,GAAG,CAAU,GAAW,EAAE,UAAkC;QAC1D,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QAC1D,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACvC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC5D,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAC7B,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE;YACrB,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,OAAO;gBAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC9D,CAAC,CAAC,CAAC;QACH,OAAO,IAAI,CAAC;IACd,CAAC;IAED,0DAA0D;IAC1D,eAAe,CAAC,GAAW;QACzB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;CACF;AApBD,oDAoBC"}

package/dist/utils/limitEpisodeRecovery.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @description Pure layer behind the boot recovery of a usage/session-limit
+ * episode that ENDED BEFORE the bot restarted.
+ *
+ * An ARMED retry survives a restart on its own (`state.json` `apiRetries`,
+ * re-armed after reattach). An UNRECOGNISED limit error leaves nothing behind —
+ * so a topic whose agent died on a limit before the detector understood that
+ * wording just sits there, and a bot update alone does not resume it. This module
+ * reads the evidence the json-stream Claude backend leaves on disk (the terminal
+ * `result` frame at the end of its `stdout.jsonl`) and decides whether the bot
+ * should arm the limit wait itself.
+ *
+ * V1 IS JSON-STREAM ONLY, by evidence availability: the tmux-scrape backend keeps
+ * its history only in a tmux pane (already repainted by adopt time) and OpenCode's
+ * error lives in a transient SSE event, so neither has a comparable on-disk tail
+ * to re-read. Those backends recover the normal way — the next live error fires
+ * the detector.
+ *
+ * Only the decisions live here; the fs read and the `handleApiError` call stay in
+ * `bot.ts` (the apiErrorRetry pure-layer / manager split).
+ */
+import type { AgentApiErrorClass, LimitEpisodeMarker } from '../types';
+/**
+ * How much of a session's `stdout.jsonl` to read when hunting the last terminal
+ * frame. The log holds a whole session's events and can reach hundreds of MB, so
+ * only the tail is read — the terminal `result` frame is by definition the last
+ * thing written. A torn first line is simply skipped by the NDJSON parser.
+ */
+export declare const limitEpisodeTailMaxBytes: number;
+/**
+ * Max age of the stdout log for its trailing error to still count as "the episode
+ * the topic is stuck on". Older than this and the topic has moved on (or the limit
+ * window is long expired), so resurrecting it would push an unexpected prompt into
+ * a quiet topic.
+ */
+export declare const limitEpisodeMaxAgeMs: number;
+/**
+ * @description The error text the session is PARKED on, read out of a stdout
+ * tail: the last terminal `result` frame's error, or `null` when the tail ends on
+ * a healthy turn, holds no terminal frame, or shows the session moving on after
+ * the error. Reuses the adapter's own NDJSON parse + message classifier, so "what
+ * counts as a terminal error and where its text lives" has exactly one definition.
+ *
+ * Anything real written AFTER the error — the echo of a message sent to the
+ * session, the agent's text, thinking or tool frames — clears the verdict, though
+ * the turn it belongs to has no terminal frame yet. That is what a limit resume
+ * leaves in the log: the bot's own "continue" nudge and the work on it. A topic
+ * with that tail is not stuck on the old error, and re-arming it at a restart
+ * in the middle of that turn would resume the same episode a second time.
+ *
+ * Only the PARENT session's frames count. A terminal `result` ends the parent
+ * turn, so the one thing that can still write after it without a resume is a
+ * background sub-agent finishing its own work (`parent_tool_use_id` set); a
+ * resume always starts with the parent's own frames (the nudge's echo first), so
+ * leaving the sub-agent's out loses nothing and keeps a parked topic parked.
+ */
+export declare function getLastTerminalErrorText(tailText: string): string | null;
+export type LimitEpisodeDecision = 
+/** Arm the limit wait through the normal live-error path. */
+{
+    action: 'arm';
+    cls: AgentApiErrorClass;
+}
+/** Nothing to do; `reason` is for the boot log only. */
+ | {
+    action: 'skip';
+    reason: 'noError' | 'notUsageLimit' | 'stale' | 'alreadyArmed' | 'alreadyHandled';
+};
+/**
+ * @description Decide whether a session's trailing error should re-arm a limit
+ * wait at boot. Deliberately strict — every guard exists to keep a boot from
+ * pushing a surprise prompt into a topic:
+ *  - only when no persisted retry record already covers the thread (that one is
+ *    re-armed by the normal restore path — arming twice would double-notice);
+ *  - only when the log CHANGED since the episode a previous boot already handled
+ *    ({@link checkIsSameHandledLog});
+ *  - only the `usageLimit` class (a transient error is long past by restart time,
+ *    and an `auth` error needs a human, not a wait);
+ *  - only when the log is younger than {@link limitEpisodeMaxAgeMs}.
+ * A `resetAt` already in the past needs no special case: the retry plan clamps a
+ * negative delay to zero and the boot arming turns that into one prompt catch-up.
+ */
+export declare function decideLimitEpisodeRecovery(input: {
+    errorText: string | null;
+    /** Identity (size + mtime) of the session's `stdout.jsonl` right now. */
+    log: LimitEpisodeMarker;
+    /** Identity recorded when a previous boot armed from this log, if any. */
+    handled?: LimitEpisodeMarker;
+    now: number;
+    hasArmedRetry: boolean;
+}): LimitEpisodeDecision;
+//# sourceMappingURL=limitEpisodeRecovery.d.ts.map

package/dist/utils/limitEpisodeRecovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limitEpisodeRecovery.d.ts","sourceRoot":"","sources":["../../src/utils/limitEpisodeRecovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,KAAK,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAEvE;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,QAAY,CAAC;AAElD;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,QAAsB,CAAC;AAExD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAexE;AAYD,MAAM,MAAM,oBAAoB;AAC9B,6DAA6D;AAC3D;IAAE,MAAM,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,kBAAkB,CAAA;CAAE;AAC5C,wDAAwD;GACtD;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,GAAG,eAAe,GAAG,OAAO,GAAG,cAAc,GAAG,gBAAgB,CAAA;CAAE,CAAC;AAgB1G;;;;;;;;;;;;;GAaG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE;IAChD,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,yEAAyE;IACzE,GAAG,EAAE,kBAAkB,CAAC;IACxB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,EAAE,OAAO,CAAC;CACxB,GAAG,oBAAoB,CAQvB"}