charness 0.0.0-stage → 3.1.0

package/dist/cli/claudeProfiles.js

@@ -0,0 +1,106 @@
+"use strict";
+/**
+ * @description `telegramcode claude-profiles [--best] [--model <name>] [--json]` — the command-line twin of the
+ * `claude_profiles` MCP tool, for a worker that has no MCP (a shell script, a child started by hand): which
+ * Claude account profile a new process should run on. It reads the bot's cache off `DATA_DIR/state.json`
+ * (`utils/claudeUsage.ts`; the bot polls every profile's usage on a timer, so the figures are at most a poll
+ * old) and never opens the `StateStore` (that would migrate and lock a live bot's file) nor the network.
+ *
+ *   --best         print ONLY the recommended profile's config directory — an EMPTY line for the default
+ *                  profile (set nothing) — so `CLAUDE_CONFIG_DIR="$(telegramcode claude-profiles --best)"`
+ *                  works as is; exit 1 when no profile is eligible
+ *   --model <name> the model the child will run (`fable` → the Fable weekly window counts)
+ *   --json         the full report as JSON (the MCP tool's shape)
+ *
+ * Without a flag: one human line per profile. `DATA_DIR` comes from the environment the bot itself reads
+ * (`~/.config/telegramcode/.env`, `$PWD/.env`, or `ENV_FILE`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseClaudeProfilesCliArgs = parseClaudeProfilesCliArgs;
+exports.formatClaudeProfileCliLine = formatClaudeProfileCliLine;
+exports.runClaudeProfilesCli = runClaudeProfilesCli;
+const envLoader_1 = require("./envLoader");
+const state_1 = require("../state");
+const claudeUsage_1 = require("../utils/claudeUsage");
+/** Parse the subcommand's flags; `null` with a message for anything unknown. */
+function parseClaudeProfilesCliArgs(argv) {
+    const args = { isBest: false, isJson: false, model: null };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === '--best')
+            args.isBest = true;
+        else if (arg === '--json')
+            args.isJson = true;
+        else if (arg === '--model') {
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith('--'))
+                return { ok: false, error: '--model needs a value' };
+            args.model = value;
+            i += 1;
+        }
+        else if (arg.startsWith('--model='))
+            args.model = arg.slice('--model='.length);
+        else
+            return { ok: false, error: `unknown option: ${arg}` };
+    }
+    if (args.model !== null && args.model.trim() === '')
+        return { ok: false, error: '--model needs a value' };
+    return { ok: true, args };
+}
+/** One human line: `✓ work  /data/…/work  mail@example.com personal max  5h 12% 🔄 in 2h · week 40% 🔄 in 2d 1h · Fable 3% 🔄 in 2d 1h` (no Fable part for an account without that window). */
+function formatClaudeProfileCliLine(entry, nowMs) {
+    const find = (kind) => entry.buckets.find((bucket) => bucket.kind === kind) ?? null;
+    const weeklyReset = find('weekly_all')?.resetsAt ?? null;
+    const read = (kind) => (0, claudeUsage_1.formatClaudeUsageBucket)(find(kind), nowMs, { fallbackResetsAt: kind === 'session' ? weeklyReset : null });
+    const marker = entry.isRecommended ? '✓' : entry.isEligible ? '•' : '✗';
+    const account = entry.loggedIn === false
+        ? 'not signed in'
+        : entry.loggedIn === null && entry.email === null
+            ? 'not probed yet (open /account once)'
+            : `${entry.email ?? '?'} ${entry.kind} ${entry.subscriptionType ?? '?'}`;
+    const usage = entry.buckets.length === 0
+        ? 'usage not read yet'
+        : `${[
+            `5h ${read('session')}`,
+            `week ${read('weekly_all')}`,
+            ...(find('weekly_scoped') === null ? [] : [`Fable ${read('weekly_scoped')}`]),
+        ].join(' · ')}${entry.isUsageStale ? ' (stale)' : ''}`;
+    const limited = entry.limitedUntil && Date.parse(entry.limitedUntil) > nowMs ? `  LIMITED until ${entry.limitedUntil}` : '';
+    return `${marker} ${entry.name}  ${entry.configDir ?? '(default: no CLAUDE_CONFIG_DIR)'}  ${account}  ${usage}${limited}`;
+}
+/**
+ * @description Run the subcommand; returns the exit code. Output goes to stdout, a refusal to stderr.
+ * `readRecords` / `now` are injectable for the unit test; the CLI test drives the built binary instead.
+ */
+async function runClaudeProfilesCli(argv, io = {}) {
+    const stdout = io.stdout ?? ((text) => process.stdout.write(text));
+    const stderr = io.stderr ?? ((text) => process.stderr.write(text));
+    const parsed = parseClaudeProfilesCliArgs(argv);
+    if (!parsed.ok) {
+        stderr(`${parsed.error}\nUsage: telegramcode claude-profiles [--best] [--model <name>] [--json]\n`);
+        return 2;
+    }
+    const { args } = parsed;
+    (0, envLoader_1.loadEnvFiles)();
+    const dataDir = (0, state_1.resolveDataDir)();
+    const nowMs = (io.now ?? Date.now)();
+    const records = (0, claudeUsage_1.readClaudeProfileRecordsFromStateFile)(dataDir);
+    const report = (0, claudeUsage_1.buildClaudeProfilesReport)((0, claudeUsage_1.buildClaudeProfileUsageViews)({ dataDir, records }), args.model, nowMs);
+    if (args.isJson) {
+        stdout(`${JSON.stringify(report, null, 2)}\n`);
+        return report.recommended === null && args.isBest ? 1 : 0;
+    }
+    if (args.isBest) {
+        if (report.recommended === null) {
+            stderr('no eligible Claude profile: every signed-in account is limited or at 100 % on a relevant window\n');
+            return 1;
+        }
+        const entry = report.profiles.find((profile) => profile.name === report.recommended);
+        stdout(`${entry?.configDir ?? ''}\n`);
+        return 0;
+    }
+    stdout(`${report.profiles.map((entry) => formatClaudeProfileCliLine(entry, nowMs)).join('\n')}\n`);
+    stdout(`recommended for ${args.model ?? 'any model'}: ${report.recommended ?? 'none'}\n`);
+    return 0;
+}
+//# sourceMappingURL=claudeProfiles.js.map

