charness 0.0.0-stage → 3.1.0

package/dist/scheduler/engine.js

@@ -0,0 +1,337 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.maxTimeoutMs = void 0;
+exports.createSchedulerEngine = createSchedulerEngine;
+const node_crypto_1 = require("node:crypto");
+const recurrence_1 = require("./recurrence");
+/**
+ * @description The scheduler timer engine (plan S3). Owns one `setTimeout` per
+ * armed job, the boot replay (`rearmAll`), and the no-overlap guard. It is
+ * deliberately decoupled from `bot.ts`: every external concern is injected via
+ * {@link SchedulerEngineDeps} (the store, the run ledger, a `deliver` callback,
+ * a clock, and optional timer functions), so the engine is constructible in a
+ * test with a fake clock and a fake `deliver`.
+ *
+ * Lifecycle of one job:
+ *
+ *   armJob(record)  → setTimeout(nextRunAt − now), clamped to {@link maxTimeoutMs}
+ *       │              (a longer delay arms an INTERMEDIATE timer that re-arms).
+ *       ▼
+ *   timer fires → re-read the FRESH record from the store (it may have been
+ *       │          removed/paused since arming); then:
+ *       │            gone        → disarm, no-op
+ *       │            paused      → ledger 'paused-skip', disarm (do NOT re-arm)
+ *       │            in-flight   → ledger 'skipped-overlap', recompute + re-arm
+ *       │            otherwise   → fire()
+ *       ▼
+ *   fire() → ledger begin record → await deliver(job, fireContext) (wrapped:
+ *       │     a thrown deliver is classified 'failed', never kills the engine)
+ *       │   → bookkeeping (lastRunAt/lastRunStatus; recurring recompute+re-arm;
+ *       │     N-times decrement, remove at 0; one-shot remove) → store.flush()
+ *       ▼     → ledger end record (always written).
+ */
+/**
+ * Node's `setTimeout` clamps any delay above 2^31−1 ms (~24.8 days) to 1, which
+ * would fire the timer immediately. For a job further out than this we arm an
+ * INTERMEDIATE timer at the cap that simply re-arms when it fires, walking the
+ * delay down in cap-sized hops until it fits.
+ */
+exports.maxTimeoutMs = 2_147_483_647;
+/** Length of the hex run-id minted per fire for the ledger correlation. */
+const runIdByteLength = 8;
+function createSchedulerEngine(deps) {
+    const { store, ledger, deliver, now } = deps;
+    const armTimer = deps.setTimeoutFn ?? ((callback, delayMs) => setTimeout(callback, delayMs));
+    const clearTimer = deps.clearTimeoutFn ?? ((handle) => clearTimeout(handle));
+    /** jobId → its armed timer handle. The single source of truth for "is armed". */
+    const timers = new Map();
+    /** jobIds whose delivery is currently in flight — the no-overlap guard. */
+    const inFlight = new Set();
+    /**
+     * Every still-running timer-callback chain (`onTimer`). `whenIdle` awaits
+     * these; entries remove themselves on settle. A Set (not a count) so the
+     * same job firing twice tracks both chains.
+     */
+    const activeChains = new Set();
+    /** Run an `onTimer` chain, tracking it so {@link whenIdle} can await it. */
+    function trackChain(jobId) {
+        const chain = onTimer(jobId).finally(() => {
+            activeChains.delete(chain);
+        });
+        activeChains.add(chain);
+    }
+    async function whenIdle() {
+        // Re-snapshot until stable: a settling chain may have re-armed nothing, but
+        // an overlap/bookkeeping path can spawn follow-up awaits within the same
+        // chain; awaiting the snapshot then re-checking covers chains added late.
+        while (activeChains.size > 0) {
+            await Promise.allSettled([...activeChains]);
+        }
+    }
+    function disarmJob(jobId) {
+        const handle = timers.get(jobId);
+        if (handle) {
+            clearTimer(handle);
+            timers.delete(jobId);
+        }
+    }
+    /**
+     * Arm a timer for `jobId` due at `dueAtMs`. Delays beyond {@link maxTimeoutMs}
+     * arm an intermediate hop that re-arms toward the real due time. Any existing
+     * timer for the job is cleared first so re-arming never leaks a timer.
+     */
+    function armAt(jobId, dueAtMs) {
+        disarmJob(jobId);
+        const delayMs = Math.max(0, dueAtMs - now());
+        if (delayMs > exports.maxTimeoutMs) {
+            const intermediate = armTimer(() => armAt(jobId, dueAtMs), exports.maxTimeoutMs);
+            intermediate.unref?.();
+            timers.set(jobId, intermediate);
+            return;
+        }
+        const handle = armTimer(() => {
+            trackChain(jobId);
+        }, delayMs);
+        handle.unref?.();
+        timers.set(jobId, handle);
+    }
+    function armJob(record) {
+        if (record.isPaused) {
+            // Paused jobs stay disarmed silently — no ledger entry (a 'paused-skip'
+            // is only for a fire attempt that races a pause, see onTimer).
+            disarmJob(record.id);
+            return;
+        }
+        if (record.nextRunAt === null) {
+            disarmJob(record.id);
+            return;
+        }
+        armAt(record.id, record.nextRunAt);
+    }
+    /**
+     * Timer callback for `jobId`. Re-reads the fresh record (it may have changed
+     * between arm and fire), applies the re-validate / overlap / paused gates,
+     * and dispatches to {@link fire}. Never throws — a thrown body would escape
+     * the timer callback and could take the process down.
+     */
+    async function onTimer(jobId) {
+        try {
+            // The armed timer has now fired; drop its handle so disarm is a no-op and
+            // re-arms below install a clean one.
+            timers.delete(jobId);
+            const record = store.getSchedules()[jobId];
+            if (!record) {
+                // Removed between arm and fire — nothing to do, nothing armed.
+                return;
+            }
+            if (record.isPaused) {
+                ledger.append({
+                    runId: mintRunId(),
+                    jobId,
+                    threadKey: record.threadKey,
+                    firedAt: now(),
+                    kind: 'paused-skip',
+                });
+                // Do NOT re-arm — a paused job stays disarmed until resumed (S8).
+                return;
+            }
+            if (inFlight.has(jobId)) {
+                // Previous fire still delivering — skip this occurrence, advance, re-arm.
+                ledger.append({
+                    runId: mintRunId(),
+                    jobId,
+                    threadKey: record.threadKey,
+                    firedAt: now(),
+                    kind: 'skipped-overlap',
+                });
+                await advanceOverlap(record);
+                return;
+            }
+            await fire(record);
+        }
+        catch (error) {
+            console.error(`[scheduler] timer callback failed for job ${jobId}:`, error);
+        }
+    }
+    /**
+     * After a skipped-overlap: persist the advanced `nextRunAt` (recurring) or
+     * leave a one-shot/N-times-final alone, and re-arm if there is a next run.
+     * Bookkeeping here is light — the skip is not a "run", so lastRunStatus is
+     * recorded as 'skipped-overlap' for visibility but remainingRuns is untouched.
+     */
+    async function advanceOverlap(record) {
+        const nextRunAt = (0, recurrence_1.getNextRunAt)(record.spec, now());
+        const updated = {
+            ...record,
+            lastRunAt: now(),
+            lastRunStatus: 'skipped-overlap',
+            nextRunAt,
+            updatedAt: new Date(now()).toISOString(),
+        };
+        if (nextRunAt === null) {
+            // A one-shot that overlapped its own (already-elapsed) instant: nothing
+            // more to run, drop the record like a completed one-shot.
+            await store.removeSchedule(record.id);
+        }
+        else {
+            await store.upsertSchedule(updated);
+            armAt(record.id, nextRunAt);
+        }
+        await store.flush();
+    }
+    /**
+     * Execute one fire: ledger begin, await the (wrapped) deliver, bookkeeping,
+     * flush, ledger end. Classifies a thrown deliver as 'failed' so an exception
+     * never skips bookkeeping or kills the engine.
+     */
+    async function fire(record) {
+        const runId = mintRunId();
+        const firedAt = now();
+        const decision = (0, recurrence_1.getCatchUpDecision)({ nextRunAt: record.nextRunAt, nowMs: firedAt });
+        const isCatchUp = decision === 'fire-missed';
+        const fireContext = isCatchUp
+            ? { kind: 'catch-up', missedAtMs: record.nextRunAt ?? undefined }
+            : { kind: 'on-time' };
+        ledger.append({
+            runId,
+            jobId: record.id,
+            threadKey: record.threadKey,
+            firedAt,
+            kind: isCatchUp ? 'catch-up' : 'on-time',
+        });
+        inFlight.add(record.id);
+        let outcome;
+        try {
+            outcome = await deliver(record, fireContext);
+        }
+        catch (error) {
+            outcome = { status: 'failed', error: error instanceof Error ? error.message : String(error) };
+        }
+        finally {
+            inFlight.delete(record.id);
+        }
+        const deliveredAt = now();
+        try {
+            await applyBookkeeping(record, outcome, deliveredAt);
+        }
+        catch (error) {
+            console.error(`[scheduler] bookkeeping failed for job ${record.id}:`, error);
+        }
+        ledger.append({
+            runId,
+            jobId: record.id,
+            threadKey: record.threadKey,
+            firedAt,
+            kind: isCatchUp ? 'catch-up' : 'on-time',
+            deliveredAt,
+            ...(outcome.status === 'failed' && outcome.error ? { error: outcome.error } : {}),
+        });
+    }
+    /**
+     * Update the record after a completed fire and re-arm (or remove). Reads the
+     * fresh record again so a pause/removal during delivery is respected. flush()
+     * is awaited because `nextRunAt`/`remainingRuns` are crash-critical.
+     */
+    async function applyBookkeeping(original, outcome, deliveredAt) {
+        const fresh = store.getSchedules()[original.id];
+        if (!fresh) {
+            // Removed mid-delivery — leave it gone, just make sure nothing is armed.
+            disarmJob(original.id);
+            await store.flush();
+            return;
+        }
+        if (fresh.isPaused) {
+            // Paused DURING delivery (e.g. the deliver callback hit an unbound topic
+            // and parked the job, S8): the engine never arms a paused job, so do NOT
+            // re-arm a recurring one or delete a one-shot — just stay disarmed and let
+            // the rebind-resume path own its lifecycle. (A pause BEFORE the timer fires
+            // is caught earlier in onTimer as a paused-skip.)
+            disarmJob(fresh.id);
+            await store.flush();
+            return;
+        }
+        const lastRunStatus = outcome.status === 'delivered' ? 'delivered' : 'failed';
+        if (fresh.spec.kind === 'once') {
+            await store.removeSchedule(fresh.id);
+            disarmJob(fresh.id);
+            await store.flush();
+            return;
+        }
+        // cron (possibly N-times)
+        if (typeof fresh.spec.remainingRuns === 'number') {
+            const remaining = fresh.spec.remainingRuns - 1;
+            if (remaining <= 0) {
+                await store.removeSchedule(fresh.id);
+                disarmJob(fresh.id);
+                await store.flush();
+                return;
+            }
+            const nextRunAt = (0, recurrence_1.getNextRunAt)(fresh.spec, deliveredAt);
+            const updated = {
+                ...fresh,
+                spec: { ...fresh.spec, remainingRuns: remaining },
+                lastRunAt: deliveredAt,
+                lastRunStatus,
+                nextRunAt,
+                updatedAt: new Date(deliveredAt).toISOString(),
+            };
+            await store.upsertSchedule(updated);
+            if (nextRunAt !== null)
+                armAt(fresh.id, nextRunAt);
+            else
+                disarmJob(fresh.id);
+            await store.flush();
+            return;
+        }
+        // plain recurring cron
+        const nextRunAt = (0, recurrence_1.getNextRunAt)(fresh.spec, deliveredAt);
+        const updated = {
+            ...fresh,
+            lastRunAt: deliveredAt,
+            lastRunStatus,
+            nextRunAt,
+            updatedAt: new Date(deliveredAt).toISOString(),
+        };
+        await store.upsertSchedule(updated);
+        if (nextRunAt !== null)
+            armAt(fresh.id, nextRunAt);
+        else
+            disarmJob(fresh.id);
+        await store.flush();
+    }
+    /**
+     * Boot replay. Walks every persisted job:
+     *   - paused → skip silently (stays disarmed; no ledger entry).
+     *   - nextRunAt missed (getCatchUpDecision → 'fire-missed') → fire ONCE as a
+     *     catch-up (the deliver callback gets `missedAtMs`), then bookkeeping
+     *     already recomputed nextRunAt from now and re-armed.
+     *   - on-time / future → just arm.
+     * Catch-ups run sequentially (await) so a burst of missed jobs paces its
+     * announcements through the shared chat send budget.
+     */
+    async function rearmAll() {
+        const all = store.getSchedules();
+        for (const record of Object.values(all)) {
+            if (record.isPaused)
+                continue;
+            const decision = (0, recurrence_1.getCatchUpDecision)({ nextRunAt: record.nextRunAt, nowMs: now() });
+            if (decision === 'fire-missed') {
+                // fire() reads the same catch-up decision and handles re-arming via
+                // bookkeeping; nothing else to arm here.
+                await fire(record);
+                continue;
+            }
+            armJob(record);
+        }
+    }
+    function shutdown() {
+        for (const handle of timers.values())
+            clearTimer(handle);
+        timers.clear();
+    }
+    function mintRunId() {
+        return (0, node_crypto_1.randomBytes)(runIdByteLength).toString('hex');
+    }
+    return { armJob, disarmJob, rearmAll, whenIdle, shutdown };
+}
+//# sourceMappingURL=engine.js.map

