charness 0.0.0-stage → 3.0.0

package/dist/utils/claudeCodeVersion.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * @description The Claude Code version gate for the json-stream lifecycle
+ * (plan 2026-10-04-claude-process-lifecycle, L-D10). A process may be stopped
+ * automatically (idle stop, per-turn stop) ONLY when its CLI reports the
+ * `system/background_tasks_changed` list — verified on 2.1.287 and never seen
+ * before it. Without that list a stop could kill background work (a background
+ * Bash, a Monitor, a background sub-agent): stdin EOF kills them ~5 s later
+ * (probe 2026-10-04). An unknown version (no `claude_code_version` on `init`)
+ * is treated as too old.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.minAutoStopClaudeCodeVersion = void 0;
+exports.compareClaudeCodeVersions = compareClaudeCodeVersions;
+exports.checkIsClaudeAutoStopSupported = checkIsClaudeAutoStopSupported;
+exports.getPerTurnRefusedVersion = getPerTurnRefusedVersion;
+/** The first Claude Code version whose stream-json reports the background-task list. */
+exports.minAutoStopClaudeCodeVersion = '2.1.287';
+const versionRe = /^(\d+)\.(\d+)\.(\d+)/;
+/** Parse `major.minor.patch` (a trailing pre-release / build suffix is ignored); `null` for anything else. */
+function parseClaudeCodeVersion(version) {
+    const match = versionRe.exec(version.trim());
+    if (!match)
+        return null;
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+/**
+ * @description Compare two `major.minor.patch` versions numerically (so `2.1.300`
+ * sorts after `2.1.287`, which a string compare gets wrong). Returns a negative
+ * number, zero, or a positive number like `Array.prototype.sort` expects; `null`
+ * when either side does not parse.
+ */
+function compareClaudeCodeVersions(left, right) {
+    const leftParts = parseClaudeCodeVersion(left);
+    const rightParts = parseClaudeCodeVersion(right);
+    if (!leftParts || !rightParts)
+        return null;
+    for (let index = 0; index < leftParts.length; index += 1) {
+        if (leftParts[index] !== rightParts[index])
+            return leftParts[index] - rightParts[index];
+    }
+    return 0;
+}
+/** Whether a process reporting `version` may be auto-stopped (L-D10); `null` / unparseable → `false`. */
+function checkIsClaudeAutoStopSupported(version) {
+    if (version === null)
+        return false;
+    const comparison = compareClaudeCodeVersions(version, exports.minAutoStopClaudeCodeVersion);
+    return comparison !== null && comparison >= 0;
+}
+/**
+ * @description The version a switch of a conversation to the per-turn lifecycle
+ * is REFUSED on (L-D10, narrowed): its last known Claude Code version — from the
+ * live process or the persisted tail record — when that is below the gate;
+ * `null` when the switch is allowed. An unknown version allows it: the refusal is
+ * only decidable once a version is known, and the stop gate keeps an unknown or
+ * old process alive anyway.
+ */
+function getPerTurnRefusedVersion(lastKnownVersion) {
+    return lastKnownVersion !== null && !checkIsClaudeAutoStopSupported(lastKnownVersion) ? lastKnownVersion : null;
+}
+//# sourceMappingURL=claudeCodeVersion.js.map

package/dist/utils/claudeCodeVersion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claudeCodeVersion.js","sourceRoot":"","sources":["../../src/utils/claudeCodeVersion.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AAoBH,8DAQC;AAGD,wEAIC;AAUD,4DAEC;AA7CD,wFAAwF;AAC3E,QAAA,4BAA4B,GAAG,SAAS,CAAC;AAEtD,MAAM,SAAS,GAAG,sBAAsB,CAAC;AAEzC,8GAA8G;AAC9G,SAAS,sBAAsB,CAAC,OAAe;IAC7C,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAC7C,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAChE,CAAC;AAED;;;;;GAKG;AACH,SAAgB,yBAAyB,CAAC,IAAY,EAAE,KAAa;IACnE,MAAM,SAAS,GAAG,sBAAsB,CAAC,IAAI,CAAC,CAAC;IAC/C,MAAM,UAAU,GAAG,sBAAsB,CAAC,KAAK,CAAC,CAAC;IACjD,IAAI,CAAC,SAAS,IAAI,CAAC,UAAU;QAAE,OAAO,IAAI,CAAC;IAC3C,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACzD,IAAI,SAAS,CAAC,KAAK,CAAC,KAAK,UAAU,CAAC,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC,KAAK,CAAC,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;IAC1F,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,yGAAyG;AACzG,SAAgB,8BAA8B,CAAC,OAAsB;IACnE,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IACnC,MAAM,UAAU,GAAG,yBAAyB,CAAC,OAAO,EAAE,oCAA4B,CAAC,CAAC;IACpF,OAAO,UAAU,KAAK,IAAI,IAAI,UAAU,IAAI,CAAC,CAAC;AAChD,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,wBAAwB,CAAC,gBAA+B;IACtE,OAAO,gBAAgB,KAAK,IAAI,IAAI,CAAC,8BAA8B,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,IAAI,CAAC;AAClH,CAAC"}

package/dist/utils/claudeCompactHook.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @description The `PreCompact` hook the bot hands every Claude session it starts,
+ * so the compaction Claude runs ON ITS OWN when the context overflows gets the
+ * same summary guidance as a bot-issued one.
+ *
+ * WHY this exists: a bot-issued compaction carries its instruction as
+ * `/compact <instruction>`, but the overflow-triggered (auto) compaction is started
+ * by the CLI itself and has no argument the bot could fill. It summarised with the
+ * default prompt: the loaded skills were not named, and the continuing session
+ * silently stopped following them. Claude Code runs `PreCompact` hooks before
+ * EVERY compaction (`trigger` `auto` and `manual`) and appends a hook's stdout to
+ * that compaction's custom instructions — measured on v2.1.289: an
+ * overflow-triggered compaction's summary opened with the line the hook printed.
+ * The hook rides `--settings <file>`, which is merged with the user's own settings
+ * and never writes to them.
+ *
+ * A bot-issued compaction already carries the same text, so the hook prints
+ * nothing when the compaction's `custom_instructions` (part of the JSON the hook
+ * reads on stdin) already contain the skills guidance — otherwise the model would
+ * get the instruction twice.
+ */
+/**
+ * Name of the hook settings file inside `DATA_DIR`. ONE file shared by every
+ * session: its content is the same for all of them, and a session that outlives
+ * the bot (json-stream) must never find it deleted under it.
+ */
+export declare const claudeCompactHookSettingsFileName = "claude-compact-hook.json";
+/**
+ * @description The instruction the hook adds to a compaction the bot did not
+ * issue: D3 + the loaded-skills guidance. No closing section — that one exists for
+ * the bot's own idle-compaction report, which an overflow compaction never feeds.
+ */
+export declare function getHookCompactionInstruction(): string;
+/**
+ * @description Build the hook's shell command: print `instruction` unless the
+ * hook's stdin (the `PreCompact` input JSON) already contains `alreadySentMarker`.
+ * The marker is matched as a fixed string against the raw JSON, so it must be text
+ * JSON leaves unescaped — the caller passes the skills guidance, and a test pins
+ * that it qualifies.
+ */
+export declare function buildPreCompactHookCommand(input: {
+    instruction: string;
+    alreadySentMarker: string;
+}): string;
+/** The `--settings` payload: one `PreCompact` command hook, no matcher (auto AND manual). */
+export declare function buildClaudeCompactHookSettings(command: string): {
+    hooks: {
+        PreCompact: Array<{
+            hooks: Array<{
+                type: 'command';
+                command: string;
+            }>;
+        }>;
+    };
+};
+/**
+ * @description Write the hook settings file and return the `--settings <path>`
+ * argument pair for a Claude launch. Rewritten on every launch (atomic rename, so
+ * a concurrently starting session never reads a half-written file) so a changed
+ * guidance reaches the next session. A write failure returns `[]` and only logs:
+ * the hook improves a summary, it must never stop an agent from starting.
+ */
+export declare function prepareClaudeCompactHookFlags(dataDir: string): string[];
+//# sourceMappingURL=claudeCompactHook.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"claudeCompactHook.d.ts","sourceRoot":"","sources":["../../src/utils/claudeCompactHook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAWH;;;;GAIG;AACH,eAAO,MAAM,iCAAiC,6BAA6B,CAAC;AAE5E;;;;GAIG;AACH,wBAAgB,4BAA4B,IAAI,MAAM,CAOrD;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;CAC3B,GAAG,MAAM,CAET;AAED,6FAA6F;AAC7F,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,MAAM,GAAG;IAC/D,KAAK,EAAE;QAAE,UAAU,EAAE,KAAK,CAAC;YAAE,KAAK,EAAE,KAAK,CAAC;gBAAE,IAAI,EAAE,SAAS,CAAC;gBAAC,OAAO,EAAE,MAAM,CAAA;aAAE,CAAC,CAAA;SAAE,CAAC,CAAA;KAAE,CAAC;CACtF,CAEA;AAED;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAiBvE"}