package/dist/cli/claudeProfiles.js.map

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

package/dist/cli/connectorGuards.d.ts

@@ -0,0 +1,31 @@
+type EnvReading = Readonly<Record<string, string | undefined>>;
+/**
+ * @description The guard that must hold BEFORE any env file is read: an instance
+ * the shell already marks as serving Jira reads its settings from `ENV_FILE`
+ * only, so the shared config files (which hold a live bot's token) are never
+ * opened. A `CONNECTORS` the shell sets but that does not parse is refused here
+ * too: it cannot tell whether the instance was meant to serve Jira.
+ */
+export declare function getPreloadGuardErrors(env: EnvReading): string[];
+/**
+ * @description The guards on the loaded environment. Names only — never a value.
+ * `envFileAtLaunch` is `ENV_FILE` as it was BEFORE the load: only that value
+ * says the instance read nothing but its own file, since a shared config file
+ * may itself define `ENV_FILE`.
+ */
+export declare function getConnectorGuardErrors(input: {
+    env: EnvReading;
+    hasJiraConfig: boolean;
+    envFileAtLaunch: string | undefined;
+    /** `process.versions.node`. */
+    nodeVersion: string;
+}): string[];
+/**
+ * @description Load the env files between the two guard passes — the ONE way the
+ * CLI starts (plain and hot), so no start skips a guard. Exits 1 on a breach.
+ */
+export declare function loadEnvWithConnectorGuards(localDirectory?: string): {
+    loaded: string[];
+};
+export {};
+//# sourceMappingURL=connectorGuards.d.ts.map

