charness 0.0.0-stage → 3.0.0

package/dist/utils/identicalOutputGuard.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * @description Per-thread defense-in-depth backstop against a runaway flood of
+ * byte-identical PERMANENT output.
+ *
+ * WHY it exists (flood 2026-06-16): a Claude tmux-scrape topic emitted a
+ * box-drawing table ~500 times, one byte-identical copy every ~12s for >2h.
+ * The root cause was fixed at the table emit path (S1, `recentRelayWindow`'s
+ * block-level dedup), but ANY emit path that re-sends the same large block —
+ * present or future, either backend — should not be able to flood a topic.
+ * This guard caps that regardless of which path produced the output: if a fresh
+ * permanent output is byte-identical to one recently sent to the SAME thread, it
+ * is suppressed.
+ *
+ * Deliberately NARROW to avoid false positives:
+ *  - only LARGE blocks ({@link identicalOutputMinChars}) are guarded — short
+ *    answers ("done", "yes", a one-line confirmation) legitimately repeat and
+ *    always pass;
+ *  - only within a short TIME window ({@link identicalOutputWindowMs}) and the
+ *    last few outputs ({@link identicalOutputWindowSize}) — a deliberate
+ *    re-print minutes apart is not a flood and passes;
+ *  - it is the BACKSTOP, not the primary fix: byte-identical only, never a
+ *    fuzzy match, so a genuinely-changed block (a cell flipped, a row added) is
+ *    different text and always passes.
+ *
+ * The continuation / status / transient / question exclusions are the caller's
+ * (`bot.ts` handleAgentOutput) — this guard only ever sees fresh permanent
+ * output text + the current time. State is reset at the same per-thread
+ * teardown points as the other relay state (session stop / closed / unbind).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.identicalOutputMinChars = exports.identicalOutputWindowMs = exports.identicalOutputWindowSize = void 0;
+exports.checkIsIdenticalOutputRepeat = checkIsIdenticalOutputRepeat;
+exports.recordRecentOutput = recordRecentOutput;
+exports.createIdenticalOutputGuard = createIdenticalOutputGuard;
+/** Last N permanent outputs per thread kept for the identical-repeat check. */
+exports.identicalOutputWindowSize = 5;
+/** Only an identical output within this time window is treated as a flood. */
+exports.identicalOutputWindowMs = 60_000;
+/**
+ * Minimum candidate length (chars) to be guarded at all. Short answers repeat
+ * legitimately far too often to ever suppress — only LARGE blocks (a re-printed
+ * table, a re-rendered file dump) can flood meaningfully.
+ */
+exports.identicalOutputMinChars = 200;
+/**
+ * @description Pure decision: is `candidate` a byte-identical repeat of a recent
+ * permanent output still inside the window? Short candidates (< {@link
+ * identicalOutputMinChars}) always return false. Only records within {@link
+ * identicalOutputWindowMs} of `nowMs` count — an older identical output has
+ * already aged out and is not a flood.
+ */
+function checkIsIdenticalOutputRepeat(candidate, recentOutputs, nowMs) {
+    if (candidate.length < exports.identicalOutputMinChars)
+        return false;
+    for (const record of recentOutputs) {
+        if (nowMs - record.sentAtMs > exports.identicalOutputWindowMs)
+            continue;
+        if (record.text === candidate)
+            return true;
+    }
+    return false;
+}
+/**
+ * @description Append a permanent output to a thread's bounded recent-output
+ * history (newest last), evicting the oldest beyond {@link
+ * identicalOutputWindowSize}. Returns a NEW array (pure) so callers store the
+ * result. Outputs below {@link identicalOutputMinChars} are not recorded — they
+ * are never guarded, so they would only waste a slot.
+ */
+function recordRecentOutput(recentOutputs, text, sentAtMs) {
+    if (text.length < exports.identicalOutputMinChars)
+        return [...recentOutputs];
+    const next = [...recentOutputs, { text, sentAtMs }];
+    if (next.length > exports.identicalOutputWindowSize)
+        next.splice(0, next.length - exports.identicalOutputWindowSize);
+    return next;
+}
+/**
+ * @description Create an empty identical-output guard. `nowMs` is supplied per
+ * call (not read from `Date.now()` here) so tests can drive the time window
+ * deterministically.
+ */
+function createIdenticalOutputGuard() {
+    const historyByThread = new Map();
+    return {
+        checkAndRecord(threadKey, text, nowMs) {
+            const history = historyByThread.get(threadKey) ?? [];
+            if (checkIsIdenticalOutputRepeat(text, history, nowMs))
+                return true;
+            historyByThread.set(threadKey, recordRecentOutput(history, text, nowMs));
+            return false;
+        },
+        reset(threadKey) {
+            historyByThread.delete(threadKey);
+        },
+    };
+}
+//# sourceMappingURL=identicalOutputGuard.js.map

