charness 0.0.0-stage → 3.1.0

package/dist/utils/timezone.d.ts

@@ -0,0 +1,125 @@
+/**
+ * @description The operator's timezone — validation, the zone catalog behind the
+ * `/timezone` picker, wall-clock formatting, and the one impure apply path that
+ * makes the setting take effect process-wide.
+ *
+ * Why a process-global mechanism: the bot runs on a host whose clock may be
+ * anything (this deploy is `Etc/UTC`). Every clock the bot touches — cron fire
+ * times, "missed at HH:MM" renders, the `/timestamps` injection, schedule
+ * descriptions — reads HOST-LOCAL time. Assigning `process.env.TZ` re-bases
+ * `Date` and `Intl` immediately on Node (verified on Node 22, no restart
+ * needed), so setting it once at startup fixes all of those call sites at their
+ * existing code with no per-site timezone threading.
+ *
+ * That is also why the setting is ONE zone per bot instance rather than
+ * per-chat: `process.env.TZ` is global by nature, and two chat-scoped zones
+ * could not both be true in a single process.
+ *
+ * Everything except {@link applyProcessTimezone} is pure, so the catalog, the
+ * validation rule and the formatting are unit-testable without booting the bot.
+ */
+/**
+ * @description Canonicalize a zone the operator typed, or `null` when `Intl`
+ * does not know it.
+ *
+ * `new Intl.DateTimeFormat(undefined, { timeZone })` throws `RangeError` for an
+ * unknown zone and accepts both IANA names and `±HH:MM` offsets — which is
+ * exactly the acceptance set the setting wants, so the probe IS the validation
+ * rule rather than a hand-maintained list that would rot against the ICU data.
+ * `resolvedOptions()` then hands back the canonical spelling (`europe/moscow` →
+ * `Europe/Moscow`, `+0400` → `+04:00`), so what gets persisted and echoed is one
+ * stable form rather than whatever casing was typed.
+ */
+export declare function getCanonicalTimezone(timezone: string): string | null;
+/** Whether `Intl` recognises `timezone` — the validation gate for `/timezone`. */
+export declare function checkIsValidTimezone(timezone: string): boolean;
+/**
+ * @description The zone the process resolved at startup — the default whenever
+ * nothing is stored, and the target `/timezone auto` resets to.
+ */
+export declare function getHostTimezone(): string;
+/**
+ * @description Whether the zone is a fixed UTC offset rather than a real region.
+ * Drives the daylight-saving warning line on the confirmation: a fixed offset
+ * silently goes an hour wrong when the operator's region changes to summer time.
+ */
+export declare function checkIsFixedOffsetZone(timezone: string): boolean;
+/**
+ * @description The value to assign to `process.env.TZ` for `timezone`, or `null`
+ * when the zone cannot be applied process-wide.
+ *
+ * An IANA name passes through unchanged. A fixed `±HH:MM` offset must NOT:
+ * `Intl.DateTimeFormat({ timeZone })` supports offset zones, but the `TZ`
+ * environment variable goes through ICU's own parser, which silently resolves
+ * `TZ="+04:00"` to **UTC** instead of rejecting it (measured on Node 22).
+ * Assigning it verbatim would therefore leave every clock on UTC while the
+ * confirmation — formatted through `Intl` — cheerfully printed `+04:00`: the
+ * exact plausible-but-wrong outcome the confirmation exists to prevent.
+ *
+ * A whole-hour offset has an exact IANA equivalent in `Etc/GMT±H`, which ICU
+ * does understand (POSIX sign inversion: UTC+4 is `Etc/GMT-4`). An offset
+ * carrying MINUTES has no such equivalent — no `TZ` spelling of it takes effect
+ * — so `null` is the honest answer and the caller rejects the input.
+ */
+export declare function getProcessTimezoneValue(timezone: string): string | null;
+/**
+ * @description Whether the zone can actually take effect process-wide — the
+ * gate `/timezone` applies before storing, so a setting is never accepted that
+ * would leave the process running on a different clock than it reports.
+ */
+export declare function checkIsApplicableTimezone(timezone: string): boolean;
+/** The region a zone belongs to (`Europe/Moscow` → `Europe`), or `null`. */
+export declare function getTimezoneRegion(timezone: string): string | null;
+/**
+ * @description The 10 IANA regions, sorted — level 1 of the `/timezone` picker.
+ */
+export declare function listTimezoneRegions(): string[];
+/**
+ * @description Every zone in `region`, sorted — level 2 of the picker. An
+ * unknown region yields an empty list rather than throwing, so a stale callback
+ * carrying a region index that no longer resolves renders an empty page instead
+ * of killing the handler.
+ */
+export declare function getTimezonesForRegion(region: string): string[];
+/**
+ * @description The zone's current wall clock as `18:42 (+03:00)` — the tail of
+ * every `/timezone` confirmation and of the `/status` zone row, so a wrong pick
+ * is obvious the moment it is made.
+ */
+export declare function formatZoneNow(timezone: string, nowMs: number): string;
+/**
+ * @description The zone's current instant WITH the calendar date —
+ * `2026-09-14 18:42 (+03:00)`. Used in the picker header, where the date
+ * matters: a zone far enough east or west can sit on a different day than the
+ * operator expects, and that is the mistake the header is there to catch.
+ */
+export declare function formatZoneNowWithDate(timezone: string, nowMs: number): string;
+/**
+ * @description Apply the stored zone to the process — the ONE impure function
+ * here, shared by bot startup and the runtime `/timezone` change so both take
+ * effect through identical code.
+ *
+ * `null` means "nothing stored": the `TZ` environment is restored to exactly
+ * what the process was launched with (absent stays absent), which is what makes
+ * `/timezone auto` return to the host zone and what keeps a default install
+ * behaving precisely as it did before this setting existed.
+ *
+ * Assigning `process.env.TZ` re-bases `Date` and `Intl` for subsequent calls, so
+ * no restart is needed — that behaviour is asserted by a unit test rather than
+ * trusted. The assigned value comes from {@link getProcessTimezoneValue}, which
+ * rewrites a fixed offset into the `Etc/GMT±H` spelling ICU honours.
+ *
+ * A zone with no applicable `TZ` value (an offset carrying minutes) is treated
+ * as "nothing stored" rather than applied: `/timezone` rejects those at the
+ * boundary, so this is only reachable from a hand-edited `state.json`, and
+ * falling back to the launch environment beats silently running on UTC.
+ */
+export declare function applyProcessTimezone(timezone: string | null): void;
+/**
+ * @description The zone in effect right now: the stored setting when present,
+ * otherwise the host zone. The single resolution rule every render (`/status`,
+ * the picker header, the thread-context preamble, the schedule templates) reads,
+ * so no call site re-derives the "unset means host" default.
+ */
+export declare function getEffectiveTimezone(storedTimezone: string | null): string;
+//# sourceMappingURL=timezone.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"timezone.d.ts","sourceRoot":"","sources":["../../src/utils/timezone.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AA+CH;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOpE;AAED,kFAAkF;AAClF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEhE;AAUD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOvE;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEnE;AAED,4EAA4E;AAC5E,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGjE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,EAAE,CAO9C;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAG9D;AAmDD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAGrE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAG7E;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAQlE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAE1E"}