package/dist/cli/connectorGuards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connectorGuards.d.ts","sourceRoot":"","sources":["../../src/cli/connectorGuards.ts"],"names":[],"mappings":"AA8CA,KAAK,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAE/D;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,EAAE,CAK/D;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAC7C,GAAG,EAAE,UAAU,CAAC;IAChB,aAAa,EAAE,OAAO,CAAC;IACvB,eAAe,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,MAAM,EAAE,CAmCX;AAQD;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAOxF"}

package/dist/cli/connectorGuards.js

@@ -0,0 +1,159 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPreloadGuardErrors = getPreloadGuardErrors;
+exports.getConnectorGuardErrors = getConnectorGuardErrors;
+exports.loadEnvWithConnectorGuards = loadEnvWithConnectorGuards;
+const fs = __importStar(require("fs"));
+const connectorSet_1 = require("../platform/connectorSet");
+const configFile_1 = require("../connectors/jira/configFile");
+const state_1 = require("../state");
+const envLoader_1 = require("./envLoader");
+/**
+ * @description The fail-closed guards that stop a start before it can touch
+ * anything (Jira connector plan J3: D6, D7, D8); which connectors an instance
+ * serves is `platform/connectorSet.ts`. They run in the CLI preflight — before
+ * the console tee, the lock and the bot module — for the plain and the hot
+ * start alike.
+ *
+ * What they make impossible for an instance that serves Jira:
+ *  - using a Telegram bot token it inherited (a live bot's): with the Telegram
+ *    connector off a present `TELEGRAM_BOT_TOKEN` is fatal;
+ *  - reading the shared config files that hold such tokens: its settings come
+ *    from `ENV_FILE` only, required before any file is read;
+ *  - touching the default tmux server, where another bot's sessions live (its
+ *    boot kills every session it does not own): `TMUX_SOCKET_NAME` is required
+ *    and may not name the default server;
+ *  - acting under the operator's Atlassian identity: a Jira-only instance
+ *    refuses any `ATLASSIAN_*` variable in its environment (its own Jira
+ *    settings use other names).
+ */
+/** `tmux -L default` IS the default server. */
+const defaultTmuxSocketName = 'default';
+/** A socket NAME, never a path: `-L` puts it in tmux's own socket directory. */
+const tmuxSocketNameRe = /^[A-Za-z0-9_-]+$/;
+const atlassianEnvPrefix = 'ATLASSIAN_';
+/**
+ * The oldest Node the Jira connector runs on (R20): it loads an ES-module-only
+ * package through `require()`, unflagged from 22.12 — earlier, its first answer
+ * would crash the instance instead of refusing the start.
+ */
+const jiraMinimumNodeVersion = [22, 12];
+/** Is `version` (`process.versions.node`, e.g. `22.11.0`) older than `minimum`? */
+function checkIsNodeVersionBelow(version, minimum) {
+    const [major = 0, minor = 0] = version.split('.').map((part) => Number.parseInt(part, 10));
+    return major < minimum[0] || (major === minimum[0] && minor < minimum[1]);
+}
+const envFileRequiredError = 'CONNECTORS lists jira: set ENV_FILE to the instance\'s own env file (it is the only file read)';
+/**
+ * @description The guard that must hold BEFORE any env file is read: an instance
+ * the shell already marks as serving Jira reads its settings from `ENV_FILE`
+ * only, so the shared config files (which hold a live bot's token) are never
+ * opened. A `CONNECTORS` the shell sets but that does not parse is refused here
+ * too: it cannot tell whether the instance was meant to serve Jira.
+ */
+function getPreloadGuardErrors(env) {
+    const parsed = (0, connectorSet_1.parseConnectors)(env.CONNECTORS);
+    if (!parsed.ok)
+        return [parsed.error];
+    if (!parsed.connectors.includes('jira') || env.ENV_FILE)
+        return [];
+    return [envFileRequiredError];
+}
+/**
+ * @description The guards on the loaded environment. Names only — never a value.
+ * `envFileAtLaunch` is `ENV_FILE` as it was BEFORE the load: only that value
+ * says the instance read nothing but its own file, since a shared config file
+ * may itself define `ENV_FILE`.
+ */
+function getConnectorGuardErrors(input) {
+    const { env } = input;
+    const parsed = (0, connectorSet_1.parseConnectors)(env.CONNECTORS);
+    if (!parsed.ok)
+        return [parsed.error];
+    const isTelegramServed = parsed.connectors.includes('telegram');
+    const isJiraServed = parsed.connectors.includes('jira');
+    const errors = [];
+    if (!isTelegramServed && env.TELEGRAM_BOT_TOKEN) {
+        errors.push('TELEGRAM_BOT_TOKEN is set but the telegram connector is off: refusing a bot token this instance must not use');
+    }
+    if (env.ENV_FILE !== input.envFileAtLaunch) {
+        // The env load already happened from other files; in hot mode the worker would then read a different one.
+        errors.push('ENV_FILE is set inside an env file: it may only come from the launching environment');
+    }
+    else if (isJiraServed && !input.envFileAtLaunch) {
+        errors.push(envFileRequiredError);
+    }
+    if (isJiraServed && checkIsNodeVersionBelow(input.nodeVersion, jiraMinimumNodeVersion)) {
+        errors.push(`CONNECTORS lists jira: Node ${input.nodeVersion} is too old — the Jira connector needs Node ${jiraMinimumNodeVersion.join('.')} or newer`);
+    }
+    if (isJiraServed && !input.hasJiraConfig) {
+        errors.push(`CONNECTORS lists jira but DATA_DIR has no ${configFile_1.jiraConfigFileName}`);
+    }
+    const tmuxSocketName = env.TMUX_SOCKET_NAME;
+    if (tmuxSocketName !== undefined && (!tmuxSocketNameRe.test(tmuxSocketName) || tmuxSocketName === defaultTmuxSocketName)) {
+        errors.push(`TMUX_SOCKET_NAME must be a plain name other than "${defaultTmuxSocketName}" (letters, digits, "_", "-")`);
+    }
+    else if (isJiraServed && !tmuxSocketName) {
+        errors.push('CONNECTORS lists jira: set TMUX_SOCKET_NAME — this instance must not use the default tmux server');
+    }
+    if (isJiraServed && !isTelegramServed) {
+        const atlassianNames = Object.keys(env).filter((name) => name.startsWith(atlassianEnvPrefix)).sort();
+        if (atlassianNames.length > 0) {
+            errors.push(`a Jira-only instance refuses Atlassian variables in its environment: ${atlassianNames.join(', ')}`);
+        }
+    }
+    return errors;
+}
+function exitOnGuardErrors(errors) {
+    if (errors.length === 0)
+        return;
+    for (const error of errors)
+        process.stderr.write(`[startup] ${error}\n`);
+    process.exit(1);
+}
+/**
+ * @description Load the env files between the two guard passes — the ONE way the
+ * CLI starts (plain and hot), so no start skips a guard. Exits 1 on a breach.
+ */
+function loadEnvWithConnectorGuards(localDirectory) {
+    exitOnGuardErrors(getPreloadGuardErrors(process.env));
+    const envFileAtLaunch = process.env.ENV_FILE;
+    const result = (0, envLoader_1.loadEnvFiles)(localDirectory);
+    const hasJiraConfig = fs.existsSync((0, configFile_1.getJiraConfigPath)((0, state_1.resolveDataDir)()));
+    exitOnGuardErrors(getConnectorGuardErrors({ env: process.env, hasJiraConfig, envFileAtLaunch, nodeVersion: process.versions.node }));
+    return result;
+}
+//# sourceMappingURL=connectorGuards.js.map