package/dist/scheduler/engine.js.map

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

package/dist/scheduler/injection.d.ts

@@ -0,0 +1,102 @@
+/**
+ * @description The single source of the scheduler MCP server entry injected into
+ * every bot-started agent session (plan S6). Both backends get the SAME bot-owned
+ * `telegramBot` server, just shaped for their respective MCP-config formats:
+ *   - Claude reads a `--mcp-config` file with a streamable-HTTP `mcpServers` entry
+ *     (thread-scoped token).
+ *   - OpenCode is registered at runtime via `POST /mcp?directory=` with a `remote`
+ *     server entry (directory-scoped token).
+ *
+ * This server is bot-owned plumbing — it is NOT part of the user-editable `/mcp`
+ * hierarchy (`mcpConfig.ts`) and is never written into the user's group/thread
+ * config files.
+ *
+ * INERT until S8 calls {@link configureSchedulerMcpInjection} at boot: unconfigured,
+ * every builder returns `null`, so the `prepareMcpFlags` / OpenCode-registration
+ * call sites behave byte-identically to before the scheduler existed. The module
+ * imports nothing from `bot.ts`; the secret + port arrive through the config
+ * singleton, mirroring how `mcpSurface.ts` takes its deps injected.
+ */
+import { type SessionKey } from '../sessionKey';
+import { schedulerMcpClientIdHeader } from './mcpSurface';
+/** The fixed MCP server name both backends register the injected entry under. */
+export declare const schedulerMcpServerName = "telegramBot";
+/**
+ * @name SchedulerInjectionConfig
+ * @description The boot-supplied dependencies (S8 wires these). `getSecret`
+ * returns the persisted HMAC secret used to mint scope tokens (same secret the
+ * server verifies against in {@link mcpSurface}); `port` is the bound listen
+ * port (resolved after the server starts, since a `0` request port becomes an
+ * ephemeral one) so the injected url points at the real listener.
+ */
+interface SchedulerInjectionConfig {
+    getSecret: () => Promise<string>;
+    port: number;
+}
+/**
+ * @description Activate scheduler MCP injection (plan S8 calls this at boot,
+ * after the MCP server's `start()` resolves so the bound port is known). Until
+ * called, all builders are inert. Re-calling overwrites the config (e.g. a
+ * server restart that rebinds a different ephemeral port).
+ */
+export declare function configureSchedulerMcpInjection(config: SchedulerInjectionConfig): void;
+/**
+ * @description Reset to the inert state. Intended for tests (and a future
+ * shutdown path) so a configured singleton can't leak across cases.
+ */
+export declare function resetSchedulerMcpInjection(): void;
+/**
+ * @name ClaudeSchedulerMcpConfig
+ * @description The exact JSON shape written to the bot-generated `--mcp-config`
+ * file for Claude: a single streamable-HTTP `mcpServers` entry keyed by
+ * {@link schedulerMcpServerName}, carrying the thread-scoped bearer token.
+ */
+export interface ClaudeSchedulerMcpConfig {
+    mcpServers: {
+        [schedulerMcpServerName]: {
+            type: 'http';
+            url: string;
+            headers: {
+                Authorization: string;
+                [schedulerMcpClientIdHeader]: string;
+            };
+        };
+    };
+}
+/**
+ * @description Build the Claude `--mcp-config` payload for a thread, scoped to
+ * that exact thread (`thread:<key>`). Returns `null` when injection is inert
+ * (S8 not wired) so the caller adds no extra flag. The thread key is serialised
+ * with {@link keyToString} — the same canonical form `serializeSchedulerScope`
+ * signs — so the token the server later verifies resolves to this exact thread.
+ */
+export declare function buildClaudeSchedulerMcpConfig(threadKey: SessionKey): Promise<ClaudeSchedulerMcpConfig | null>;
+/**
+ * @name OpenCodeSchedulerMcpRegistration
+ * @description The body posted to OpenCode's runtime `POST /mcp?directory=` to
+ * register the injected server for a bound folder, scoped to that directory
+ * (`dir:<path>`). OpenCode's runtime MCP shape is `remote` (vs Claude's `http`),
+ * `enabled: true`, with the directory-scoped bearer token in `headers`.
+ */
+export interface OpenCodeSchedulerMcpRegistration {
+    name: typeof schedulerMcpServerName;
+    config: {
+        type: 'remote';
+        url: string;
+        enabled: true;
+        headers: {
+            Authorization: string;
+            [schedulerMcpClientIdHeader]: string;
+        };
+    };
+}
+/**
+ * @description Build the OpenCode runtime MCP registration body for a directory,
+ * scoped to that directory (`dir:<path>`). Returns `null` when injection is
+ * inert. The directory is the bound folder (the OpenCode instance selector); the
+ * server resolves the single bound thread implicitly, or requires `threadKey`
+ * when the folder has more than one bound thread (see `resolveTargetThreadKey`).
+ */
+export declare function buildOpenCodeSchedulerMcpRegistration(directory: string): Promise<OpenCodeSchedulerMcpRegistration | null>;
+export {};
+//# sourceMappingURL=injection.d.ts.map