package/dist/utils/identicalOutputGuard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identicalOutputGuard.js","sourceRoot":"","sources":["../../src/utils/identicalOutputGuard.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;;;AA4BH,oEAWC;AASD,gDASC;AAwBD,gEAcC;AA7FD,+EAA+E;AAClE,QAAA,yBAAyB,GAAG,CAAC,CAAC;AAE3C,8EAA8E;AACjE,QAAA,uBAAuB,GAAG,MAAM,CAAC;AAE9C;;;;GAIG;AACU,QAAA,uBAAuB,GAAG,GAAG,CAAC;AAQ3C;;;;;;GAMG;AACH,SAAgB,4BAA4B,CAC1C,SAAiB,EACjB,aAA4C,EAC5C,KAAa;IAEb,IAAI,SAAS,CAAC,MAAM,GAAG,+BAAuB;QAAE,OAAO,KAAK,CAAC;IAC7D,KAAK,MAAM,MAAM,IAAI,aAAa,EAAE,CAAC;QACnC,IAAI,KAAK,GAAG,MAAM,CAAC,QAAQ,GAAG,+BAAuB;YAAE,SAAS;QAChE,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;IAC7C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,kBAAkB,CAChC,aAA4C,EAC5C,IAAY,EACZ,QAAgB;IAEhB,IAAI,IAAI,CAAC,MAAM,GAAG,+BAAuB;QAAE,OAAO,CAAC,GAAG,aAAa,CAAC,CAAC;IACrE,MAAM,IAAI,GAAG,CAAC,GAAG,aAAa,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;IACpD,IAAI,IAAI,CAAC,MAAM,GAAG,iCAAyB;QAAE,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,GAAG,iCAAyB,CAAC,CAAC;IACrG,OAAO,IAAI,CAAC;AACd,CAAC;AAmBD;;;;GAIG;AACH,SAAgB,0BAA0B;IACxC,MAAM,eAAe,GAAG,IAAI,GAAG,EAAgC,CAAC;IAEhE,OAAO;QACL,cAAc,CAAC,SAAiB,EAAE,IAAY,EAAE,KAAa;YAC3D,MAAM,OAAO,GAAG,eAAe,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;YACrD,IAAI,4BAA4B,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC;gBAAE,OAAO,IAAI,CAAC;YACpE,eAAe,CAAC,GAAG,CAAC,SAAS,EAAE,kBAAkB,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;YACzE,OAAO,KAAK,CAAC;QACf,CAAC;QACD,KAAK,CAAC,SAAiB;YACrB,eAAe,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACpC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/utils/isoTimestamp.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @description Pure formatter for the `/timestamps` prompt injection: an
+ * ISO-8601 wall-clock timestamp carrying the host's LOCAL UTC offset
+ * (`2026-06-27T19:42:10+04:00`), never the `Z` suffix `toISOString()` emits.
+ * The agent-facing use case is absolute-time context for long multi-day
+ * sessions ("yesterday", "2-3 days ago"), so the operator's local clock — not
+ * UTC — is the meaningful frame of reference.
+ */
+/**
+ * @description Format an epoch-ms instant as local-offset ISO-8601, second
+ * precision: `YYYY-MM-DDTHH:mm:ss±HH:MM`. Uses the host timezone in effect for
+ * that instant (DST-correct — the offset comes from the Date itself), so
+ * parsing the result back yields the same instant.
+ */
+export declare function formatIsoLocalOffset(epochMs: number): string;
+//# sourceMappingURL=isoTimestamp.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"isoTimestamp.d.ts","sourceRoot":"","sources":["../../src/utils/isoTimestamp.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAW5D"}