package/dist/utils/timezone.js

@@ -0,0 +1,278 @@
+"use strict";
+/**
+ * @description The operator's timezone — validation, the zone catalog behind the
+ * `/timezone` picker, wall-clock formatting, and the one impure apply path that
+ * makes the setting take effect process-wide.
+ *
+ * Why a process-global mechanism: the bot runs on a host whose clock may be
+ * anything (this deploy is `Etc/UTC`). Every clock the bot touches — cron fire
+ * times, "missed at HH:MM" renders, the `/timestamps` injection, schedule
+ * descriptions — reads HOST-LOCAL time. Assigning `process.env.TZ` re-bases
+ * `Date` and `Intl` immediately on Node (verified on Node 22, no restart
+ * needed), so setting it once at startup fixes all of those call sites at their
+ * existing code with no per-site timezone threading.
+ *
+ * That is also why the setting is ONE zone per bot instance rather than
+ * per-chat: `process.env.TZ` is global by nature, and two chat-scoped zones
+ * could not both be true in a single process.
+ *
+ * Everything except {@link applyProcessTimezone} is pure, so the catalog, the
+ * validation rule and the formatting are unit-testable without booting the bot.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCanonicalTimezone = getCanonicalTimezone;
+exports.checkIsValidTimezone = checkIsValidTimezone;
+exports.getHostTimezone = getHostTimezone;
+exports.checkIsFixedOffsetZone = checkIsFixedOffsetZone;
+exports.getProcessTimezoneValue = getProcessTimezoneValue;
+exports.checkIsApplicableTimezone = checkIsApplicableTimezone;
+exports.getTimezoneRegion = getTimezoneRegion;
+exports.listTimezoneRegions = listTimezoneRegions;
+exports.getTimezonesForRegion = getTimezonesForRegion;
+exports.formatZoneNow = formatZoneNow;
+exports.formatZoneNowWithDate = formatZoneNowWithDate;
+exports.applyProcessTimezone = applyProcessTimezone;
+exports.getEffectiveTimezone = getEffectiveTimezone;
+/** Separator between the region and the rest of an IANA zone name. */
+const zoneRegionSeparator = '/';
+/**
+ * @description A fixed UTC offset written as a zone (`+04:00`, `-0330`, `+05`).
+ * `Intl` accepts these as real zones, so they are allowed — but they do NOT
+ * follow daylight saving, which is why picking one earns a warning line.
+ */
+const fixedOffsetZoneRe = /^([+-])(\d{2})(?::?(\d{2}))?$/;
+const minutesPerHour = 60;
+/**
+ * The widest `Etc/GMT±H` zones tzdata defines (UTC+14 .. UTC−12). An offset
+ * outside that has no IANA equivalent to apply.
+ */
+const maxEtcGmtOffsetHours = 14;
+const minEtcGmtOffsetHours = -12;
+/**
+ * The zone the process would use if the bot stored nothing — captured at module
+ * load, BEFORE {@link applyProcessTimezone} can overwrite `process.env.TZ`.
+ * Without this snapshot `/timezone auto` could not find its way back: once a
+ * stored zone is applied, `resolvedOptions()` reports the STORED zone and the
+ * original is gone.
+ */
+const hostTimezone = new Intl.DateTimeFormat().resolvedOptions().timeZone;
+/**
+ * The `TZ` environment value as the process was launched with it (possibly
+ * absent). Restored verbatim on a reset so an operator who deliberately exports
+ * `TZ` keeps that behaviour when no bot setting is stored.
+ */
+const initialTimezoneEnv = process.env.TZ;
+/** The full IANA zone list, computed once (418 entries on Node 22). */
+let cachedTimezones = null;
+function getAllTimezones() {
+    if (cachedTimezones === null) {
+        cachedTimezones = [...Intl.supportedValuesOf('timeZone')].sort();
+    }
+    return cachedTimezones;
+}
+/**
+ * @description Canonicalize a zone the operator typed, or `null` when `Intl`
+ * does not know it.
+ *
+ * `new Intl.DateTimeFormat(undefined, { timeZone })` throws `RangeError` for an
+ * unknown zone and accepts both IANA names and `±HH:MM` offsets — which is
+ * exactly the acceptance set the setting wants, so the probe IS the validation
+ * rule rather than a hand-maintained list that would rot against the ICU data.
+ * `resolvedOptions()` then hands back the canonical spelling (`europe/moscow` →
+ * `Europe/Moscow`, `+0400` → `+04:00`), so what gets persisted and echoed is one
+ * stable form rather than whatever casing was typed.
+ */
+function getCanonicalTimezone(timezone) {
+    if (typeof timezone !== 'string' || timezone.trim() === '')
+        return null;
+    try {
+        return new Intl.DateTimeFormat(undefined, { timeZone: timezone }).resolvedOptions().timeZone;
+    }
+    catch {
+        return null;
+    }
+}
+/** Whether `Intl` recognises `timezone` — the validation gate for `/timezone`. */
+function checkIsValidTimezone(timezone) {
+    return getCanonicalTimezone(timezone) !== null;
+}
+/**
+ * @description The zone the process resolved at startup — the default whenever
+ * nothing is stored, and the target `/timezone auto` resets to.
+ */
+function getHostTimezone() {
+    return hostTimezone;
+}
+/**
+ * @description Whether the zone is a fixed UTC offset rather than a real region.
+ * Drives the daylight-saving warning line on the confirmation: a fixed offset
+ * silently goes an hour wrong when the operator's region changes to summer time.
+ */
+function checkIsFixedOffsetZone(timezone) {
+    return fixedOffsetZoneRe.test(timezone);
+}
+/** Signed minutes of a `±HH:MM` zone, or `null` when it is not an offset. */
+function getFixedOffsetMinutes(timezone) {
+    const match = fixedOffsetZoneRe.exec(timezone);
+    if (match === null)
+        return null;
+    const sign = match[1] === '-' ? -1 : 1;
+    return sign * (Number(match[2]) * minutesPerHour + Number(match[3] ?? 0));
+}
+/**
+ * @description The value to assign to `process.env.TZ` for `timezone`, or `null`
+ * when the zone cannot be applied process-wide.
+ *
+ * An IANA name passes through unchanged. A fixed `±HH:MM` offset must NOT:
+ * `Intl.DateTimeFormat({ timeZone })` supports offset zones, but the `TZ`
+ * environment variable goes through ICU's own parser, which silently resolves
+ * `TZ="+04:00"` to **UTC** instead of rejecting it (measured on Node 22).
+ * Assigning it verbatim would therefore leave every clock on UTC while the
+ * confirmation — formatted through `Intl` — cheerfully printed `+04:00`: the
+ * exact plausible-but-wrong outcome the confirmation exists to prevent.
+ *
+ * A whole-hour offset has an exact IANA equivalent in `Etc/GMT±H`, which ICU
+ * does understand (POSIX sign inversion: UTC+4 is `Etc/GMT-4`). An offset
+ * carrying MINUTES has no such equivalent — no `TZ` spelling of it takes effect
+ * — so `null` is the honest answer and the caller rejects the input.
+ */
+function getProcessTimezoneValue(timezone) {
+    const offsetMinutes = getFixedOffsetMinutes(timezone);
+    if (offsetMinutes === null)
+        return timezone;
+    if (offsetMinutes % minutesPerHour !== 0)
+        return null;
+    const offsetHours = offsetMinutes / minutesPerHour;
+    if (offsetHours > maxEtcGmtOffsetHours || offsetHours < minEtcGmtOffsetHours)
+        return null;
+    return `Etc/GMT${offsetHours <= 0 ? '+' : '-'}${Math.abs(offsetHours)}`;
+}
+/**
+ * @description Whether the zone can actually take effect process-wide — the
+ * gate `/timezone` applies before storing, so a setting is never accepted that
+ * would leave the process running on a different clock than it reports.
+ */
+function checkIsApplicableTimezone(timezone) {
+    return getProcessTimezoneValue(timezone) !== null;
+}
+/** The region a zone belongs to (`Europe/Moscow` → `Europe`), or `null`. */
+function getTimezoneRegion(timezone) {
+    const separatorIndex = timezone.indexOf(zoneRegionSeparator);
+    return separatorIndex > 0 ? timezone.slice(0, separatorIndex) : null;
+}
+/**
+ * @description The 10 IANA regions, sorted — level 1 of the `/timezone` picker.
+ */
+function listTimezoneRegions() {
+    const regions = new Set();
+    for (const timezone of getAllTimezones()) {
+        const region = getTimezoneRegion(timezone);
+        if (region !== null)
+            regions.add(region);
+    }
+    return [...regions].sort();
+}
+/**
+ * @description Every zone in `region`, sorted — level 2 of the picker. An
+ * unknown region yields an empty list rather than throwing, so a stale callback
+ * carrying a region index that no longer resolves renders an empty page instead
+ * of killing the handler.
+ */
+function getTimezonesForRegion(region) {
+    const prefix = `${region}${zoneRegionSeparator}`;
+    return getAllTimezones().filter((timezone) => timezone.startsWith(prefix));
+}
+/** Prefix `Intl`'s `longOffset` renders before the numeric offset. */
+const longOffsetPrefix = 'GMT';
+/** What a `longOffset` of exactly `GMT` means numerically. */
+const zeroOffset = '+00:00';
+/**
+ * Read the zone's wall clock at `nowMs` via `formatToParts`, so the date, the
+ * time and the offset come from ONE formatter pass (and therefore one instant)
+ * instead of three separately-parsed strings.
+ *
+ * Throws `RangeError` for an invalid zone — callers validate with
+ * {@link checkIsValidTimezone} first.
+ */
+function getZoneClockParts(timezone, nowMs) {
+    const parts = new Intl.DateTimeFormat('en-CA', {
+        timeZone: timezone,
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        hourCycle: 'h23',
+        timeZoneName: 'longOffset',
+    }).formatToParts(new Date(nowMs));
+    const read = (type) => parts.find((part) => part.type === type)?.value ?? '';
+    const rawOffset = read('timeZoneName');
+    const numericOffset = rawOffset.startsWith(longOffsetPrefix)
+        ? rawOffset.slice(longOffsetPrefix.length)
+        : rawOffset;
+    return {
+        date: `${read('year')}-${read('month')}-${read('day')}`,
+        time: `${read('hour')}:${read('minute')}`,
+        offset: numericOffset === '' ? zeroOffset : numericOffset,
+    };
+}
+/**
+ * @description The zone's current wall clock as `18:42 (+03:00)` — the tail of
+ * every `/timezone` confirmation and of the `/status` zone row, so a wrong pick
+ * is obvious the moment it is made.
+ */
+function formatZoneNow(timezone, nowMs) {
+    const { time, offset } = getZoneClockParts(timezone, nowMs);
+    return `${time} (${offset})`;
+}
+/**
+ * @description The zone's current instant WITH the calendar date —
+ * `2026-09-14 18:42 (+03:00)`. Used in the picker header, where the date
+ * matters: a zone far enough east or west can sit on a different day than the
+ * operator expects, and that is the mistake the header is there to catch.
+ */
+function formatZoneNowWithDate(timezone, nowMs) {
+    const { date, time, offset } = getZoneClockParts(timezone, nowMs);
+    return `${date} ${time} (${offset})`;
+}
+/**
+ * @description Apply the stored zone to the process — the ONE impure function
+ * here, shared by bot startup and the runtime `/timezone` change so both take
+ * effect through identical code.
+ *
+ * `null` means "nothing stored": the `TZ` environment is restored to exactly
+ * what the process was launched with (absent stays absent), which is what makes
+ * `/timezone auto` return to the host zone and what keeps a default install
+ * behaving precisely as it did before this setting existed.
+ *
+ * Assigning `process.env.TZ` re-bases `Date` and `Intl` for subsequent calls, so
+ * no restart is needed — that behaviour is asserted by a unit test rather than
+ * trusted. The assigned value comes from {@link getProcessTimezoneValue}, which
+ * rewrites a fixed offset into the `Etc/GMT±H` spelling ICU honours.
+ *
+ * A zone with no applicable `TZ` value (an offset carrying minutes) is treated
+ * as "nothing stored" rather than applied: `/timezone` rejects those at the
+ * boundary, so this is only reachable from a hand-edited `state.json`, and
+ * falling back to the launch environment beats silently running on UTC.
+ */
+function applyProcessTimezone(timezone) {
+    const envValue = timezone === null ? null : getProcessTimezoneValue(timezone);
+    if (envValue === null) {
+        if (initialTimezoneEnv === undefined)
+            delete process.env.TZ;
+        else
+            process.env.TZ = initialTimezoneEnv;
+        return;
+    }
+    process.env.TZ = envValue;
+}
+/**
+ * @description The zone in effect right now: the stored setting when present,
+ * otherwise the host zone. The single resolution rule every render (`/status`,
+ * the picker header, the thread-context preamble, the schedule templates) reads,
+ * so no call site re-derives the "unset means host" default.
+ */
+function getEffectiveTimezone(storedTimezone) {
+    return storedTimezone ?? hostTimezone;
+}
+//# sourceMappingURL=timezone.js.map