package/dist/scheduler/injection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"injection.d.ts","sourceRoot":"","sources":["../../src/scheduler/injection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EAAe,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,EAEL,0BAA0B,EAG3B,MAAM,cAAc,CAAC;AAEtB,iFAAiF;AACjF,eAAO,MAAM,sBAAsB,gBAAgB,CAAC;AAEpD;;;;;;;GAOG;AACH,UAAU,wBAAwB;IAChC,SAAS,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC;CACd;AAQD;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,wBAAwB,GAAG,IAAI,CAErF;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD;AAkBD;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE;QACV,CAAC,sBAAsB,CAAC,EAAE;YACxB,IAAI,EAAE,MAAM,CAAC;YACb,GAAG,EAAE,MAAM,CAAC;YACZ,OAAO,EAAE;gBACP,aAAa,EAAE,MAAM,CAAC;gBACtB,CAAC,0BAA0B,CAAC,EAAE,MAAM,CAAC;aACtC,CAAC;SACH,CAAC;KACH,CAAC;CACH;AAED;;;;;;GAMG;AACH,wBAAsB,6BAA6B,CACjD,SAAS,EAAE,UAAU,GACpB,OAAO,CAAC,wBAAwB,GAAG,IAAI,CAAC,CAiB1C;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gCAAgC;IAC/C,IAAI,EAAE,OAAO,sBAAsB,CAAC;IACpC,MAAM,EAAE;QACN,IAAI,EAAE,QAAQ,CAAC;QACf,GAAG,EAAE,MAAM,CAAC;QACZ,OAAO,EAAE,IAAI,CAAC;QACd,OAAO,EAAE;YACP,aAAa,EAAE,MAAM,CAAC;YACtB,CAAC,0BAA0B,CAAC,EAAE,MAAM,CAAC;SACtC,CAAC;KACH,CAAC;CACH;AAED;;;;;;GAMG;AACH,wBAAsB,qCAAqC,CACzD,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,gCAAgC,GAAG,IAAI,CAAC,CAiBlD"}