package/dist/utils/isoTimestamp.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * @description Pure formatter for the `/timestamps` prompt injection: an
+ * ISO-8601 wall-clock timestamp carrying the host's LOCAL UTC offset
+ * (`2026-06-27T19:42:10+04:00`), never the `Z` suffix `toISOString()` emits.
+ * The agent-facing use case is absolute-time context for long multi-day
+ * sessions ("yesterday", "2-3 days ago"), so the operator's local clock — not
+ * UTC — is the meaningful frame of reference.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatIsoLocalOffset = formatIsoLocalOffset;
+const minutesPerHour = 60;
+/** Zero-pad a calendar/clock component to two digits. */
+function padTwo(value) {
+    return value.toString().padStart(2, '0');
+}
+/**
+ * @description Format an epoch-ms instant as local-offset ISO-8601, second
+ * precision: `YYYY-MM-DDTHH:mm:ss±HH:MM`. Uses the host timezone in effect for
+ * that instant (DST-correct — the offset comes from the Date itself), so
+ * parsing the result back yields the same instant.
+ */
+function formatIsoLocalOffset(epochMs) {
+    const date = new Date(epochMs);
+    const offsetTotalMinutes = -date.getTimezoneOffset();
+    const offsetSign = offsetTotalMinutes >= 0 ? '+' : '-';
+    const offsetAbsMinutes = Math.abs(offsetTotalMinutes);
+    const offsetHours = Math.floor(offsetAbsMinutes / minutesPerHour);
+    const offsetMinutes = offsetAbsMinutes % minutesPerHour;
+    const datePart = `${date.getFullYear()}-${padTwo(date.getMonth() + 1)}-${padTwo(date.getDate())}`;
+    const timePart = `${padTwo(date.getHours())}:${padTwo(date.getMinutes())}:${padTwo(date.getSeconds())}`;
+    return `${datePart}T${timePart}${offsetSign}${padTwo(offsetHours)}:${padTwo(offsetMinutes)}`;
+}
+//# sourceMappingURL=isoTimestamp.js.map

package/dist/utils/isoTimestamp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"isoTimestamp.js","sourceRoot":"","sources":["../../src/utils/isoTimestamp.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AAeH,oDAWC;AAxBD,MAAM,cAAc,GAAG,EAAE,CAAC;AAE1B,yDAAyD;AACzD,SAAS,MAAM,CAAC,KAAa;IAC3B,OAAO,KAAK,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;GAKG;AACH,SAAgB,oBAAoB,CAAC,OAAe;IAClD,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC;IAC/B,MAAM,kBAAkB,GAAG,CAAC,IAAI,CAAC,iBAAiB,EAAE,CAAC;IACrD,MAAM,UAAU,GAAG,kBAAkB,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;IACvD,MAAM,gBAAgB,GAAG,IAAI,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;IACtD,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,gBAAgB,GAAG,cAAc,CAAC,CAAC;IAClE,MAAM,aAAa,GAAG,gBAAgB,GAAG,cAAc,CAAC;IAExD,MAAM,QAAQ,GAAG,GAAG,IAAI,CAAC,WAAW,EAAE,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;IAClG,MAAM,QAAQ,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,EAAE,CAAC;IACxG,OAAO,GAAG,QAAQ,IAAI,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC,WAAW,CAAC,IAAI,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC;AAC/F,CAAC"}

package/dist/utils/jsonStreamBusyWatchdog.d.ts