package/dist/cli/connectorGuards.js.map

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

package/dist/cli/envLoader.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @description Path to the per-user global config file.
+ *
+ * Prefers the canonical `~/.config/telegramcode/.env`; falls back to the
+ * legacy `~/.config/telegram-code/.env` when only that one exists. When
+ * neither exists the canonical path is returned, so callers report the
+ * location a fresh install should use.
+ *
+ * Resolved lazily per call — tests may swap `HOME` between cases.
+ */
+export declare function globalEnvPath(): string;
+/** @description Path to the local `.env` for a supplied directory (defaults to `$PWD`). */
+export declare function localEnvPath(localDirectory?: string): string;
+/**
+ * @description Load environment from the wrapper's two well-known locations.
+ *
+ * Order is **global first, local second** so that `dotenv.config({ override: true })`
+ * on the local file gives `<localDirectory>/.env` last-write-wins semantics over
+ * the global. Both files are optional; if neither exists this is a no-op. The
+ * explicit directory lets a supervisor load its worker's project config without
+ * changing the operator-facing process cwd.
+ *
+ * The first load uses `override: false` so that variables already in
+ * `process.env` (set by the user's shell, systemd, etc.) win against the
+ * global file — matching how `dotenv/config` behaves today. The local file
+ * then forces an override only for keys it explicitly sets.
+ *
+ * Returns the list of paths actually read, in load order. Useful for the
+ * `telegramcode` startup banner and for test assertions.
+ */
+export declare function loadEnvFiles(localDirectory?: string): {
+    loaded: string[];
+};
+//# sourceMappingURL=envLoader.d.ts.map