package/dist/scheduler/injection.js

@@ -0,0 +1,122 @@
+"use strict";
+/**
+ * @description The single source of the scheduler MCP server entry injected into
+ * every bot-started agent session (plan S6). Both backends get the SAME bot-owned
+ * `telegramBot` server, just shaped for their respective MCP-config formats:
+ *   - Claude reads a `--mcp-config` file with a streamable-HTTP `mcpServers` entry
+ *     (thread-scoped token).
+ *   - OpenCode is registered at runtime via `POST /mcp?directory=` with a `remote`
+ *     server entry (directory-scoped token).
+ *
+ * This server is bot-owned plumbing — it is NOT part of the user-editable `/mcp`
+ * hierarchy (`mcpConfig.ts`) and is never written into the user's group/thread
+ * config files.
+ *
+ * INERT until S8 calls {@link configureSchedulerMcpInjection} at boot: unconfigured,
+ * every builder returns `null`, so the `prepareMcpFlags` / OpenCode-registration
+ * call sites behave byte-identically to before the scheduler existed. The module
+ * imports nothing from `bot.ts`; the secret + port arrive through the config
+ * singleton, mirroring how `mcpSurface.ts` takes its deps injected.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.schedulerMcpServerName = void 0;
+exports.configureSchedulerMcpInjection = configureSchedulerMcpInjection;
+exports.resetSchedulerMcpInjection = resetSchedulerMcpInjection;
+exports.buildClaudeSchedulerMcpConfig = buildClaudeSchedulerMcpConfig;
+exports.buildOpenCodeSchedulerMcpRegistration = buildOpenCodeSchedulerMcpRegistration;
+const node_crypto_1 = require("node:crypto");
+const sessionKey_1 = require("../sessionKey");
+const mcpSurface_1 = require("./mcpSurface");
+/** The fixed MCP server name both backends register the injected entry under. */
+exports.schedulerMcpServerName = 'telegramBot';
+/**
+ * Module-level singleton. `null` = unconfigured = inert: every builder returns
+ * `null` and the call sites add nothing. Set exactly once by S8 at boot.
+ */
+let injectionConfig = null;
+/**
+ * @description Activate scheduler MCP injection (plan S8 calls this at boot,
+ * after the MCP server's `start()` resolves so the bound port is known). Until
+ * called, all builders are inert. Re-calling overwrites the config (e.g. a
+ * server restart that rebinds a different ephemeral port).
+ */
+function configureSchedulerMcpInjection(config) {
+    injectionConfig = config;
+}
+/**
+ * @description Reset to the inert state. Intended for tests (and a future
+ * shutdown path) so a configured singleton can't leak across cases.
+ */
+function resetSchedulerMcpInjection() {
+    injectionConfig = null;
+}
+/** The loopback url the injected entry points at: `http://127.0.0.1:<port>/mcp`. */
+function buildSchedulerMcpUrl(port) {
+    return `http://127.0.0.1:${port}${mcpSurface_1.schedulerMcpPath}`;
+}
+/**
+ * @description Mint a bearer token for a scope using the configured secret.
+ * Reuses {@link buildSchedulerMcpToken} (and via it `serializeSchedulerScope`)
+ * so the token math lives in exactly one place. Returns `null` when inert.
+ */
+async function buildBearerHeader(scope) {
+    if (!injectionConfig)
+        return null;
+    const secret = await injectionConfig.getSecret();
+    return `Bearer ${(0, mcpSurface_1.buildSchedulerMcpToken)(secret, scope)}`;
+}
+/**
+ * @description Build the Claude `--mcp-config` payload for a thread, scoped to
+ * that exact thread (`thread:<key>`). Returns `null` when injection is inert
+ * (S8 not wired) so the caller adds no extra flag. The thread key is serialised
+ * with {@link keyToString} — the same canonical form `serializeSchedulerScope`
+ * signs — so the token the server later verifies resolves to this exact thread.
+ */
+async function buildClaudeSchedulerMcpConfig(threadKey) {
+    if (!injectionConfig)
+        return null;
+    const scope = { kind: 'thread', threadKey: (0, sessionKey_1.keyToString)(threadKey) };
+    const authorization = await buildBearerHeader(scope);
+    if (authorization === null)
+        return null;
+    return {
+        mcpServers: {
+            [exports.schedulerMcpServerName]: {
+                type: 'http',
+                url: buildSchedulerMcpUrl(injectionConfig.port),
+                headers: {
+                    Authorization: authorization,
+                    [mcpSurface_1.schedulerMcpClientIdHeader]: (0, node_crypto_1.randomUUID)(),
+                },
+            },
+        },
+    };
+}
+/**
+ * @description Build the OpenCode runtime MCP registration body for a directory,
+ * scoped to that directory (`dir:<path>`). Returns `null` when injection is
+ * inert. The directory is the bound folder (the OpenCode instance selector); the
+ * server resolves the single bound thread implicitly, or requires `threadKey`
+ * when the folder has more than one bound thread (see `resolveTargetThreadKey`).
+ */
+async function buildOpenCodeSchedulerMcpRegistration(directory) {
+    if (!injectionConfig)
+        return null;
+    const scope = { kind: 'dir', directory };
+    const authorization = await buildBearerHeader(scope);
+    if (authorization === null)
+        return null;
+    return {
+        name: exports.schedulerMcpServerName,
+        config: {
+            type: 'remote',
+            url: buildSchedulerMcpUrl(injectionConfig.port),
+            enabled: true,
+            headers: {
+                Authorization: authorization,
+                [mcpSurface_1.schedulerMcpClientIdHeader]: (0, node_crypto_1.randomUUID)(),
+            },
+        },
+    };
+}
+//# sourceMappingURL=injection.js.map