@@ -0,0 +1,130 @@
+/**
+ * @description Pure idle-watchdog decision for the `claude-json-stream` adapter's
+ * `isBusy` flag — the flag that (via `checkIsBusy` → `checkShouldKeepTyping`)
+ * keeps the native Telegram "agent is typing…" indicator alive.
+ *
+ * ROOT-CAUSE CONTEXT. In `claudeJsonStreamAdapter` `isBusy` has exactly ONE
+ * clear-point: a processed terminal `result` line (`handleTurnEnd`). Every other
+ * event only ever SETS it (`sendInput`, a text/thinking delta, a `tool_use`, a
+ * surfaced question). So if that single `result` is ever missed — an `interrupt`
+ * the CLI aborts without a final `result`, a process that goes quiet after the
+ * answer, a `result` shape a newer CLI stops emitting — `isBusy` sticks `true`
+ * forever and the typing indicator hangs. Observed live: an otherwise-idle topic
+ * firing `sendChatAction('typing')` every 4s for an hour+ after the agent was
+ * already done. The typing loop self-stops only when `checkShouldKeepTyping`
+ * (`isBusy || isOutputStreaming`) goes false and has NO absolute bound, so a
+ * single stuck flag is unbounded.
+ *
+ * This is the bounded safety net: when the session is flagged busy but stdout has
+ * been SILENT for {@link busyIdleWatchdogMs} AND nothing is genuinely in flight
+ * (no outstanding tool, no active sub-agent, no pending user question, no
+ * un-emitted answer batch), the turn has really ended — clear `isBusy`.
+ *
+ * SILENCE — not wall-clock since the turn started — is the signal, so a
+ * legitimately long turn is NEVER cut short: a working agent is always doing one
+ * of (a) streaming text/thinking deltas → stdout activity, (b) waiting on a tool
+ * → `outstandingToolCount > 0`, (c) waiting on a sub-agent → `subagentActive`,
+ * (d) waiting on the user → `hasPendingQuestion`. Each of those VETOES the clear.
+ * The watchdog can therefore only fire once the work is provably done but the
+ * terminal `result` never arrived.
+ */
+/**
+ * @description How long stdout may be silent, with nothing in flight, before a
+ * busy session is force-declared idle. Comfortably longer than the only silent
+ * gap a working-yet-nothing-in-flight turn has (pre-first-token latency), far
+ * shorter than the reported hour+ hang.
+ */
+export declare const busyIdleWatchdogMs = 120000;
+export interface BusyIdleWatchdogInput {
+    /** Is the session currently flagged busy (drives the typing indicator)? */
+    isBusy: boolean;
+    /** ms since the last stdout byte was consumed for this session. */
+    msSinceStdoutActivity: number;
+    /** The silence threshold (injected so tests need no fake clock). */
+    idleTimeoutMs: number;
+    /** Tool calls started but whose `tool_result` hasn't returned (Bash/Read/Task/…). */
+    outstandingToolCount: number;
+    /** A sub-agent delegation is mid-flight. */
+    subagentActive: boolean;
+    /** A user question is awaiting an answer. */
+    hasPendingQuestion: boolean;
+    /** Answer text still sits un-emitted in the coalesce batch. */
+    hasUnflushedAnswer: boolean;
+}
+/**
+ * @description True iff a busy session should be force-cleared to idle: it is
+ * busy, stdout has been silent past the threshold, and every "in flight" signal
+ * is absent. Any single in-flight signal (tool / sub-agent / question / batched
+ * answer) VETOES the clear so a legitimately mid-turn agent is never truncated.
+ */
+export declare function checkShouldClearBusyOnIdle(input: BusyIdleWatchdogInput): boolean;
+/**
+ * @description How long stdout may be silent before a compaction the CLI never
+ * confirmed is declared dead. Same signal, same reasoning as
+ * {@link busyIdleWatchdogMs}: while it compacts, the CLI heartbeats
+ * `system/status status:"compacting"` every few seconds, so real silence this long
+ * means the process is gone — not that it is thinking.
+ */
+export declare const compactionSilenceTimeoutMs = 120000;
+/**
+ * @description Absolute backstop on one compaction wait. Only reachable by a CLI
+ * that keeps talking forever without ever finishing (a retry loop), which silence
+ * alone cannot catch; without it the caller's promise — and with it the
+ * "a compaction is running" guard — would never settle.
+ */
+export declare const compactionAbsoluteTimeoutMs: number;
+/** How often the compaction wait re-evaluates its verdict. */
+export declare const compactionWaitPollMs = 15000;
+export type CompactionWaitVerdict = 'keepWaiting' | 'timedOutSilent' | 'timedOutTotal';
+/** How a timed-out wait is REPORTED (decided by {@link getCompactionTimeoutOutcome}). */
+export type CompactionTimeoutOutcome = 
+/** It demonstrably worked; only the frame carrying the token counts is missing. */
+{
+    kind: 'succeededWithoutTokenCounts';
+} | {
+    kind: 'failed';
+    reason: 'silent' | 'total';
+};
+/**
+ * @description What a timed-out compaction wait should report.
+ *
+ * `sawSuccess` means the CLI already sent `compact_status success` and only the
+ * boundary frame (which carries the pre/post token counts) never followed. The
+ * context IS compacted at that point, so reporting failure would suppress the
+ * notice over an already-compacted session and leave the operator with the same
+ * silence this whole fix exists to remove. Token counts are a diagnostic; the
+ * compaction is the outcome.
+ */
+export declare function getCompactionTimeoutOutcome(input: {
+    verdict: Exclude<CompactionWaitVerdict, 'keepWaiting'>;
+    sawSuccess: boolean;
+}): CompactionTimeoutOutcome;
+/**
+ * @description Decide whether to keep waiting for a compaction to confirm.
+ *
+ * ROOT-CAUSE CONTEXT. This wait used to be a flat 3-minute cap on TOTAL elapsed
+ * time, and it produced the operator's report that idle compaction "runs but never
+ * says so": the compaction fired, the CLI compacted successfully, and the bot had
+ * already given up and posted nothing. Measured on the real session that exposed
+ * it — `compact_metadata.duration_ms: 195649`, i.e. 3 min 15.6 s against a 180 s
+ * cap, missing by 15 seconds. Elapsed time is the wrong bound: how long a summary
+ * takes scales with the context being summarised, so ANY fixed cap is a guess that
+ * a big enough session beats, and compact-on-idle exists precisely FOR big
+ * sessions — the bound was guaranteed to fail exactly where the feature matters.
+ *
+ * So silence decides instead, and the absolute cap survives only as a backstop
+ * against a CLI that never finishes at all. Silence is checked FIRST: for a dead
+ * process both bounds can be past, and "still talking, never finished" would be
+ * the wrong report.
+ */
+export declare function getCompactionWaitVerdict(input: {
+    /** ms since the last stdout byte was consumed for this session. */
+    msSinceStdoutActivity: number;
+    /** ms since the `/compact` turn was written to stdin. */
+    msSinceCompactionStarted: number;
+    /** Silence threshold (injected so tests need no fake clock). */
+    silenceTimeoutMs: number;
+    /** Absolute backstop (injected for the same reason). */
+    absoluteTimeoutMs: number;
+}): CompactionWaitVerdict;
+//# sourceMappingURL=jsonStreamBusyWatchdog.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"jsonStreamBusyWatchdog.d.ts","sourceRoot":"","sources":["../../src/utils/jsonStreamBusyWatchdog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,SAAU,CAAC;AAE1C,MAAM,WAAW,qBAAqB;IACpC,2EAA2E;IAC3E,MAAM,EAAE,OAAO,CAAC;IAChB,mEAAmE;IACnE,qBAAqB,EAAE,MAAM,CAAC;IAC9B,oEAAoE;IACpE,aAAa,EAAE,MAAM,CAAC;IACtB,qFAAqF;IACrF,oBAAoB,EAAE,MAAM,CAAC;IAC7B,4CAA4C;IAC5C,cAAc,EAAE,OAAO,CAAC;IACxB,6CAA6C;IAC7C,kBAAkB,EAAE,OAAO,CAAC;IAC5B,+DAA+D;IAC/D,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAQhF;AAED;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,SAAU,CAAC;AAElD;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,QAAiB,CAAC;AAE1D,8DAA8D;AAC9D,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAE3C,MAAM,MAAM,qBAAqB,GAAG,aAAa,GAAG,gBAAgB,GAAG,eAAe,CAAC;AAEvF,yFAAyF;AACzF,MAAM,MAAM,wBAAwB;AAClC,mFAAmF;AACjF;IAAE,IAAI,EAAE,6BAA6B,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,QAAQ,GAAG,OAAO,CAAA;CAAE,CAAC;AAEnD;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE;IACjD,OAAO,EAAE,OAAO,CAAC,qBAAqB,EAAE,aAAa,CAAC,CAAC;IACvD,UAAU,EAAE,OAAO,CAAC;CACrB,GAAG,wBAAwB,CAG3B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC9C,mEAAmE;IACnE,qBAAqB,EAAE,MAAM,CAAC;IAC9B,yDAAyD;IACzD,wBAAwB,EAAE,MAAM,CAAC;IACjC,gEAAgE;IAChE,gBAAgB,EAAE,MAAM,CAAC;IACzB,wDAAwD;IACxD,iBAAiB,EAAE,MAAM,CAAC;CAC3B,GAAG,qBAAqB,CAIxB"}