package/dist/cli/envLoader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envLoader.d.ts","sourceRoot":"","sources":["../../src/cli/envLoader.ts"],"names":[],"mappings":"AAkBA;;;;;;;;;GASG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAMtC;AAED,2FAA2F;AAC3F,wBAAgB,YAAY,CAAC,cAAc,SAAgB,GAAG,MAAM,CAEnE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,cAAc,SAAgB,GAAG;IAAE,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAuCjF"}

package/dist/cli/envLoader.js

@@ -0,0 +1,132 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.globalEnvPath = globalEnvPath;
+exports.localEnvPath = localEnvPath;
+exports.loadEnvFiles = loadEnvFiles;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const dotenv = __importStar(require("dotenv"));
+const agentEnvironment_1 = require("../utils/agentEnvironment");
+/** Canonical per-user config dir name under `~/.config` (post-rename). */
+const configDirName = 'telegramcode';
+/**
+ * Pre-rename config dir name — still honoured as a fallback so installs
+ * that predate the `telegramcode` rename keep working without moving files.
+ */
+const legacyConfigDirName = 'telegram-code';
+function buildGlobalEnvPath(dirName) {
+    return path.join(os.homedir(), '.config', dirName, '.env');
+}
+/**
+ * @description Path to the per-user global config file.
+ *
+ * Prefers the canonical `~/.config/telegramcode/.env`; falls back to the
+ * legacy `~/.config/telegram-code/.env` when only that one exists. When
+ * neither exists the canonical path is returned, so callers report the
+ * location a fresh install should use.
+ *
+ * Resolved lazily per call — tests may swap `HOME` between cases.
+ */
+function globalEnvPath() {
+    const canonicalPath = buildGlobalEnvPath(configDirName);
+    if (fs.existsSync(canonicalPath))
+        return canonicalPath;
+    const legacyPath = buildGlobalEnvPath(legacyConfigDirName);
+    if (fs.existsSync(legacyPath))
+        return legacyPath;
+    return canonicalPath;
+}
+/** @description Path to the local `.env` for a supplied directory (defaults to `$PWD`). */
+function localEnvPath(localDirectory = process.cwd()) {
+    return path.join(localDirectory, '.env');
+}
+/**
+ * @description Load environment from the wrapper's two well-known locations.
+ *
+ * Order is **global first, local second** so that `dotenv.config({ override: true })`
+ * on the local file gives `<localDirectory>/.env` last-write-wins semantics over
+ * the global. Both files are optional; if neither exists this is a no-op. The
+ * explicit directory lets a supervisor load its worker's project config without
+ * changing the operator-facing process cwd.
+ *
+ * The first load uses `override: false` so that variables already in
+ * `process.env` (set by the user's shell, systemd, etc.) win against the
+ * global file — matching how `dotenv/config` behaves today. The local file
+ * then forces an override only for keys it explicitly sets.
+ *
+ * Returns the list of paths actually read, in load order. Useful for the
+ * `telegramcode` startup banner and for test assertions.
+ */
+function loadEnvFiles(localDirectory = process.cwd()) {
+    // An isolated instance (Jira connector plan J3, D7): ONLY its own file — no
+    // global config, no legacy config, no `$PWD/.env`, which may hold another
+    // bot's token. It wins over the inherited environment.
+    const envFile = process.env.ENV_FILE;
+    if (envFile !== undefined) {
+        if (!path.isAbsolute(envFile))
+            throw new Error(`ENV_FILE must be an absolute path (got "${envFile}")`);
+        if (!fs.existsSync(envFile))
+            throw new Error(`ENV_FILE does not exist: ${envFile}`);
+        if (!fs.statSync(envFile).isFile())
+            throw new Error(`ENV_FILE is not a regular file: ${envFile}`);
+        // dotenv REPORTS a read failure instead of throwing; ignoring it would start
+        // the instance on the inherited environment with nothing loaded.
+        const { error, parsed } = dotenv.config({ path: envFile, override: true });
+        if (error)
+            throw new Error(`ENV_FILE could not be read: ${envFile} (${error.message})`);
+        // R32: what the instance file set never reaches a tracker conversation's agent.
+        (0, agentEnvironment_1.addEnvFileVariableNames)(Object.keys(parsed ?? {}));
+        return { loaded: [envFile] };
+    }
+    const loaded = [];
+    const globalPath = globalEnvPath();
+    if (fs.existsSync(globalPath)) {
+        dotenv.config({ path: globalPath, override: false });
+        loaded.push(globalPath);
+        if (globalPath === buildGlobalEnvPath(legacyConfigDirName)) {
+            process.stderr.write(`Using legacy config ${globalPath} — preferred location: ` +
+                `~/.config/${configDirName}/.env\n`);
+        }
+    }
+    const localPath = localEnvPath(localDirectory);
+    if (fs.existsSync(localPath)) {
+        dotenv.config({ path: localPath, override: true });
+        loaded.push(localPath);
+    }
+    return { loaded };
+}
+//# sourceMappingURL=envLoader.js.map