package/dist/utils/timezone.js.map

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

package/dist/utils/tmuxExec.d.ts

@@ -0,0 +1,61 @@
+import { execFile } from 'child_process';
+export declare const execFilePromise: typeof execFile.__promisify__;
+/**
+ * @description `-t` target naming a tmux SESSION exactly (`kill-session`). A
+ * bare name falls back to a PREFIX match when no session has exactly that name
+ * — on tmux 3.4, with topic 2's session gone, `kill-session -t claude-<chat>-2`
+ * kills topic 20's. The leading `=` makes the match exact.
+ */
+export declare function getTmuxSessionTarget(sessionName: string): string;
+/**
+ * @description `-t` target naming a session's current pane exactly — for every
+ * pane or window command (`send-keys`, `capture-pane`, `display-message`,
+ * `list-panes`). Exact for the same reason as {@link getTmuxSessionTarget}; the
+ * trailing `:` is required, since `send-keys -t =name` fails "can't find pane".
+ */
+export declare function getTmuxPaneTarget(sessionName: string): string;
+/**
+ * @description The arguments every tmux call starts with (Jira connector plan J3,
+ * D8): `TMUX_SOCKET_NAME` puts the instance on its OWN tmux server (`-L`), away
+ * from the default one — a boot kills every agent session it does not own, which
+ * on a shared server would be another bot's. The CLI preflight validates the
+ * name. This file is the only place that runs tmux; keep it so.
+ */
+export declare function getTmuxBaseArgs(): string[];
+/**
+ * @description The environment a tmux call runs with. On a PRIVATE server
+ * (`TMUX_SOCKET_NAME`) only the agent allowlist plus where its socket lives
+ * (R32): the call that starts the server hands it its global environment, which
+ * every session inherits and any process on the server can read back — a
+ * tracker instance's secrets must not be in it. The default server (a Telegram
+ * instance) keeps the bot's own environment, as before.
+ */
+export declare function getTmuxExecEnv(): NodeJS.ProcessEnv | undefined;
+/** Best-effort tmux call: returns stdout on success, empty string on any error. */
+export declare function tmuxAsync(...args: string[]): Promise<string>;
+/**
+ * @description Strict tmux call: throws if tmux exits non-zero (or times out).
+ * Used on critical paths (`new-session`, `send-keys` of the agent command
+ * line) where silent failure would leave the bot thinking a session
+ * started when it didn't. Callers should wrap and translate to a friendly
+ * error for the user.
+ */
+export declare function tmuxOrThrowAsync(...args: string[]): Promise<string>;
+/**
+ * @description Reject `args` with NUL or other control characters before
+ * passing to a backend. These are unsafe in shell-quoted contexts (the
+ * `'\\''` escape doesn't protect against `\x00`), and tmux/terminals
+ * treat them as control sequences. Mirrors `validateSubdir`'s reasoning.
+ */
+export declare function checkArgsAreSafe(args: string): boolean;
+/**
+ * @description Shell-quote a path for safe inclusion in a tmux `send-keys "..."` command.
+ *
+ * The tmux command line concatenates: `tmux send-keys -t <name> "cd <dir> && claude ..."`.
+ * The dir is interpreted by the user's shell after tmux delivers the keystrokes, so we
+ * single-quote it. Embedded single quotes are escaped via the standard
+ * `'\''` close-reopen idiom. This is the path a backend will `cd` into, so paths with
+ * spaces or special chars (e.g. `~/my projects/foo`) must survive untouched.
+ */
+export declare function shellSingleQuote(s: string): string;
+//# sourceMappingURL=tmuxExec.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tmuxExec.d.ts","sourceRoot":"","sources":["../../src/utils/tmuxExec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAIzC,eAAO,MAAM,eAAe,+BAAsB,CAAC;AAEnD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,IAAI,MAAM,EAAE,CAG1C;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAAC,UAAU,GAAG,SAAS,CAI9D;AAED,mFAAmF;AACnF,wBAAsB,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAWlE;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAOzE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAElD"}