package/dist/utils/jsonStreamBusyWatchdog.js

@@ -0,0 +1,122 @@
+"use strict";
+/**
+ * @description Pure idle-watchdog decision for the `claude-json-stream` adapter's
+ * `isBusy` flag — the flag that (via `checkIsBusy` → `checkShouldKeepTyping`)
+ * keeps the native Telegram "agent is typing…" indicator alive.
+ *
+ * ROOT-CAUSE CONTEXT. In `claudeJsonStreamAdapter` `isBusy` has exactly ONE
+ * clear-point: a processed terminal `result` line (`handleTurnEnd`). Every other
+ * event only ever SETS it (`sendInput`, a text/thinking delta, a `tool_use`, a
+ * surfaced question). So if that single `result` is ever missed — an `interrupt`
+ * the CLI aborts without a final `result`, a process that goes quiet after the
+ * answer, a `result` shape a newer CLI stops emitting — `isBusy` sticks `true`
+ * forever and the typing indicator hangs. Observed live: an otherwise-idle topic
+ * firing `sendChatAction('typing')` every 4s for an hour+ after the agent was
+ * already done. The typing loop self-stops only when `checkShouldKeepTyping`
+ * (`isBusy || isOutputStreaming`) goes false and has NO absolute bound, so a
+ * single stuck flag is unbounded.
+ *
+ * This is the bounded safety net: when the session is flagged busy but stdout has
+ * been SILENT for {@link busyIdleWatchdogMs} AND nothing is genuinely in flight
+ * (no outstanding tool, no active sub-agent, no pending user question, no
+ * un-emitted answer batch), the turn has really ended — clear `isBusy`.
+ *
+ * SILENCE — not wall-clock since the turn started — is the signal, so a
+ * legitimately long turn is NEVER cut short: a working agent is always doing one
+ * of (a) streaming text/thinking deltas → stdout activity, (b) waiting on a tool
+ * → `outstandingToolCount > 0`, (c) waiting on a sub-agent → `subagentActive`,
+ * (d) waiting on the user → `hasPendingQuestion`. Each of those VETOES the clear.
+ * The watchdog can therefore only fire once the work is provably done but the
+ * terminal `result` never arrived.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compactionWaitPollMs = exports.compactionAbsoluteTimeoutMs = exports.compactionSilenceTimeoutMs = exports.busyIdleWatchdogMs = void 0;
+exports.checkShouldClearBusyOnIdle = checkShouldClearBusyOnIdle;
+exports.getCompactionTimeoutOutcome = getCompactionTimeoutOutcome;
+exports.getCompactionWaitVerdict = getCompactionWaitVerdict;
+/**
+ * @description How long stdout may be silent, with nothing in flight, before a
+ * busy session is force-declared idle. Comfortably longer than the only silent
+ * gap a working-yet-nothing-in-flight turn has (pre-first-token latency), far
+ * shorter than the reported hour+ hang.
+ */
+exports.busyIdleWatchdogMs = 120_000;
+/**
+ * @description True iff a busy session should be force-cleared to idle: it is
+ * busy, stdout has been silent past the threshold, and every "in flight" signal
+ * is absent. Any single in-flight signal (tool / sub-agent / question / batched
+ * answer) VETOES the clear so a legitimately mid-turn agent is never truncated.
+ */
+function checkShouldClearBusyOnIdle(input) {
+    if (!input.isBusy)
+        return false;
+    if (input.msSinceStdoutActivity < input.idleTimeoutMs)
+        return false;
+    if (input.outstandingToolCount > 0)
+        return false;
+    if (input.subagentActive)
+        return false;
+    if (input.hasPendingQuestion)
+        return false;
+    if (input.hasUnflushedAnswer)
+        return false;
+    return true;
+}
+/**
+ * @description How long stdout may be silent before a compaction the CLI never
+ * confirmed is declared dead. Same signal, same reasoning as
+ * {@link busyIdleWatchdogMs}: while it compacts, the CLI heartbeats
+ * `system/status status:"compacting"` every few seconds, so real silence this long
+ * means the process is gone — not that it is thinking.
+ */
+exports.compactionSilenceTimeoutMs = 120_000;
+/**
+ * @description Absolute backstop on one compaction wait. Only reachable by a CLI
+ * that keeps talking forever without ever finishing (a retry loop), which silence
+ * alone cannot catch; without it the caller's promise — and with it the
+ * "a compaction is running" guard — would never settle.
+ */
+exports.compactionAbsoluteTimeoutMs = 30 * 60 * 1000;
+/** How often the compaction wait re-evaluates its verdict. */
+exports.compactionWaitPollMs = 15_000;
+/**
+ * @description What a timed-out compaction wait should report.
+ *
+ * `sawSuccess` means the CLI already sent `compact_status success` and only the
+ * boundary frame (which carries the pre/post token counts) never followed. The
+ * context IS compacted at that point, so reporting failure would suppress the
+ * notice over an already-compacted session and leave the operator with the same
+ * silence this whole fix exists to remove. Token counts are a diagnostic; the
+ * compaction is the outcome.
+ */
+function getCompactionTimeoutOutcome(input) {
+    if (input.sawSuccess)
+        return { kind: 'succeededWithoutTokenCounts' };
+    return { kind: 'failed', reason: input.verdict === 'timedOutSilent' ? 'silent' : 'total' };
+}
+/**
+ * @description Decide whether to keep waiting for a compaction to confirm.
+ *
+ * ROOT-CAUSE CONTEXT. This wait used to be a flat 3-minute cap on TOTAL elapsed
+ * time, and it produced the operator's report that idle compaction "runs but never
+ * says so": the compaction fired, the CLI compacted successfully, and the bot had
+ * already given up and posted nothing. Measured on the real session that exposed
+ * it — `compact_metadata.duration_ms: 195649`, i.e. 3 min 15.6 s against a 180 s
+ * cap, missing by 15 seconds. Elapsed time is the wrong bound: how long a summary
+ * takes scales with the context being summarised, so ANY fixed cap is a guess that
+ * a big enough session beats, and compact-on-idle exists precisely FOR big
+ * sessions — the bound was guaranteed to fail exactly where the feature matters.
+ *
+ * So silence decides instead, and the absolute cap survives only as a backstop
+ * against a CLI that never finishes at all. Silence is checked FIRST: for a dead
+ * process both bounds can be past, and "still talking, never finished" would be
+ * the wrong report.
+ */
+function getCompactionWaitVerdict(input) {
+    if (input.msSinceStdoutActivity >= input.silenceTimeoutMs)
+        return 'timedOutSilent';
+    if (input.msSinceCompactionStarted >= input.absoluteTimeoutMs)
+        return 'timedOutTotal';
+    return 'keepWaiting';
+}
+//# sourceMappingURL=jsonStreamBusyWatchdog.js.map