package/dist/utils/claudeCompactHook.js

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * @description The `PreCompact` hook the bot hands every Claude session it starts,
+ * so the compaction Claude runs ON ITS OWN when the context overflows gets the
+ * same summary guidance as a bot-issued one.
+ *
+ * WHY this exists: a bot-issued compaction carries its instruction as
+ * `/compact <instruction>`, but the overflow-triggered (auto) compaction is started
+ * by the CLI itself and has no argument the bot could fill. It summarised with the
+ * default prompt: the loaded skills were not named, and the continuing session
+ * silently stopped following them. Claude Code runs `PreCompact` hooks before
+ * EVERY compaction (`trigger` `auto` and `manual`) and appends a hook's stdout to
+ * that compaction's custom instructions — measured on v2.1.289: an
+ * overflow-triggered compaction's summary opened with the line the hook printed.
+ * The hook rides `--settings <file>`, which is merged with the user's own settings
+ * and never writes to them.
+ *
+ * A bot-issued compaction already carries the same text, so the hook prints
+ * nothing when the compaction's `custom_instructions` (part of the JSON the hook
+ * reads on stdin) already contain the skills guidance — otherwise the model would
+ * get the instruction twice.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claudeCompactHookSettingsFileName = void 0;
+exports.getHookCompactionInstruction = getHookCompactionInstruction;
+exports.buildPreCompactHookCommand = buildPreCompactHookCommand;
+exports.buildClaudeCompactHookSettings = buildClaudeCompactHookSettings;
+exports.prepareClaudeCompactHookFlags = prepareClaudeCompactHookFlags;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const compactOnIdle_1 = require("./compactOnIdle");
+const tmuxExec_1 = require("./tmuxExec");
+/**
+ * Name of the hook settings file inside `DATA_DIR`. ONE file shared by every
+ * session: its content is the same for all of them, and a session that outlives
+ * the bot (json-stream) must never find it deleted under it.
+ */
+exports.claudeCompactHookSettingsFileName = 'claude-compact-hook.json';
+/**
+ * @description The instruction the hook adds to a compaction the bot did not
+ * issue: D3 + the loaded-skills guidance. No closing section — that one exists for
+ * the bot's own idle-compaction report, which an overflow compaction never feeds.
+ */
+function getHookCompactionInstruction() {
+    return (0, compactOnIdle_1.buildCompactionInstruction)({
+        bakesSummaryGuidance: false,
+        summaryGuidance: compactOnIdle_1.compactionSummaryGuidance,
+        bakesSkillsGuidance: false,
+        skillsGuidance: compactOnIdle_1.compactionSkillsGuidance,
+    }) ?? '';
+}
+/**
+ * @description Build the hook's shell command: print `instruction` unless the
+ * hook's stdin (the `PreCompact` input JSON) already contains `alreadySentMarker`.
+ * The marker is matched as a fixed string against the raw JSON, so it must be text
+ * JSON leaves unescaped — the caller passes the skills guidance, and a test pins
+ * that it qualifies.
+ */
+function buildPreCompactHookCommand(input) {
+    return `grep -qF -e ${(0, tmuxExec_1.shellSingleQuote)(input.alreadySentMarker)} || printf '%s\\n' ${(0, tmuxExec_1.shellSingleQuote)(input.instruction)}`;
+}
+/** The `--settings` payload: one `PreCompact` command hook, no matcher (auto AND manual). */
+function buildClaudeCompactHookSettings(command) {
+    return { hooks: { PreCompact: [{ hooks: [{ type: 'command', command }] }] } };
+}
+/**
+ * @description Write the hook settings file and return the `--settings <path>`
+ * argument pair for a Claude launch. Rewritten on every launch (atomic rename, so
+ * a concurrently starting session never reads a half-written file) so a changed
+ * guidance reaches the next session. A write failure returns `[]` and only logs:
+ * the hook improves a summary, it must never stop an agent from starting.
+ */
+function prepareClaudeCompactHookFlags(dataDir) {
+    const settingsPath = path_1.default.join(dataDir, exports.claudeCompactHookSettingsFileName);
+    const command = buildPreCompactHookCommand({
+        instruction: getHookCompactionInstruction(),
+        alreadySentMarker: compactOnIdle_1.compactionSkillsGuidance,
+    });
+    const tmpPath = `${settingsPath}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        fs_1.default.mkdirSync(dataDir, { recursive: true });
+        fs_1.default.writeFileSync(tmpPath, JSON.stringify(buildClaudeCompactHookSettings(command)));
+        fs_1.default.renameSync(tmpPath, settingsPath);
+    }
+    catch (e) {
+        console.warn(`[compact-hook] cannot write ${settingsPath}:`, e);
+        try {
+            fs_1.default.unlinkSync(tmpPath);
+        }
+        catch { /* never written */ }
+        return [];
+    }
+    return ['--settings', settingsPath];
+}
+//# sourceMappingURL=claudeCompactHook.js.map

package/dist/utils/claudeCompactHook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claudeCompactHook.js","sourceRoot":"","sources":["../../src/utils/claudeCompactHook.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;;;;AAuBH,oEAOC;AASD,gEAKC;AAGD,wEAIC;AASD,sEAiBC;AA3ED,4CAAoB;AACpB,gDAAwB;AACxB,mDAIyB;AACzB,yCAA8C;AAE9C;;;;GAIG;AACU,QAAA,iCAAiC,GAAG,0BAA0B,CAAC;AAE5E;;;;GAIG;AACH,SAAgB,4BAA4B;IAC1C,OAAO,IAAA,0CAA0B,EAAC;QAChC,oBAAoB,EAAE,KAAK;QAC3B,eAAe,EAAE,yCAAyB;QAC1C,mBAAmB,EAAE,KAAK;QAC1B,cAAc,EAAE,wCAAwB;KACzC,CAAC,IAAI,EAAE,CAAC;AACX,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,0BAA0B,CAAC,KAG1C;IACC,OAAO,eAAe,IAAA,2BAAgB,EAAC,KAAK,CAAC,iBAAiB,CAAC,sBAAsB,IAAA,2BAAgB,EAAC,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC;AAC7H,CAAC;AAED,6FAA6F;AAC7F,SAAgB,8BAA8B,CAAC,OAAe;IAG5D,OAAO,EAAE,KAAK,EAAE,EAAE,UAAU,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;AAChF,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,6BAA6B,CAAC,OAAe;IAC3D,MAAM,YAAY,GAAG,cAAI,CAAC,IAAI,CAAC,OAAO,EAAE,yCAAiC,CAAC,CAAC;IAC3E,MAAM,OAAO,GAAG,0BAA0B,CAAC;QACzC,WAAW,EAAE,4BAA4B,EAAE;QAC3C,iBAAiB,EAAE,wCAAwB;KAC5C,CAAC,CAAC;IACH,MAAM,OAAO,GAAG,GAAG,YAAY,IAAI,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC;IACnE,IAAI,CAAC;QACH,YAAE,CAAC,SAAS,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3C,YAAE,CAAC,aAAa,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,8BAA8B,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QACnF,YAAE,CAAC,UAAU,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IACvC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,CAAC,IAAI,CAAC,+BAA+B,YAAY,GAAG,EAAE,CAAC,CAAC,CAAC;QAChE,IAAI,CAAC;YAAC,YAAE,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,mBAAmB,CAAC,CAAC;QAC7D,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;AACtC,CAAC"}

package/dist/utils/claudeLivenessAction.d.ts

@@ -0,0 +1,208 @@
+/**
+ * @description Pure decision for the Claude per-thread liveness loop: given the
+ * session's current busy state, whether a rolling status frame is on screen,
+ * whether real output is actively streaming, and whether this tick crossed a
+ * busy→idle edge, decide what the loop should do with the status frame.
+ *
+ * Why a separate machine (not folded into the status coalescer): the live bug
+ * (#11) is that a busy Claude session can show NOTHING in Telegram — the frame
+ * is emitted only opportunistically when a spinner line happens to be scraped,
+ * and `handleAgentOutput` DELETES it on every real output chunk. So while the
+ * agent keeps working after some output (or thinks quietly during the poll
+ * backoff) the topic looks idle/hung. The fix drives the frame off the cheap,
+ * reliable `checkIsBusy` footer signal instead of the scrape, and this pure
+ * function is the single owner of the create/tick/delete decision so the loop
+ * and `handleAgentOutput` can't thrash (delete→instant-recreate flicker / a
+ * 429 storm of editMessageText).
+ *
+ * Extracted from `bot.ts` so the rule is unit-testable without the
+ * Telegraf / tmux machinery (same pattern as `statusFlushDecision.ts`).
+ *
+ * @name ClaudeLivenessAction
+ *
+ * (S1/S2 — working-status un-freeze + pane-static idle removal, plan
+ * `2026-06-29-claude-working-status-liveness-and-idle-removal.md`: this module
+ * also owns {@link buildClaudeLivenessFrameText} — the frame text carries a live
+ * elapsed `m:ss` so a glyph-only tick is no longer the ONLY change the dedup
+ * strips — and {@link checkShouldForceIdleRemoval} — the 30s pane-static net.)
+ * @description
+ * - `create` — busy, no frame on screen, output not streaming: send a fresh
+ *   activity frame to the bottom of the topic (THE bug — recreate after an
+ *   output chunk deleted it while work continues).
+ * - `tick`   — busy, frame already present, output not streaming: re-edit it
+ *   so it reads as alive during a quiet thinking stretch / poll backoff.
+ * - `delete` — the session went idle (busy→idle edge or simply not busy) and a
+ *   frame is still on screen: remove it (idle-only removal).
+ * - `noop`   — nothing to do: output is actively streaming (let it own the
+ *   message — don't fight it), or the session is idle with no frame.
+ */
+export type ClaudeLivenessAction = 'create' | 'tick' | 'delete' | 'noop';
+export interface ClaudeLivenessActionInput {
+    /** Is the Claude session mid-turn right now (`adapter.checkIsBusy`)? */
+    isBusy: boolean;
+    /** Is a rolling status frame currently on screen for this thread? */
+    hasStatusFrame: boolean;
+    /** Is real agent output actively streaming (queued / debouncing / sending)? */
+    isOutputStreaming: boolean;
+    /**
+     * Did this tick observe a busy→idle edge? Folds into the same removal as
+     * `!isBusy`; kept explicit so a caller that tracks the edge (and tests) can
+     * assert the transition removes the frame even if a later poll flips busy
+     * back on.
+     */
+    idleTransition: boolean;
+    /**
+     * Idle-removal latch (S2): a previous tick force-removed the frame because
+     * the scraped pane went static for ≥ the idle threshold, so the agent is
+     * treated as idle until the next prompt re-arms activity. While latched the
+     * loop must NEVER `create`/`tick` a fresh working frame (it would resurrect
+     * the very status the 30s net just removed); a stray frame is cleaned up.
+     * Cleared on a new prompt / the next fresh liveness arm.
+     */
+    isSuppressed: boolean;
+}
+/**
+ * @description Decide what the Claude liveness loop should do this tick.
+ *
+ * Priority order matters:
+ *  1. Streaming output wins — never edit/delete the frame while output owns the
+ *     message (anti-thrash with `handleAgentOutput`'s delete-on-output).
+ *  2. Idle (edge or steady) with a frame still up → `delete` (idle-only removal;
+ *     a false-idle would reintroduce the gap, a false-busy a stuck spinner, so
+ *     the caller anchors `isBusy` to the footer signal that drops on idle).
+ *  3. Busy without a frame → `create` (the bug).
+ *  4. Busy with a frame → `tick` (keep it visibly alive).
+ *  5. Otherwise (idle, no frame) → `noop`.
+ */
+export declare function getClaudeLivenessAction(input: ClaudeLivenessActionInput): ClaudeLivenessAction;
+/**
+ * @description Whether the liveness loop may STOP after this tick. Kept separate
+ * from the create/tick/delete action because the stop decision must ALSO weigh
+ * the status COALESCER: `sendStatusFrame` stores `statusMessageId` only AFTER its
+ * network await, so a frame create can still be in flight on a tick that reads
+ * `hasStatusFrame === false`. Stopping then strands the just-sent frame with no
+ * loop left to delete it on idle — an orphan that lingers until the next message
+ * (live 2026-06-29: a hung "☁️ thinking …" whose final frame landed exactly as
+ * the agent went idle, so the idle tick saw no frame, stopped, and the send then
+ * resurrected one with nothing watching it).
+ *
+ * Stop ONLY when idle, no frame tracked, AND the coalescer is fully drained
+ * (nothing in flight, queued, or deferred behind a 429 cooldown). While any of
+ * those hold, keep ticking: the pending send lands, the next idle tick deletes
+ * the frame, and the loop then stops cleanly.
+ *
+ * S2 busy-onset arming grace: when the loop is armed by a freshly-forwarded
+ * prompt (not by a scrape emit), Claude has not flipped its footer busy signal
+ * yet, so the first tick reads idle. Without the grace the loop would self-stop
+ * immediately (idle, no frame, nothing pending) and never show a working frame
+ * for a long quiet think. While `withinArmingGrace`, NEVER stop — keep ticking
+ * until Claude goes busy (normal flow takes over) or the grace expires (then the
+ * idle stop applies as usual).
+ */
+export declare function getClaudeLivenessShouldStop(input: {
+    isBusy: boolean;
+    hasStatusFrame: boolean;
+    statusSendPending: boolean;
+    withinArmingGrace: boolean;
+}): boolean;
+/**
+ * @description Resolve what `sendStatusFrame` must do with a status message it
+ * just CREATED (a brand-new Telegram message id, from the no-existing-frame
+ * branch), once the create's `await` resolves.
+ *
+ * The bug this guards (#11 follow-up — orphaned/duplicate spinner frames): the
+ * status-frame lifecycle mutates `statusMessageId` across `await` boundaries
+ * from THREE concurrent paths — the liveness tick (`create`/`tick`), the scraped
+ * status coalescer, and `handleAgentOutput`'s delete-on-output. `sendStatusFrame`
+ * reads `statusMessageId` at entry but only writes the new id back AFTER its
+ * network `await`. If a `deleteStatusMessage` runs during that window it sees a
+ * still-`null` id (or a stale one), deletes nothing of the in-flight message, and
+ * the create then resurrects `statusMessageId` pointing at a message nothing will
+ * ever remove → an orphan left on screen after idle, and a second `create` (the
+ * next glyph tick) spawning a SEPARATE message instead of editing the one frame.
+ *
+ * Fix: a monotonic per-thread `generation`, bumped on every `deleteStatusMessage`.
+ * `sendStatusFrame` captures the generation before creating, and feeds it here
+ * with the generation observed after the `await`:
+ *  - unchanged  → `store`   : safe to record the new id as the single tracked frame.
+ *  - changed    → `discard` : a delete (idle / output-supersede) landed mid-create;
+ *                 the new message is already orphaned — delete it, DON'T store its id.
+ *
+ * Pure + tiny so the invariant ("delete during an in-flight create wins, no
+ * orphan, single tracked id") is unit-testable without the Telegraf/tmux stack.
+ */
+export type StatusFrameStoreDecision = 'store' | 'discard';
+export declare function getStatusFrameStoreDecision(generationAtCreateStart: number, generationNow: number): StatusFrameStoreDecision;
+/**
+ * @description Decide whether the liveness loop should RE-RENDER+SEND the
+ * working-status frame on this tick (S3 — cooldown-scaled throttle).
+ *
+ * Mirrors the relay output debounce ({@link ./outputFlushTiming.ts}): the 1s
+ * idle-CHECK tick must not turn into a per-second `editMessageText`, so a `tick`
+ * (frame already on screen) only re-sends after the throttle window. The window
+ * is the LONGER of the base refresh floor and the live remaining 429 cooldown —
+ * so while the chat is throttling, the status frame coalesces into one larger,
+ * later edit instead of piling more requests onto the storm (the status frame was
+ * ~half the 429-storm traffic, live 2026-06-29). A `create` (no frame yet) always
+ * sends so the indicator appears immediately, regardless of cooldown.
+ *
+ * Pure so the cadence rule is unit-testable without the Telegraf/tmux stack.
+ */
+export declare function checkShouldSendLivenessFrame(input: {
+    /** Is this a `create` (no frame on screen yet)? Then always send. */
+    isCreate: boolean;
+    /** Ms since the loop last sent the frame. */
+    msSinceLastSent: number;
+    /** Base refresh floor (`claudeWorkingStatusRefreshMs`). */
+    refreshMs: number;
+    /** Live remaining 429 cooldown for the chat, ms (0 when not limited). */
+    remainingCooldownMs: number;
+}): boolean;
+/**
+ * @description Build the Claude working-status frame text (S1 un-freeze).
+ *
+ * Root cause of the freeze: the loop rotated a leading spinner glyph each tick
+ * to look alive, but `getStatusFlushAction` STRIPS that lead glyph before its
+ * dedup compare — so when the scraped activity line had no ticking tail (a
+ * generic tool / "working…" indicator), the only thing changing was the part
+ * the dedup removed → every tick `skip`ped → the frame sat static for minutes,
+ * indistinguishable from a hung agent.
+ *
+ * Fix: append a live elapsed `m:ss` tail (reusing the shared {@link formatElapsed}
+ * the sub-agent status uses) anchored at `workingSince`. The elapsed advances
+ * every second and is NOT stripped by `stripLeadingSpinnerGlyph`, so a re-render
+ * a few seconds later differs after the glyph strip → the coalescer `send`s it →
+ * the frame visibly ticks. Prefers the scraped activity word (e.g. "Clauding…",
+ * lead glyph swapped for our rotating one) over `fallbackText` (a neutral
+ * localized "working…"). `workingSince === null` ⇒ no tail (defensive; the loop
+ * always sets it on a fresh turn).
+ */
+export declare function buildClaudeLivenessFrameText(input: {
+    /** Rotating heartbeat glyph for this tick (from `CLAUDE_LIVENESS_GLYPHS`). */
+    glyph: string;
+    /** Latest scraped activity line, or null when none has been seen this turn. */
+    activityText: string | null;
+    /** Already-localized neutral fallback (i18n `agent.workingIndicator`). */
+    fallbackText: string;
+    /** Epoch ms the current busy turn started, or null when not tracking. */
+    workingSince: number | null;
+    /** Now, epoch ms — the elapsed base for `m:ss`. */
+    nowMs: number;
+}): string;
+/**
+ * @description S2 hard anti-hang net: should the liveness loop FORCE-remove the
+ * working-status frame because the scraped TUI pane has gone static for too long?
+ *
+ * The frame is normally removed on the busy→idle edge (`getClaudeLivenessAction`
+ * `delete`), but that anchors on Claude's footer busy signal, which can wrongly
+ * stay "busy" after a turn ends — leaving a working status hanging for minutes
+ * (live 2026-06-29). A genuinely working agent keeps the pane changing every
+ * second (animated spinner + the TUI's own elapsed timer), so a pane that has
+ * NOT changed for `idlePaneThresholdMs` is idle regardless of the footer: remove
+ * the frame and stop the loop. `null` age (no live session) never triggers it.
+ */
+export declare function checkShouldForceIdleRemoval(input: {
+    msSincePaneChange: number | null;
+    idlePaneThresholdMs: number;
+}): boolean;
+//# sourceMappingURL=claudeLivenessAction.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"claudeLivenessAction.d.ts","sourceRoot":"","sources":["../../src/utils/claudeLivenessAction.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEzE,MAAM,WAAW,yBAAyB;IACxC,wEAAwE;IACxE,MAAM,EAAE,OAAO,CAAC;IAChB,qEAAqE;IACrE,cAAc,EAAE,OAAO,CAAC;IACxB,+EAA+E;IAC/E,iBAAiB,EAAE,OAAO,CAAC;IAC3B;;;;;OAKG;IACH,cAAc,EAAE,OAAO,CAAC;IACxB;;;;;;;OAOG;IACH,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,yBAAyB,GAAG,oBAAoB,CAU9F;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE;IACjD,MAAM,EAAE,OAAO,CAAC;IAChB,cAAc,EAAE,OAAO,CAAC;IACxB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,iBAAiB,EAAE,OAAO,CAAC;CAC5B,GAAG,OAAO,CAGV;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,MAAM,wBAAwB,GAAG,OAAO,GAAG,SAAS,CAAC;AAE3D,wBAAgB,2BAA2B,CACzC,uBAAuB,EAAE,MAAM,EAC/B,aAAa,EAAE,MAAM,GACpB,wBAAwB,CAE1B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE;IAClD,qEAAqE;IACrE,QAAQ,EAAE,OAAO,CAAC;IAClB,6CAA6C;IAC7C,eAAe,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,mBAAmB,EAAE,MAAM,CAAC;CAC7B,GAAG,OAAO,CAGV;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE;IAClD,8EAA8E;IAC9E,KAAK,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;CACf,GAAG,MAAM,CAUT;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE;IACjD,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,mBAAmB,EAAE,MAAM,CAAC;CAC7B,GAAG,OAAO,CAGV"}

package/dist/utils/claudeLivenessAction.js

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getClaudeLivenessAction = getClaudeLivenessAction;
+exports.getClaudeLivenessShouldStop = getClaudeLivenessShouldStop;
+exports.getStatusFrameStoreDecision = getStatusFrameStoreDecision;
+exports.checkShouldSendLivenessFrame = checkShouldSendLivenessFrame;
+exports.buildClaudeLivenessFrameText = buildClaudeLivenessFrameText;
+exports.checkShouldForceIdleRemoval = checkShouldForceIdleRemoval;
+const claudeScrapeShapes_1 = require("./claudeScrapeShapes");
+const subagentStatusRender_1 = require("./subagentStatusRender");
+/**
+ * @description Decide what the Claude liveness loop should do this tick.
+ *
+ * Priority order matters:
+ *  1. Streaming output wins — never edit/delete the frame while output owns the
+ *     message (anti-thrash with `handleAgentOutput`'s delete-on-output).
+ *  2. Idle (edge or steady) with a frame still up → `delete` (idle-only removal;
+ *     a false-idle would reintroduce the gap, a false-busy a stuck spinner, so
+ *     the caller anchors `isBusy` to the footer signal that drops on idle).
+ *  3. Busy without a frame → `create` (the bug).
+ *  4. Busy with a frame → `tick` (keep it visibly alive).
+ *  5. Otherwise (idle, no frame) → `noop`.
+ */
+function getClaudeLivenessAction(input) {
+    if (input.isOutputStreaming)
+        return 'noop';
+    if (!input.isBusy || input.idleTransition) {
+        return input.hasStatusFrame ? 'delete' : 'noop';
+    }
+    // Idle-removal latch (S2): the pane went static ≥ threshold this turn, so the
+    // agent is treated as idle until the next prompt. Never create/tick a fresh
+    // working frame while latched; clean up a stray one if it somehow exists.
+    if (input.isSuppressed)
+        return input.hasStatusFrame ? 'delete' : 'noop';
+    return input.hasStatusFrame ? 'tick' : 'create';
+}
+/**
+ * @description Whether the liveness loop may STOP after this tick. Kept separate
+ * from the create/tick/delete action because the stop decision must ALSO weigh
+ * the status COALESCER: `sendStatusFrame` stores `statusMessageId` only AFTER its
+ * network await, so a frame create can still be in flight on a tick that reads
+ * `hasStatusFrame === false`. Stopping then strands the just-sent frame with no
+ * loop left to delete it on idle — an orphan that lingers until the next message
+ * (live 2026-06-29: a hung "☁️ thinking …" whose final frame landed exactly as
+ * the agent went idle, so the idle tick saw no frame, stopped, and the send then
+ * resurrected one with nothing watching it).
+ *
+ * Stop ONLY when idle, no frame tracked, AND the coalescer is fully drained
+ * (nothing in flight, queued, or deferred behind a 429 cooldown). While any of
+ * those hold, keep ticking: the pending send lands, the next idle tick deletes
+ * the frame, and the loop then stops cleanly.
+ *
+ * S2 busy-onset arming grace: when the loop is armed by a freshly-forwarded
+ * prompt (not by a scrape emit), Claude has not flipped its footer busy signal
+ * yet, so the first tick reads idle. Without the grace the loop would self-stop
+ * immediately (idle, no frame, nothing pending) and never show a working frame
+ * for a long quiet think. While `withinArmingGrace`, NEVER stop — keep ticking
+ * until Claude goes busy (normal flow takes over) or the grace expires (then the
+ * idle stop applies as usual).
+ */
+function getClaudeLivenessShouldStop(input) {
+    if (input.withinArmingGrace)
+        return false;
+    return !input.isBusy && !input.hasStatusFrame && !input.statusSendPending;
+}
+function getStatusFrameStoreDecision(generationAtCreateStart, generationNow) {
+    return generationAtCreateStart === generationNow ? 'store' : 'discard';
+}
+/**
+ * @description Decide whether the liveness loop should RE-RENDER+SEND the
+ * working-status frame on this tick (S3 — cooldown-scaled throttle).
+ *
+ * Mirrors the relay output debounce ({@link ./outputFlushTiming.ts}): the 1s
+ * idle-CHECK tick must not turn into a per-second `editMessageText`, so a `tick`
+ * (frame already on screen) only re-sends after the throttle window. The window
+ * is the LONGER of the base refresh floor and the live remaining 429 cooldown —
+ * so while the chat is throttling, the status frame coalesces into one larger,
+ * later edit instead of piling more requests onto the storm (the status frame was
+ * ~half the 429-storm traffic, live 2026-06-29). A `create` (no frame yet) always
+ * sends so the indicator appears immediately, regardless of cooldown.
+ *
+ * Pure so the cadence rule is unit-testable without the Telegraf/tmux stack.
+ */
+function checkShouldSendLivenessFrame(input) {
+    if (input.isCreate)
+        return true;
+    return input.msSinceLastSent >= Math.max(input.refreshMs, input.remainingCooldownMs);
+}
+/**
+ * @description Build the Claude working-status frame text (S1 un-freeze).
+ *
+ * Root cause of the freeze: the loop rotated a leading spinner glyph each tick
+ * to look alive, but `getStatusFlushAction` STRIPS that lead glyph before its
+ * dedup compare — so when the scraped activity line had no ticking tail (a
+ * generic tool / "working…" indicator), the only thing changing was the part
+ * the dedup removed → every tick `skip`ped → the frame sat static for minutes,
+ * indistinguishable from a hung agent.
+ *
+ * Fix: append a live elapsed `m:ss` tail (reusing the shared {@link formatElapsed}
+ * the sub-agent status uses) anchored at `workingSince`. The elapsed advances
+ * every second and is NOT stripped by `stripLeadingSpinnerGlyph`, so a re-render
+ * a few seconds later differs after the glyph strip → the coalescer `send`s it →
+ * the frame visibly ticks. Prefers the scraped activity word (e.g. "Clauding…",
+ * lead glyph swapped for our rotating one) over `fallbackText` (a neutral
+ * localized "working…"). `workingSince === null` ⇒ no tail (defensive; the loop
+ * always sets it on a fresh turn).
+ */
+function buildClaudeLivenessFrameText(input) {
+    const elapsedSuffix = input.workingSince === null ? '' : ` · ${(0, subagentStatusRender_1.formatElapsed)(input.nowMs - input.workingSince)}`;
+    const activity = input.activityText?.trim();
+    if (activity) {
+        // Swap the scrape's own leading spinner glyph for our rotating one so the
+        // heartbeat shows while preserving the activity word + any scraped tail.
+        return `${input.glyph} ${(0, claudeScrapeShapes_1.stripLeadingSpinnerGlyph)(activity)}${elapsedSuffix}`;
+    }
+    return `${input.fallbackText}${elapsedSuffix}`;
+}
+/**
+ * @description S2 hard anti-hang net: should the liveness loop FORCE-remove the
+ * working-status frame because the scraped TUI pane has gone static for too long?
+ *
+ * The frame is normally removed on the busy→idle edge (`getClaudeLivenessAction`
+ * `delete`), but that anchors on Claude's footer busy signal, which can wrongly
+ * stay "busy" after a turn ends — leaving a working status hanging for minutes
+ * (live 2026-06-29). A genuinely working agent keeps the pane changing every
+ * second (animated spinner + the TUI's own elapsed timer), so a pane that has
+ * NOT changed for `idlePaneThresholdMs` is idle regardless of the footer: remove
+ * the frame and stop the loop. `null` age (no live session) never triggers it.
+ */
+function checkShouldForceIdleRemoval(input) {
+    if (input.msSincePaneChange === null)
+        return false;
+    return input.msSincePaneChange >= input.idlePaneThresholdMs;
+}
+//# sourceMappingURL=claudeLivenessAction.js.map

package/dist/utils/claudeLivenessAction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claudeLivenessAction.js","sourceRoot":"","sources":["../../src/utils/claudeLivenessAction.ts"],"names":[],"mappings":";;AAiFA,0DAUC;AA0BD,kEAQC;AA8BD,kEAKC;AAiBD,oEAYC;AAqBD,oEAqBC;AAcD,kEAMC;AA3PD,6DAAgE;AAChE,iEAAuD;AAmEvD;;;;;;;;;;;;GAYG;AACH,SAAgB,uBAAuB,CAAC,KAAgC;IACtE,IAAI,KAAK,CAAC,iBAAiB;QAAE,OAAO,MAAM,CAAC;IAC3C,IAAI,CAAC,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,cAAc,EAAE,CAAC;QAC1C,OAAO,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC;IAClD,CAAC;IACD,8EAA8E;IAC9E,4EAA4E;IAC5E,0EAA0E;IAC1E,IAAI,KAAK,CAAC,YAAY;QAAE,OAAO,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC;IACxE,OAAO,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC;AAClD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,SAAgB,2BAA2B,CAAC,KAK3C;IACC,IAAI,KAAK,CAAC,iBAAiB;QAAE,OAAO,KAAK,CAAC;IAC1C,OAAO,CAAC,KAAK,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,cAAc,IAAI,CAAC,KAAK,CAAC,iBAAiB,CAAC;AAC5E,CAAC;AA8BD,SAAgB,2BAA2B,CACzC,uBAA+B,EAC/B,aAAqB;IAErB,OAAO,uBAAuB,KAAK,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AACzE,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAgB,4BAA4B,CAAC,KAS5C;IACC,IAAI,KAAK,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAChC,OAAO,KAAK,CAAC,eAAe,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,mBAAmB,CAAC,CAAC;AACvF,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,4BAA4B,CAAC,KAW5C;IACC,MAAM,aAAa,GACjB,KAAK,CAAC,YAAY,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,IAAA,oCAAa,EAAC,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,YAAY,CAAC,EAAE,CAAC;IAC7F,MAAM,QAAQ,GAAG,KAAK,CAAC,YAAY,EAAE,IAAI,EAAE,CAAC;IAC5C,IAAI,QAAQ,EAAE,CAAC;QACb,0EAA0E;QAC1E,yEAAyE;QACzE,OAAO,GAAG,KAAK,CAAC,KAAK,IAAI,IAAA,6CAAwB,EAAC,QAAQ,CAAC,GAAG,aAAa,EAAE,CAAC;IAChF,CAAC;IACD,OAAO,GAAG,KAAK,CAAC,YAAY,GAAG,aAAa,EAAE,CAAC;AACjD,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,2BAA2B,CAAC,KAG3C;IACC,IAAI,KAAK,CAAC,iBAAiB,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IACnD,OAAO,KAAK,CAAC,iBAAiB,IAAI,KAAK,CAAC,mBAAmB,CAAC;AAC9D,CAAC"}