package/dist/cli/envLoader.js.map

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

package/dist/cli/hot.d.ts

@@ -0,0 +1,82 @@
+interface HotOpenCodeDeps {
+    checkIsInstalled: (toolName: string) => boolean;
+    ensureOpenCodeServer: () => Promise<void>;
+    stopOpenCodeServer: () => void;
+    writeWarning: (message: string) => void;
+}
+type HotChildName = 'tsc' | 'nodemon';
+/**
+ * @description Wrapper-entry for `telegramcode hot` — hot-reload mode for
+ * the global terminal bin.
+ *
+ * **What it does:** starts `tsc -w` from the project root, then starts
+ * `nodemon` only after the watcher's first completed compile. Editing any
+ * `src/**` file rebuilds `dist/` and nodemon restarts the internal
+ * `dist/cli/botEntry.js` worker on the new artifact. The bot's own
+ * graceful-shutdown sequence (state flush → lock release → exit) makes the
+ * old → new handoff clean enough that mid-work agent sessions are re-attached
+ * on the next boot. OpenCode is pre-started by this long-lived supervisor;
+ * later generations use a one-shot external host, so none remain inside
+ * nodemon's worker subtree and in-flight turns survive reloads.
+ *
+ * **Why it lives in the bin** (not only as `yarn hot`): the user runs
+ * `telegramcode` as a globally-installed `npm link` symlink, so they don't
+ * have a yarn project in front of them. Exposing hot reload as a
+ * subcommand makes the same workflow reachable from any CWD — we just
+ * resolve the project root from the bin's own realpath. `yarn hot` in the
+ * repo is the in-project equivalent.
+ *
+ * **Failure modes handled:**
+ *   - fresh checkout → nodemon waits until `tsc -w` produces the worker entry;
+ *   - broken intermediate TS edit → `tsc -w` doesn't emit, so nodemon
+ *     never sees a new artifact and the running bot keeps serving;
+ *   - bot crash at runtime (e.g. a second poller appears and Telegram
+ *     answers 409) → nodemon's `exitcrash` exits instead of parking on
+ *     "app crashed - waiting for file changes", so this wrapper tears
+ *     down and the supervisor (systemd) starts a clean generation.
+ *     Without it the wrapper stays alive with no bot under it, and the
+ *     service looks `active (running)` while the bot is dead;
+ *   - wrapper termination → tsc receives the original signal, while nodemon
+ *     receives its graceful `SIGINT`; we wait for both before exiting.
+ *
+ * `yarn hot` reaches this same wrapper. It spawns directly so the installed
+ * bin doesn't need any devDep but `nodemon` + `typescript`
+ * (always present in this project because the consumer of the bin IS this
+ * project — `npm link` exposes the same `node_modules/.bin`).
+ */
+export declare function runHot(): Promise<void>;
+/**
+ * @description Select the signal used to stop each hot-mode watcher. Nodemon's
+ * SIGTERM handler can terminate its shell before the asynchronous process-tree
+ * sweep reaches the bot worker, leaving that worker alive with the instance
+ * lock. SIGINT follows nodemon's graceful quit path and waits for the tree.
+ */
+export declare function getHotChildShutdownSignal(childName: HotChildName, wrapperSignal: NodeJS.Signals): NodeJS.Signals;
+/** Return a failing wrapper code whenever a watcher stops on its own. */
+export declare function getUnexpectedHotChildExitCode(code: number | null): number;
+export declare function checkIsHotModeSupported(platform: typeof process.platform): boolean;
+export declare function checkIsTscWatchReady(text: string): boolean;
+/**
+ * @description Pre-start OpenCode in the long-lived hot supervisor, outside
+ * nodemon's worker subtree. A missing binary or failed start stays non-fatal:
+ * hot mode must still serve Claude/terminal and the worker can retry OpenCode
+ * through the externally hosted startup path.
+ */
+export declare function prepareHotOpenCodeServer(deps?: HotOpenCodeDeps): Promise<boolean>;
+/**
+ * @description Build the env handed to the hot-mode worker (nodemon → bot).
+ *
+ * In hot mode the supervisor runs `nodemon` with cwd = projectRoot (it must,
+ * to watch `dist/`), and the worker (`node dist/cli/botEntry.js`) inherits that
+ * cwd. Left alone the worker would default `WORK_ROOT` to `process.cwd()` =
+ * the project checkout, so `/bind` would list folders inside the Charness
+ * checkout instead of the operator's projects parent. We hand the worker the real
+ * launch dir as `WORK_ROOT` so it binds against where the wrapper was started.
+ *
+ * An explicit `WORK_ROOT` in the inherited env always wins (advanced
+ * override); empty/unset falls back to `launchCwd` — matching how `runBot`
+ * itself treats `WORK_ROOT` (`!process.env.WORK_ROOT`).
+ */
+export declare function buildHotWorkerEnv(baseEnv: NodeJS.ProcessEnv, launchCwd: string): NodeJS.ProcessEnv;
+export {};
+//# sourceMappingURL=hot.d.ts.map

package/dist/cli/hot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hot.d.ts","sourceRoot":"","sources":["../../src/cli/hot.ts"],"names":[],"mappings":"AAeA,UAAU,eAAe;IACvB,gBAAgB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;IAChD,oBAAoB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,kBAAkB,EAAE,MAAM,IAAI,CAAC;IAC/B,YAAY,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AAED,KAAK,YAAY,GAAG,KAAK,GAAG,SAAS,CAAC;AAMtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAsB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CA2J5C;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,YAAY,EACvB,aAAa,EAAE,MAAM,CAAC,OAAO,GAC5B,MAAM,CAAC,OAAO,CAEhB;AAED,yEAAyE;AACzE,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAEzE;AAED,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,OAAO,OAAO,CAAC,QAAQ,GAAG,OAAO,CAElF;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED;;;;;GAKG;AACH,wBAAsB,wBAAwB,CAC5C,IAAI,GAAE,eAKL,GACA,OAAO,CAAC,OAAO,CAAC,CAclB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,CAAC,UAAU,EAC1B,SAAS,EAAE,MAAM,GAChB,MAAM,CAAC,UAAU,CAMnB"}