package/dist/utils/jsonStreamBusyWatchdog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonStreamBusyWatchdog.js","sourceRoot":"","sources":["../../src/utils/jsonStreamBusyWatchdog.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;;;AAiCH,gEAQC;AAwCD,kEAMC;AAoBD,4DAaC;AAtHD;;;;;GAKG;AACU,QAAA,kBAAkB,GAAG,OAAO,CAAC;AAmB1C;;;;;GAKG;AACH,SAAgB,0BAA0B,CAAC,KAA4B;IACrE,IAAI,CAAC,KAAK,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAChC,IAAI,KAAK,CAAC,qBAAqB,GAAG,KAAK,CAAC,aAAa;QAAE,OAAO,KAAK,CAAC;IACpE,IAAI,KAAK,CAAC,oBAAoB,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IACjD,IAAI,KAAK,CAAC,cAAc;QAAE,OAAO,KAAK,CAAC;IACvC,IAAI,KAAK,CAAC,kBAAkB;QAAE,OAAO,KAAK,CAAC;IAC3C,IAAI,KAAK,CAAC,kBAAkB;QAAE,OAAO,KAAK,CAAC;IAC3C,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACU,QAAA,0BAA0B,GAAG,OAAO,CAAC;AAElD;;;;;GAKG;AACU,QAAA,2BAA2B,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAE1D,8DAA8D;AACjD,QAAA,oBAAoB,GAAG,MAAM,CAAC;AAU3C;;;;;;;;;GASG;AACH,SAAgB,2BAA2B,CAAC,KAG3C;IACC,IAAI,KAAK,CAAC,UAAU;QAAE,OAAO,EAAE,IAAI,EAAE,6BAA6B,EAAE,CAAC;IACrE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,OAAO,KAAK,gBAAgB,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;AAC7F,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,wBAAwB,CAAC,KASxC;IACC,IAAI,KAAK,CAAC,qBAAqB,IAAI,KAAK,CAAC,gBAAgB;QAAE,OAAO,gBAAgB,CAAC;IACnF,IAAI,KAAK,CAAC,wBAAwB,IAAI,KAAK,CAAC,iBAAiB;QAAE,OAAO,eAAe,CAAC;IACtF,OAAO,aAAa,CAAC;AACvB,CAAC"}