package/dist/utils/tmuxExec.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.execFilePromise = void 0;
+exports.getTmuxSessionTarget = getTmuxSessionTarget;
+exports.getTmuxPaneTarget = getTmuxPaneTarget;
+exports.getTmuxBaseArgs = getTmuxBaseArgs;
+exports.getTmuxExecEnv = getTmuxExecEnv;
+exports.tmuxAsync = tmuxAsync;
+exports.tmuxOrThrowAsync = tmuxOrThrowAsync;
+exports.checkArgsAreSafe = checkArgsAreSafe;
+exports.shellSingleQuote = shellSingleQuote;
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const agentEnvironment_1 = require("./agentEnvironment");
+exports.execFilePromise = (0, util_1.promisify)(child_process_1.execFile);
+/**
+ * @description `-t` target naming a tmux SESSION exactly (`kill-session`). A
+ * bare name falls back to a PREFIX match when no session has exactly that name
+ * — on tmux 3.4, with topic 2's session gone, `kill-session -t claude-<chat>-2`
+ * kills topic 20's. The leading `=` makes the match exact.
+ */
+function getTmuxSessionTarget(sessionName) {
+    return `=${sessionName}`;
+}
+/**
+ * @description `-t` target naming a session's current pane exactly — for every
+ * pane or window command (`send-keys`, `capture-pane`, `display-message`,
+ * `list-panes`). Exact for the same reason as {@link getTmuxSessionTarget}; the
+ * trailing `:` is required, since `send-keys -t =name` fails "can't find pane".
+ */
+function getTmuxPaneTarget(sessionName) {
+    return `=${sessionName}:`;
+}
+/**
+ * @description The arguments every tmux call starts with (Jira connector plan J3,
+ * D8): `TMUX_SOCKET_NAME` puts the instance on its OWN tmux server (`-L`), away
+ * from the default one — a boot kills every agent session it does not own, which
+ * on a shared server would be another bot's. The CLI preflight validates the
+ * name. This file is the only place that runs tmux; keep it so.
+ */
+function getTmuxBaseArgs() {
+    const socketName = process.env.TMUX_SOCKET_NAME;
+    return socketName ? ['-L', socketName] : [];
+}
+/**
+ * @description The environment a tmux call runs with. On a PRIVATE server
+ * (`TMUX_SOCKET_NAME`) only the agent allowlist plus where its socket lives
+ * (R32): the call that starts the server hands it its global environment, which
+ * every session inherits and any process on the server can read back — a
+ * tracker instance's secrets must not be in it. The default server (a Telegram
+ * instance) keeps the bot's own environment, as before.
+ */
+function getTmuxExecEnv() {
+    if (!process.env.TMUX_SOCKET_NAME)
+        return undefined;
+    const socketDir = process.env.TMUX_TMPDIR;
+    return { ...(0, agentEnvironment_1.getAgentEnvironment)(), ...(socketDir ? { TMUX_TMPDIR: socketDir } : {}) };
+}
+/** Best-effort tmux call: returns stdout on success, empty string on any error. */
+async function tmuxAsync(...args) {
+    try {
+        const { stdout } = await (0, exports.execFilePromise)('tmux', [...getTmuxBaseArgs(), ...args], {
+            encoding: 'utf-8',
+            timeout: 5000,
+            env: getTmuxExecEnv(),
+        });
+        return stdout.toString().trim();
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * @description Strict tmux call: throws if tmux exits non-zero (or times out).
+ * Used on critical paths (`new-session`, `send-keys` of the agent command
+ * line) where silent failure would leave the bot thinking a session
+ * started when it didn't. Callers should wrap and translate to a friendly
+ * error for the user.
+ */
+async function tmuxOrThrowAsync(...args) {
+    const { stdout } = await (0, exports.execFilePromise)('tmux', [...getTmuxBaseArgs(), ...args], {
+        encoding: 'utf-8',
+        timeout: 5000,
+        env: getTmuxExecEnv(),
+    });
+    return stdout.toString().trim();
+}
+/**
+ * @description Reject `args` with NUL or other control characters before
+ * passing to a backend. These are unsafe in shell-quoted contexts (the
+ * `'\\''` escape doesn't protect against `\x00`), and tmux/terminals
+ * treat them as control sequences. Mirrors `validateSubdir`'s reasoning.
+ */
+function checkArgsAreSafe(args) {
+    return !/[\x00-\x08\x0b\x0c\x0e-\x1f]/.test(args);
+}
+/**
+ * @description Shell-quote a path for safe inclusion in a tmux `send-keys "..."` command.
+ *
+ * The tmux command line concatenates: `tmux send-keys -t <name> "cd <dir> && claude ..."`.
+ * The dir is interpreted by the user's shell after tmux delivers the keystrokes, so we
+ * single-quote it. Embedded single quotes are escaped via the standard
+ * `'\''` close-reopen idiom. This is the path a backend will `cd` into, so paths with
+ * spaces or special chars (e.g. `~/my projects/foo`) must survive untouched.
+ */
+function shellSingleQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+//# sourceMappingURL=tmuxExec.js.map

package/dist/utils/tmuxExec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tmuxExec.js","sourceRoot":"","sources":["../../src/utils/tmuxExec.ts"],"names":[],"mappings":";;;AAYA,oDAEC;AAQD,8CAEC;AASD,0CAGC;AAUD,wCAIC;AAGD,8BAWC;AASD,4CAOC;AAQD,4CAEC;AAWD,4CAEC;AAvGD,iDAAyC;AACzC,+BAAiC;AACjC,yDAAyD;AAE5C,QAAA,eAAe,GAAG,IAAA,gBAAS,EAAC,wBAAQ,CAAC,CAAC;AAEnD;;;;;GAKG;AACH,SAAgB,oBAAoB,CAAC,WAAmB;IACtD,OAAO,IAAI,WAAW,EAAE,CAAC;AAC3B,CAAC;AAED;;;;;GAKG;AACH,SAAgB,iBAAiB,CAAC,WAAmB;IACnD,OAAO,IAAI,WAAW,GAAG,CAAC;AAC5B,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,eAAe;IAC7B,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;IAChD,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC9C,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,cAAc;IAC5B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB;QAAE,OAAO,SAAS,CAAC;IACpD,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC;IAC1C,OAAO,EAAE,GAAG,IAAA,sCAAmB,GAAE,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AACxF,CAAC;AAED,mFAAmF;AAC5E,KAAK,UAAU,SAAS,CAAC,GAAG,IAAc;IAC/C,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,IAAA,uBAAe,EAAC,MAAM,EAAE,CAAC,GAAG,eAAe,EAAE,EAAE,GAAG,IAAI,CAAC,EAAE;YAChF,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,IAAI;YACb,GAAG,EAAE,cAAc,EAAE;SACtB,CAAC,CAAC;QACH,OAAO,MAAM,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACI,KAAK,UAAU,gBAAgB,CAAC,GAAG,IAAc;IACtD,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,IAAA,uBAAe,EAAC,MAAM,EAAE,CAAC,GAAG,eAAe,EAAE,EAAE,GAAG,IAAI,CAAC,EAAE;QAChF,QAAQ,EAAE,OAAO;QACjB,OAAO,EAAE,IAAI;QACb,GAAG,EAAE,cAAc,EAAE;KACtB,CAAC,CAAC;IACH,OAAO,MAAM,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC;AAClC,CAAC;AAED;;;;;GAKG;AACH,SAAgB,gBAAgB,CAAC,IAAY;IAC3C,OAAO,CAAC,8BAA8B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACpD,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,gBAAgB,CAAC,CAAS;IACxC,OAAO,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC;AACzC,CAAC"}

package/dist/utils/tmuxSessionName.d.ts

@@ -0,0 +1,34 @@
+import { type SessionKey } from '../sessionKey';
+/**
+ * @description Tmux session name for a `SessionKey`, namespaced by a backend
+ * `prefix` so different adapters (Claude `claude-…`, terminal `term-…`) never
+ * collide on one tmux server.
+ *
+ * Format: `<prefix>-<serializedKey with ':' → '-'>`, which for Telegram is the
+ * historical `<prefix>-<chatId>-<threadId>`. Negative chat ids (forum
+ * supergroups are negative) keep their minus sign — tmux session names accept
+ * it. The format is `parse`-able back to `SessionKey` via
+ * {@link parseTmuxSessionName} with the SAME prefix.
+ *
+ * The connector's codec owns the serialized halves, so this helper never looks
+ * at platform-specific fields and the on-disk names stay byte-identical.
+ */
+export declare function buildTmuxSessionName(prefix: string, key: SessionKey): string;
+/**
+ * @description Inverse of {@link buildTmuxSessionName} for a given `prefix`.
+ * Returns `null` for names that don't parse back to a key (e.g. an unrelated
+ * tmux session a user started by hand, or one owned by a different backend's
+ * prefix).
+ *
+ * The slug after the prefix is read back by the codec that owns it
+ * ({@link tryKeyFromSlug}): Telegram's `claude--1001234-42` parses to
+ * `-1001234:42` (split on the last `-`, whatever the chat id's sign), Jira's
+ * `claude-jira-PROJ-PROJ-12` to `jira:PROJ:PROJ-12`.
+ *
+ * Strictness lives in the codec (audit S1 / #22): plain `Number(...)` accepts
+ * `1e5`, `0x10`, `1.5`, `" 42 "`. Such values come from a foreign tmux session
+ * whose name happens to share our prefix; treating them as ours would cause an
+ * adopt path to attach to an unrelated session.
+ */
+export declare function parseTmuxSessionName(prefix: string, name: string): SessionKey | null;
+//# sourceMappingURL=tmuxSessionName.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tmuxSessionName.d.ts","sourceRoot":"","sources":["../../src/utils/tmuxSessionName.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6B,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAS3E;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,MAAM,CAE5E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAIpF"}