package/dist/scheduler/injection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"injection.js","sourceRoot":"","sources":["../../src/scheduler/injection.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;;AAuCH,wEAEC;AAMD,gEAEC;AA4CD,sEAmBC;AA6BD,sFAmBC;AA9JD,6CAAyC;AACzC,8CAA6D;AAC7D,6CAKsB;AAEtB,iFAAiF;AACpE,QAAA,sBAAsB,GAAG,aAAa,CAAC;AAepD;;;GAGG;AACH,IAAI,eAAe,GAAoC,IAAI,CAAC;AAE5D;;;;;GAKG;AACH,SAAgB,8BAA8B,CAAC,MAAgC;IAC7E,eAAe,GAAG,MAAM,CAAC;AAC3B,CAAC;AAED;;;GAGG;AACH,SAAgB,0BAA0B;IACxC,eAAe,GAAG,IAAI,CAAC;AACzB,CAAC;AAED,oFAAoF;AACpF,SAAS,oBAAoB,CAAC,IAAY;IACxC,OAAO,oBAAoB,IAAI,GAAG,6BAAgB,EAAE,CAAC;AACvD,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,iBAAiB,CAAC,KAAqB;IACpD,IAAI,CAAC,eAAe;QAAE,OAAO,IAAI,CAAC;IAClC,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,SAAS,EAAE,CAAC;IACjD,OAAO,UAAU,IAAA,mCAAsB,EAAC,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC;AAC3D,CAAC;AAqBD;;;;;;GAMG;AACI,KAAK,UAAU,6BAA6B,CACjD,SAAqB;IAErB,IAAI,CAAC,eAAe;QAAE,OAAO,IAAI,CAAC;IAClC,MAAM,KAAK,GAAmB,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAA,wBAAW,EAAC,SAAS,CAAC,EAAE,CAAC;IACpF,MAAM,aAAa,GAAG,MAAM,iBAAiB,CAAC,KAAK,CAAC,CAAC;IACrD,IAAI,aAAa,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACxC,OAAO;QACL,UAAU,EAAE;YACV,CAAC,8BAAsB,CAAC,EAAE;gBACxB,IAAI,EAAE,MAAM;gBACZ,GAAG,EAAE,oBAAoB,CAAC,eAAe,CAAC,IAAI,CAAC;gBAC/C,OAAO,EAAE;oBACP,aAAa,EAAE,aAAa;oBAC5B,CAAC,uCAA0B,CAAC,EAAE,IAAA,wBAAU,GAAE;iBAC3C;aACF;SACF;KACF,CAAC;AACJ,CAAC;AAsBD;;;;;;GAMG;AACI,KAAK,UAAU,qCAAqC,CACzD,SAAiB;IAEjB,IAAI,CAAC,eAAe;QAAE,OAAO,IAAI,CAAC;IAClC,MAAM,KAAK,GAAmB,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IACzD,MAAM,aAAa,GAAG,MAAM,iBAAiB,CAAC,KAAK,CAAC,CAAC;IACrD,IAAI,aAAa,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACxC,OAAO;QACL,IAAI,EAAE,8BAAsB;QAC5B,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,GAAG,EAAE,oBAAoB,CAAC,eAAe,CAAC,IAAI,CAAC;YAC/C,OAAO,EAAE,IAAI;YACb,OAAO,EAAE;gBACP,aAAa,EAAE,aAAa;gBAC5B,CAAC,uCAA0B,CAAC,EAAE,IAAA,wBAAU,GAAE;aAC3C;SACF;KACF,CAAC;AACJ,CAAC"}