package/dist/utils/jsonStreamHost.d.ts

@@ -0,0 +1,227 @@
+/**
+ * @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`.
+ */
+import { StringDecoder } from 'string_decoder';
+import { type SessionKey } from '../sessionKey';
+import type { JsonStreamTailOffset } from '../types';
+/** Subdirectory of `DATA_DIR` that holds every thread's json-stream host dir. */
+export declare const 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). */
+export declare const 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. */
+export declare const wrapperCdFailExitCode = 96;
+/** How long a fresh spawn waits for the wrapper to write the `pid` file. */
+export declare const pidFileWaitTimeoutMs = 5000;
+export declare const 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. */
+export declare const fifoOpenMaxTries = 10;
+export declare const 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. */
+export declare const fifoWriteMaxRetries = 100;
+export declare const 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. */
+export declare const stdoutOversizeWarnBytes: number;
+/** Cap for the stderr excerpt quoted into spawn-fail / unexpected-exit logs. */
+export declare const stderrTailMaxChars = 400;
+/** Absolute paths of every file in one thread's json-stream host dir. */
+export interface JsonStreamSessionPaths {
+    dir: string;
+    stdinFifo: string;
+    stdoutFile: string;
+    stderrFile: string;
+    pidFile: string;
+    exitCodeFile: string;
+    wrapperFile: string;
+    questionFile: string;
+}
+/** Absolute path of the `jsonstream/` root under a given data dir. */
+export declare function resolveJsonStreamRoot(dataDir: string): string;
+/** Absolute path of one thread's json-stream host dir. */
+export declare function resolveJsonStreamSessionDir(dataDir: string, key: SessionKey): string;
+/**
+ * @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.
+ */
+export declare function parseJsonStreamDirName(name: string): SessionKey | null;
+export declare function getJsonStreamSessionPaths(dir: string): JsonStreamSessionPaths;
+/** tmux session name for a json-stream thread (`cjson-<chatId>-<threadId>`). */
+export declare function buildJsonStreamTmuxSessionName(key: SessionKey): string;
+/** Inverse of {@link buildJsonStreamTmuxSessionName}; `null` for foreign names. */
+export declare function parseJsonStreamTmuxSessionName(name: string): SessionKey | null;
+/**
+ * @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). All embedded strings are single-quoted; `claudePath` must be ABSOLUTE
+ * (tmux server PATH differs).
+ */
+export declare function buildWrapperScript(claudePath: string, args: readonly string[], workDir: string, paths: JsonStreamSessionPaths, environment?: Readonly<Record<string, string>> | null): string;
+/**
+ * @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.
+ */
+export declare function openFifoWriterNonBlocking(fifoPath: string, maxTries?: number): Promise<number | 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.
+ */
+export declare function writeFifoText(fd: number, text: string): Promise<void>;
+export declare function readPidFile(pidFile: string): number | null;
+export declare function readExitCodeFile(exitCodeFile: string): number | null;
+/** `kill(pid, 0)` liveness probe (no signal actually delivered). */
+export declare function checkIsPidAlive(pid: number): boolean;
+/** Wait (bounded) for the wrapper to write the `pid` file after tmux spawn.
+ *  Returns the pid, or `null` on timeout (spawn diagnostics read stderr). */
+export declare function waitForPidFile(pidFile: string, timeoutMs?: number): Promise<number | null>;
+/** Last `maxChars` of the passive stderr log — spawn-fail / exit diagnostics
+ *  only (locked decision: no live stderr consumer). Empty when absent. */
+export declare function readStderrTail(stderrFile: string, maxChars?: number): string;
+/** File size in bytes, or `null` when the file doesn't exist (yet). */
+export declare function getFileSize(filePath: string): number | 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. */
+export declare function readFileByteRange(filePath: string, startOffset: number, endOffset: number): Buffer;
+/** Where an adopting bot resumes the stdout tail, and the background-task list
+ *  in force at that point (see {@link resolveAdoptedTail}). */
+export interface AdoptedTailStart {
+    startOffset: number;
+    backgroundTaskIds: string[];
+    isTurnInFlight: boolean;
+    outstandingToolUseIds: string[];
+    claudeCodeVersion: string | null;
+}
+/**
+ * @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.
+ */
+export declare function resolveAdoptedTail(persistedTail: JsonStreamTailOffset | null, claudeSessionId: string, stdoutSizeBytes: number): AdoptedTailStart;
+/**
+ * @description Tail bookkeeping for ONE session's `stdout.jsonl` (the pattern of
+ * `claudeSubagentTail`, adapted to a single file feeding the stream-json line
+ * reader). Byte-exact so the offset persisted across bot restarts always lands
+ * on a LINE BOUNDARY — the restarted tail resumes on clean JSON, never a torn
+ * line:
+ *
+ *   consumedBytes        — file bytes read + fed to the utf8 decoder
+ *   decoderRetainedBytes — bytes the decoder holds back (a multi-byte char split
+ *                          at a read boundary; stdout is block-buffered, so
+ *                          splits mid-char DO happen with non-ASCII deltas)
+ *
+ * The line-boundary offset additionally subtracts the line reader's pending
+ * partial line ({@link getStdoutLineBoundaryOffset}) — those bytes were consumed
+ * but not yet processed, so a restart re-reads exactly them and nothing twice.
+ */
+export interface StdoutTailState {
+    consumedBytes: number;
+    decoderRetainedBytes: number;
+    decoder: StringDecoder;
+}
+export declare function createStdoutTailState(startOffsetBytes: number): StdoutTailState;
+/** What one tail poll should do given the file's current size. */
+export type StdoutTailDecision = 
+/** Nothing new. */
+{
+    kind: 'none';
+}
+/** Read `[startOffset..endOffset)` and feed it through the decoder/reader. */
+ | {
+    kind: 'read';
+    startOffset: number;
+    endOffset: number;
+}
+/** The file SHRANK below the consumed offset (external truncation — should
+ *  not happen for the append-only log). State was reset to the new EOF; the
+ *  caller must reset its line reader too (a stale partial would corrupt the
+ *  next line). */
+ | {
+    kind: 'reseed';
+};
+/**
+ * @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.
+ */
+export declare function getStdoutTailDecision(state: StdoutTailState, sizeBytes: number): StdoutTailDecision;
+/**
+ * @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).
+ */
+export declare function decodeStdoutTailChunk(state: StdoutTailState, chunk: Buffer): string;
+/**
+ * @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.
+ */
+export declare function getStdoutLineBoundaryOffset(state: StdoutTailState, pendingLineText: string): number;
+/**
+ * @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.
+ */
+export declare function sweepOrphanJsonStreamDirs(jsonStreamRoot: string, checkIsThreadOwned: (key: SessionKey) => boolean): Promise<number>;
+//# sourceMappingURL=jsonStreamHost.d.ts.map