package/dist/scheduler/mcpBoot.d.ts

@@ -0,0 +1,65 @@
+import { type SchedulerMcpHandle } from './mcpSurface';
+/**
+ * @description Boot-time bring-up of the bot-owned MCP server, and the ORDER of
+ * the session phase around it. Kept out of `bot.ts` so the ordering contract is
+ * testable (importing `bot.ts` runs its module-scope `parseEnv()`).
+ *
+ * The contract: the server is bound and injection is configured BEFORE any
+ * session is re-attached or resumed. A session (re)spawned at boot builds its
+ * `--mcp-config` / OpenCode registration at that moment; with injection still
+ * inert it is born WITHOUT the bot's server, and the Claude heal path never
+ * repairs an ABSENT server (`decideMcpHeal` maps it to `skip`). Such a Claude
+ * session could not reach the bot's tools for the rest of its life.
+ *
+ * The heals stay AFTER reattach: they walk only ACTIVE sessions, so run before
+ * it they would heal nothing. The schedule re-arm stays after reattach too — a
+ * catch-up fire needs the re-attached adapters.
+ */
+/**
+ * @name SchedulerMcpBootDeps
+ * @description What {@link startSchedulerMcpForBoot} needs: the server handle,
+ * the env-pinned port ({@link defaultSchedulerMcpPort} = not pinned), the
+ * persisted port of a prior boot and its writer, and the HMAC secret the
+ * injected tokens are signed with.
+ */
+export interface SchedulerMcpBootDeps {
+    handle: SchedulerMcpHandle;
+    envPort: number;
+    getPersistedPort: () => number | undefined;
+    persistPort: (port: number) => Promise<void>;
+    getSecret: () => Promise<string>;
+}
+/**
+ * @description Bind the bot MCP server and configure injection toward the bound
+ * port. Resolves `true` when the server is up. A bind failure (port busy) is
+ * logged and resolves `false`: the bot still boots and injection stays inert,
+ * so sessions spawned this run get no bot tools — a Claude one keeps lacking
+ * them after a later restart too (its process is adopted, and the heal never
+ * adds an absent server). Persisting the port is best-effort: it only serves the
+ * NEXT boot, so a failed write is logged and the bound server is still used.
+ */
+export declare function startSchedulerMcpForBoot(deps: SchedulerMcpBootDeps): Promise<boolean>;
+/**
+ * @name SessionBootPhaseSteps
+ * @description The boot steps whose relative order {@link runSessionBootPhase}
+ * owns. `restoreAfterReattach` is the per-thread state that needs to know which
+ * sessions came back (pending questions, armed retries, limit episodes, orphaned
+ * status frames); `onSessionsRestored` opens the gate the session-reading MCP
+ * tools wait on (the server already serves, a surviving session may call in);
+ * `healActiveSessions` runs only when the server is up and is best-effort — a
+ * throw is logged and never aborts the boot.
+ */
+export interface SessionBootPhaseSteps {
+    startBotMcp: () => Promise<boolean>;
+    reattachSessions: () => Promise<void>;
+    restoreAfterReattach: () => void;
+    onSessionsRestored: () => void;
+    healActiveSessions: () => void;
+    rearmSchedules: () => Promise<void>;
+}
+/**
+ * @description Run the session phase of the boot in the order the module header
+ * explains. Resolves whether the bot MCP server started, for the shutdown path.
+ */
+export declare function runSessionBootPhase(steps: SessionBootPhaseSteps): Promise<boolean>;
+//# sourceMappingURL=mcpBoot.d.ts.map

package/dist/scheduler/mcpBoot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcpBoot.d.ts","sourceRoot":"","sources":["../../src/scheduler/mcpBoot.ts"],"names":[],"mappings":"AACA,OAAO,EAA2B,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEhF;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAC3C,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,SAAS,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CAClC;AAED;;;;;;;;GAQG;AACH,wBAAsB,wBAAwB,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC,CA2B3F;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACpC,gBAAgB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,oBAAoB,EAAE,MAAM,IAAI,CAAC;IACjC,kBAAkB,EAAE,MAAM,IAAI,CAAC;IAC/B,kBAAkB,EAAE,MAAM,IAAI,CAAC;IAC/B,cAAc,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,OAAO,CAAC,CAcxF"}