charness 0.0.0-stage → 3.0.0

package/dist/scheduler/checkRun.js.map

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

package/dist/scheduler/delivery.d.ts

@@ -0,0 +1,99 @@
+import { type CheckRunResult } from './checkRun';
+import type { DeliveryOutcome, FireContext, ScheduleRecord } from './types';
+import { type PostToSessionDeps } from '../postToSession';
+/**
+ * @description Scheduler delivery (plan S4): the real `deliver(job, fireContext)`
+ * callback the engine (S3) invokes at fire time. The flow is locked by the plan:
+ *
+ *   1. announce — post a visible message into the topic (job name + human
+ *      schedule text + the prompt; a "missed at HH:MM" note for a catch-up run).
+ *   2. pin      — pin that announcement (silent ONLY when the job opted in;
+ *      default notifies all members). A pin failure degrades to a `console.warn`
+ *      and the flow continues — the announcement is already visible.
+ *   3–4. post the prefixed prompt to the session ({@link postToSession}, shared
+ *      with the Jira connector): ensure a session (starting one with the job's
+ *      `lastAdapterName` snapshot as the adapter fallback — a topic that never
+ *      picked an agent and carries no snapshot fails with `no agent selected`),
+ *      let a BUSY one finish its turn up to the wait bound, then forward. An
+ *      unbound topic → outcome `failed` with a distinct error string the engine
+ *      records (S8 turns that into a pause).
+ *
+ * A REMINDER record (`deliveryKind: 'reminder'`) stops after step 2: its whole
+ * delivery IS the announcement plus its pin, which is what pierces a muted topic.
+ * Steps 3–4 are skipped entirely, so a reminder fires in an unbound topic and in
+ * General — there is no session to ensure, nothing to interrupt, and no agent to
+ * tell about the run.
+ *
+ * A CHECK record (`deliveryKind: 'check'`) runs its command FIRST and decides
+ * from the result and its persisted failing flag: a pass after a pass, or a
+ * failure after a failure, posts nothing; a pass after a failure posts one
+ * unpinned "passes again" line; the first failure posts the alert, pins it, and
+ * then wakes the agent through steps 3–4 with the failure details ahead of the
+ * job's prompt. An unbound topic fails with the same distinct error as a prompt
+ * job, so it is paused the same way.
+ *
+ * It owns NO bot.ts import: every side effect is injected via
+ * {@link ScheduleDeliveryDeps} (announce / pin / busy probe / ensure-session /
+ * forward / clock / sleep), so bot.ts wires its existing functions in with thin
+ * lambdas (S8) and the wait-loop is unit-testable on a fake clock.
+ */
+/** Distinct error string the engine records when a fire hits an unbound topic. */
+export declare const unboundDeliveryError = "thread is unbound";
+/**
+ * @name ScheduleDeliveryDeps
+ * @description Everything the delivery callback needs from bot.ts, injected so
+ * the module stays free of bot.ts imports and the poll loop is testable.
+ * `threadKey` is the serialized `"<chatId>:<threadId>"` string carried on the
+ * record; the bot's lambdas parse it back into a `SessionKey` where needed.
+ */
+export interface ScheduleDeliveryDeps extends PostToSessionDeps {
+    /**
+     * Post the announcement into the topic (the bot bakes in priority
+     * `'interactive'`). Resolves with the sent message id, or `null` when the
+     * send failed — pinning is skipped on `null`.
+     */
+    announce: (threadKey: string, text: string) => Promise<number | null>;
+    /** Pin the announcement. `isSilent` ⇒ `disable_notification`. Rejects on failure. */
+    pin: (threadKey: string, messageId: number, isSilent: boolean) => Promise<void>;
+    /** Run a check job's command in the thread's bound folder; `null` when the thread is unbound. */
+    runCheck: (threadKey: string, command: string, timeoutMs: number) => Promise<CheckRunResult | null>;
+    /** Persist a check job's failing flag (it decides whether the next run alerts). */
+    setCheckFailing: (jobId: string, isFailing: boolean) => Promise<void>;
+}
+/**
+ * @description Prefix a scheduled job's prompt with a single English line that
+ * tells the agent THIS turn is a scheduled run — `[Scheduled run "<name>"]`.
+ * Pure, English-stable (same convention as the `[Telegram thread context]`
+ * preamble): the agent may have no memory of the schedule being created (a
+ * different session, or created by the human, not the agent), so the visible
+ * topic announcement alone is not enough — the forwarded prompt itself must
+ * carry the marker so the agent acts on it as a scheduled task, not a stray
+ * message. Kept to one line so it never overwhelms a short prompt.
+ */
+export declare function prependScheduledRunMarker(jobName: string, prompt: string, options?: {
+    dueAtMs?: number;
+}): string;
+/**
+ * @description Build the visible fire-announcement text via i18n, per delivery
+ * kind: a prompt job frames the run as a scheduled prompt for the agent, a
+ * reminder leads with its own text (the pin notification previews it, so the
+ * operator reads the reminder without opening the topic). Both interpolate the
+ * SAME `{missedNote}` — the catch-up annotation (host-local HH:MM of the missed
+ * instant) for a `catch-up` fire, empty for an `on-time` run — so a replayed run
+ * is annotated identically whichever kind it is.
+ *
+ * The `{schedule}` text differs per kind ON PURPOSE. A prompt job keeps
+ * English-only {@link describeSchedule} (its announcement is read alongside the
+ * agent-facing prompt). A reminder uses the LOCALIZED
+ * {@link getReminderScheduleText} — the very same words its `/reminders` list row
+ * and card show, because describing one reminder two different ways is a defect.
+ */
+export declare function buildFireAnnouncement(job: ScheduleRecord, fireContext: FireContext): string;
+/** @description The topic alert of a check's first failure: what failed, how, and the output tail. */
+export declare function buildCheckFailedAnnouncement(job: ScheduleRecord, fireContext: FireContext, failure: string, output: string): string;
+/**
+ * @description Build the engine's `deliver(job, fireContext)` callback bound to
+ * the injected deps. See the module header for the locked flow.
+ */
+export declare function createScheduleDelivery(deps: ScheduleDeliveryDeps): (job: ScheduleRecord, fireContext: FireContext) => Promise<DeliveryOutcome>;
+//# sourceMappingURL=delivery.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"delivery.d.ts","sourceRoot":"","sources":["../../src/scheduler/delivery.ts"],"names":[],"mappings":"AAGA,OAAO,EASL,KAAK,cAAc,EACpB,MAAM,YAAY,CAAC;AAGpB,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAC5E,OAAO,EAAiB,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,kFAAkF;AAClF,eAAO,MAAM,oBAAoB,sBAAsB,CAAC;AAExD;;;;;;GAMG;AACH,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC7D;;;;OAIG;IACH,QAAQ,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACtE,qFAAqF;IACrF,GAAG,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChF,iGAAiG;IACjG,QAAQ,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IACpG,mFAAmF;IACnF,eAAe,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvE;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,MAAM,CAGrH;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW,GAAG,MAAM,CAe3F;AASD,sGAAsG;AACtG,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,cAAc,EACnB,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GACb,MAAM,CASR;AA0FD;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,oBAAoB,GACzB,CAAC,GAAG,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW,KAAK,OAAO,CAAC,eAAe,CAAC,CAqB7E"}

package/dist/scheduler/delivery.js

@@ -0,0 +1,212 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unboundDeliveryError = void 0;
+exports.prependScheduledRunMarker = prependScheduledRunMarker;
+exports.buildFireAnnouncement = buildFireAnnouncement;
+exports.buildCheckFailedAnnouncement = buildCheckFailedAnnouncement;
+exports.createScheduleDelivery = createScheduleDelivery;
+const i18n_1 = require("../i18n");
+const reminderScheduleText_1 = require("../utils/reminderScheduleText");
+const localClock_1 = require("../utils/localClock");
+const checkRun_1 = require("./checkRun");
+const deliveryKind_1 = require("./deliveryKind");
+const recurrence_1 = require("./recurrence");
+const postToSession_1 = require("../postToSession");
+/**
+ * @description Scheduler delivery (plan S4): the real `deliver(job, fireContext)`
+ * callback the engine (S3) invokes at fire time. The flow is locked by the plan:
+ *
+ *   1. announce — post a visible message into the topic (job name + human
+ *      schedule text + the prompt; a "missed at HH:MM" note for a catch-up run).
+ *   2. pin      — pin that announcement (silent ONLY when the job opted in;
+ *      default notifies all members). A pin failure degrades to a `console.warn`
+ *      and the flow continues — the announcement is already visible.
+ *   3–4. post the prefixed prompt to the session ({@link postToSession}, shared
+ *      with the Jira connector): ensure a session (starting one with the job's
+ *      `lastAdapterName` snapshot as the adapter fallback — a topic that never
+ *      picked an agent and carries no snapshot fails with `no agent selected`),
+ *      let a BUSY one finish its turn up to the wait bound, then forward. An
+ *      unbound topic → outcome `failed` with a distinct error string the engine
+ *      records (S8 turns that into a pause).
+ *
+ * A REMINDER record (`deliveryKind: 'reminder'`) stops after step 2: its whole
+ * delivery IS the announcement plus its pin, which is what pierces a muted topic.
+ * Steps 3–4 are skipped entirely, so a reminder fires in an unbound topic and in
+ * General — there is no session to ensure, nothing to interrupt, and no agent to
+ * tell about the run.
+ *
+ * A CHECK record (`deliveryKind: 'check'`) runs its command FIRST and decides
+ * from the result and its persisted failing flag: a pass after a pass, or a
+ * failure after a failure, posts nothing; a pass after a failure posts one
+ * unpinned "passes again" line; the first failure posts the alert, pins it, and
+ * then wakes the agent through steps 3–4 with the failure details ahead of the
+ * job's prompt. An unbound topic fails with the same distinct error as a prompt
+ * job, so it is paused the same way.
+ *
+ * It owns NO bot.ts import: every side effect is injected via
+ * {@link ScheduleDeliveryDeps} (announce / pin / busy probe / ensure-session /
+ * forward / clock / sleep), so bot.ts wires its existing functions in with thin
+ * lambdas (S8) and the wait-loop is unit-testable on a fake clock.
+ */
+/** Distinct error string the engine records when a fire hits an unbound topic. */
+exports.unboundDeliveryError = 'thread is unbound';
+/**
+ * @description Prefix a scheduled job's prompt with a single English line that
+ * tells the agent THIS turn is a scheduled run — `[Scheduled run "<name>"]`.
+ * Pure, English-stable (same convention as the `[Telegram thread context]`
+ * preamble): the agent may have no memory of the schedule being created (a
+ * different session, or created by the human, not the agent), so the visible
+ * topic announcement alone is not enough — the forwarded prompt itself must
+ * carry the marker so the agent acts on it as a scheduled task, not a stray
+ * message. Kept to one line so it never overwhelms a short prompt.
+ */
+function prependScheduledRunMarker(jobName, prompt, options = {}) {
+    const dueNote = options.dueAtMs === undefined ? '' : ` · was due at ${(0, localClock_1.formatLocalDateAndClock)(options.dueAtMs)}`;
+    return `[Scheduled run "${jobName}"${dueNote}]\n${prompt}`;
+}
+/**
+ * @description Build the visible fire-announcement text via i18n, per delivery
+ * kind: a prompt job frames the run as a scheduled prompt for the agent, a
+ * reminder leads with its own text (the pin notification previews it, so the
+ * operator reads the reminder without opening the topic). Both interpolate the
+ * SAME `{missedNote}` — the catch-up annotation (host-local HH:MM of the missed
+ * instant) for a `catch-up` fire, empty for an `on-time` run — so a replayed run
+ * is annotated identically whichever kind it is.
+ *
+ * The `{schedule}` text differs per kind ON PURPOSE. A prompt job keeps
+ * English-only {@link describeSchedule} (its announcement is read alongside the
+ * agent-facing prompt). A reminder uses the LOCALIZED
+ * {@link getReminderScheduleText} — the very same words its `/reminders` list row
+ * and card show, because describing one reminder two different ways is a defect.
+ */
+function buildFireAnnouncement(job, fireContext) {
+    const missedNote = getMissedNote(fireContext);
+    if ((0, deliveryKind_1.checkIsReminderSchedule)(job)) {
+        return (0, i18n_1.t)('reminders.fired', {
+            text: job.prompt,
+            schedule: (0, reminderScheduleText_1.getReminderScheduleText)(job.spec),
+            missedNote,
+        });
+    }
+    return (0, i18n_1.t)('schedule.fired', {
+        name: job.name,
+        schedule: (0, recurrence_1.describeSchedule)(job.spec),
+        prompt: job.prompt,
+        missedNote,
+    });
+}
+/** @description The catch-up note of a fire, empty for an on-time run. */
+function getMissedNote(fireContext) {
+    return fireContext.kind === 'catch-up' && fireContext.missedAtMs !== undefined
+        ? (0, i18n_1.t)('schedule.missedNote', { time: (0, localClock_1.formatLocalClock)(fireContext.missedAtMs) })
+        : '';
+}
+/** @description The topic alert of a check's first failure: what failed, how, and the output tail. */
+function buildCheckFailedAnnouncement(job, fireContext, failure, output) {
+    return (0, i18n_1.t)('schedule.checkFailed', {
+        name: job.name,
+        schedule: (0, recurrence_1.describeSchedule)(job.spec),
+        missedNote: getMissedNote(fireContext),
+        failure,
+        command: (0, checkRun_1.getCheckAlertCommand)(job.checkCommand ?? ''),
+        output: (0, checkRun_1.getOutputTail)(output.trim(), checkRun_1.checkAlertOutputMaxChars) || '—',
+    });
+}
+/**
+ * @description Steps 1–2: post the announcement and pin it. A pin failure only
+ * logs — the announcement is already visible.
+ */
+async function announceAndPin(deps, job, text) {
+    const messageId = await deps.announce(job.threadKey, text);
+    if (messageId === null)
+        return;
+    try {
+        await deps.pin(job.threadKey, messageId, job.isPinSilent === true);
+    }
+    catch (error) {
+        console.warn(`[scheduler] pin announcement for job ${job.id} failed:`, error instanceof Error ? error.message : error);
+    }
+}
+/**
+ * @description Steps 3–4: post `prompt` (already carrying its marker) into the
+ * thread's session through {@link postToSession} and map its outcome onto the
+ * engine's delivery outcome.
+ */
+async function deliverToAgent(deps, job, prompt, options = {}) {
+    // 3–4. ensure a session, let a busy one finish its turn, forward the prefixed prompt
+    const posted = await (0, postToSession_1.postToSession)(deps, job.threadKey, prompt, job.lastAdapterName, options);
+    if (posted.ok) {
+        // A run held during a usage-limit wait reaches the agent once the wait ends —
+        // with its resume, the operator's next message, or the next session (R23).
+        if (posted.isHeld)
+            console.log(`[scheduler] job ${job.id}: held until the usage-limit wait ends`);
+        return { status: 'delivered' };
+    }
+    // Unbound → distinct error the engine records; S8 pauses the job on it.
+    // no-adapter → the topic never picked an agent; start-failed → a start
+    // that threw; a failed forward keeps its own message.
+    switch (posted.reason) {
+        case 'unbound':
+            return { status: 'failed', error: exports.unboundDeliveryError };
+        case 'no-adapter':
+            return { status: 'failed', error: 'no agent selected for this topic' };
+        case 'start-failed':
+            return { status: 'failed', error: 'failed to start agent session' };
+        case 'forward-failed':
+            return { status: 'failed', error: posted.error };
+    }
+}
+/**
+ * @description The check flow: run the command, then stay quiet, post the
+ * "passes again" line, or raise the alert and wake the agent. The failing flag is
+ * stored BEFORE the agent is woken, so a restart mid-delivery cannot raise the
+ * same alert twice.
+ */
+async function deliverCheck(deps, job, fireContext) {
+    const timeoutSec = job.checkTimeoutSec ?? checkRun_1.defaultCheckTimeoutSec;
+    const command = job.checkCommand ?? '';
+    const result = await deps.runCheck(job.threadKey, command, timeoutSec * 1000);
+    if (!result)
+        return { status: 'failed', error: exports.unboundDeliveryError };
+    const decision = (0, checkRun_1.getCheckAlertDecision)({
+        isPassing: (0, checkRun_1.checkIsCheckPassing)(result),
+        wasFailing: job.isCheckFailing === true,
+    });
+    if (decision === 'quiet')
+        return { status: 'delivered' };
+    if (decision === 'recovered') {
+        await deps.setCheckFailing(job.id, false);
+        await deps.announce(job.threadKey, (0, i18n_1.t)('schedule.checkRecovered', { name: job.name }));
+        return { status: 'delivered' };
+    }
+    await deps.setCheckFailing(job.id, true);
+    const failure = (0, checkRun_1.describeCheckFailure)(result, timeoutSec);
+    await announceAndPin(deps, job, buildCheckFailedAnnouncement(job, fireContext, failure, result.output));
+    return deliverToAgent(deps, job, (0, checkRun_1.buildCheckFailurePrompt)({ name: job.name, command, failure, output: result.output, prompt: job.prompt }));
+}
+/**
+ * @description Build the engine's `deliver(job, fireContext)` callback bound to
+ * the injected deps. See the module header for the locked flow.
+ */
+function createScheduleDelivery(deps) {
+    return async (job, fireContext) => {
+        if ((0, deliveryKind_1.checkIsCheckSchedule)(job))
+            return deliverCheck(deps, job, fireContext);
+        // Read before the paced announce and pin, which can take a while under load:
+        // a run held over a usage-limit wait says when it was due (R27).
+        const dueAtMs = fireContext.kind === 'catch-up' && fireContext.missedAtMs !== undefined ? fireContext.missedAtMs : deps.now();
+        // 1–2. announce and pin
+        await announceAndPin(deps, job, buildFireAnnouncement(job, fireContext));
+        // A reminder is done here: announced and pinned, with no agent involved at
+        // all. Returning before `ensureSession` is also what lets it fire in an
+        // unbound topic and in General — there is no session to fail to ensure.
+        if ((0, deliveryKind_1.checkIsReminderSchedule)(job))
+            return { status: 'delivered' };
+        // 3–4. wake the agent with the prompt. A run held over a usage-limit wait
+        // reaches the agent later: it says when it was due (R27).
+        return deliverToAgent(deps, job, prependScheduledRunMarker(job.name, job.prompt), {
+            heldText: prependScheduledRunMarker(job.name, job.prompt, { dueAtMs }),
+        });
+    };
+}
+//# sourceMappingURL=delivery.js.map

package/dist/scheduler/delivery.js.map

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

package/dist/scheduler/deliveryKind.d.ts

@@ -0,0 +1,29 @@
+import type { ScheduleRecord } from './types';
+/**
+ * @description Pure decisions that depend on a schedule's {@link
+ * ScheduleRecord.deliveryKind}: the discriminator predicate itself, and the ONE
+ * policy that has to read it outside the fire path — which of a thread's jobs an
+ * unbound-topic pause applies to.
+ *
+ * The pause filter lives here rather than in `bot.ts` because `bot.ts` cannot be
+ * imported by a test (its module-scope `parseEnv()` exits the process), and this
+ * rule is the load-bearing half of the reminder feature: a reminder needs neither
+ * a bound folder nor an agent, so pausing it when the topic leaves its folder
+ * would silently stop the one job kind that could still have run.
+ */
+/**
+ * @description Whether a record is a bot-local reminder (post + pin, no agent).
+ * Takes only the field it reads so a caller can ask about a partial record.
+ */
+export declare function checkIsReminderSchedule(record: Pick<ScheduleRecord, 'deliveryKind'>): boolean;
+/** @description Whether a record is a watchdog check (the bot runs its command; a failure wakes the agent). */
+export declare function checkIsCheckSchedule(record: Pick<ScheduleRecord, 'deliveryKind'>): boolean;
+/**
+ * @description The jobs an UNBOUND topic must pause: the agent-prompt jobs and the
+ * checks (a check runs in the bound folder and wakes the agent), reminders left
+ * out so they stay armed. The caller must therefore count what this
+ * returns rather than the thread's whole list — a thread holding only reminders
+ * yields an empty array, i.e. nothing paused and no notice to post.
+ */
+export declare function getUnboundPausableSchedules(records: readonly ScheduleRecord[]): ScheduleRecord[];
+//# sourceMappingURL=deliveryKind.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"deliveryKind.d.ts","sourceRoot":"","sources":["../../src/scheduler/deliveryKind.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C;;;;;;;;;;;GAWG;AAEH;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,IAAI,CAAC,cAAc,EAAE,cAAc,CAAC,GAAG,OAAO,CAE7F;AAED,+GAA+G;AAC/G,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,IAAI,CAAC,cAAc,EAAE,cAAc,CAAC,GAAG,OAAO,CAE1F;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,SAAS,cAAc,EAAE,GACjC,cAAc,EAAE,CAElB"}

package/dist/scheduler/deliveryKind.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkIsReminderSchedule = checkIsReminderSchedule;
+exports.checkIsCheckSchedule = checkIsCheckSchedule;
+exports.getUnboundPausableSchedules = getUnboundPausableSchedules;
+/**
+ * @description Pure decisions that depend on a schedule's {@link
+ * ScheduleRecord.deliveryKind}: the discriminator predicate itself, and the ONE
+ * policy that has to read it outside the fire path — which of a thread's jobs an
+ * unbound-topic pause applies to.
+ *
+ * The pause filter lives here rather than in `bot.ts` because `bot.ts` cannot be
+ * imported by a test (its module-scope `parseEnv()` exits the process), and this
+ * rule is the load-bearing half of the reminder feature: a reminder needs neither
+ * a bound folder nor an agent, so pausing it when the topic leaves its folder
+ * would silently stop the one job kind that could still have run.
+ */
+/**
+ * @description Whether a record is a bot-local reminder (post + pin, no agent).
+ * Takes only the field it reads so a caller can ask about a partial record.
+ */
+function checkIsReminderSchedule(record) {
+    return record.deliveryKind === 'reminder';
+}
+/** @description Whether a record is a watchdog check (the bot runs its command; a failure wakes the agent). */
+function checkIsCheckSchedule(record) {
+    return record.deliveryKind === 'check';
+}
+/**
+ * @description The jobs an UNBOUND topic must pause: the agent-prompt jobs and the
+ * checks (a check runs in the bound folder and wakes the agent), reminders left
+ * out so they stay armed. The caller must therefore count what this
+ * returns rather than the thread's whole list — a thread holding only reminders
+ * yields an empty array, i.e. nothing paused and no notice to post.
+ */
+function getUnboundPausableSchedules(records) {
+    return records.filter((record) => !checkIsReminderSchedule(record));
+}
+//# sourceMappingURL=deliveryKind.js.map

package/dist/scheduler/deliveryKind.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deliveryKind.js","sourceRoot":"","sources":["../../src/scheduler/deliveryKind.ts"],"names":[],"mappings":";;AAmBA,0DAEC;AAGD,oDAEC;AASD,kEAIC;AArCD;;;;;;;;;;;GAWG;AAEH;;;GAGG;AACH,SAAgB,uBAAuB,CAAC,MAA4C;IAClF,OAAO,MAAM,CAAC,YAAY,KAAK,UAAU,CAAC;AAC5C,CAAC;AAED,+GAA+G;AAC/G,SAAgB,oBAAoB,CAAC,MAA4C;IAC/E,OAAO,MAAM,CAAC,YAAY,KAAK,OAAO,CAAC;AACzC,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,2BAA2B,CACzC,OAAkC;IAElC,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,uBAAuB,CAAC,MAAM,CAAC,CAAC,CAAC;AACtE,CAAC"}

package/dist/scheduler/directoryThreads.d.ts

@@ -0,0 +1,19 @@
+import type { BindingData } from '../state';
+import { type SessionKey } from '../sessionKey';
+/**
+ * @description Invert a directory (an OpenCode instance's absolute working
+ * folder) to the serialized thread keys bound to it. The scheduler MCP server's
+ * `dir:<directory>` scope (S5) needs this to resolve which threads a directory
+ * token may touch; `bot.ts` has the forward `binding → workDir` mapping
+ * (`resolveBoundWorkDir`) but no inverse, so this is the single place that walks
+ * every binding and matches its RESOLVED workDir against `directory`.
+ *
+ * Why resolved workDir and not the raw `subdir`: the OpenCode injection (S6)
+ * scopes the token to the canonical agent workdir. Comparing against the raw
+ * relative `subdir`, or an unresolved `WORK_ROOT`, would miss symlinked roots.
+ */
+export declare function getThreadKeysForDirectory(bindings: Array<{
+    key: SessionKey;
+    data: BindingData;
+}>, workRoot: string, directory: string): string[];
+//# sourceMappingURL=directoryThreads.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"directoryThreads.d.ts","sourceRoot":"","sources":["../../src/scheduler/directoryThreads.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,EAAe,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAE7D;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,KAAK,CAAC;IAAE,GAAG,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,WAAW,CAAA;CAAE,CAAC,EACvD,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,MAAM,EAAE,CASV"}

package/dist/scheduler/directoryThreads.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getThreadKeysForDirectory = getThreadKeysForDirectory;
+const validation_1 = require("../validation");
+const sessionKey_1 = require("../sessionKey");
+/**
+ * @description Invert a directory (an OpenCode instance's absolute working
+ * folder) to the serialized thread keys bound to it. The scheduler MCP server's
+ * `dir:<directory>` scope (S5) needs this to resolve which threads a directory
+ * token may touch; `bot.ts` has the forward `binding → workDir` mapping
+ * (`resolveBoundWorkDir`) but no inverse, so this is the single place that walks
+ * every binding and matches its RESOLVED workDir against `directory`.
+ *
+ * Why resolved workDir and not the raw `subdir`: the OpenCode injection (S6)
+ * scopes the token to the canonical agent workdir. Comparing against the raw
+ * relative `subdir`, or an unresolved `WORK_ROOT`, would miss symlinked roots.
+ */
+function getThreadKeysForDirectory(bindings, workRoot, directory) {
+    const matches = [];
+    for (const { key, data } of bindings) {
+        const decision = (0, validation_1.resolveBoundWorkDir)(workRoot, data);
+        if (decision.kind === 'proceed' && decision.workDir === directory) {
+            matches.push((0, sessionKey_1.keyToString)(key));
+        }
+    }
+    return matches;
+}
+//# sourceMappingURL=directoryThreads.js.map

package/dist/scheduler/directoryThreads.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"directoryThreads.js","sourceRoot":"","sources":["../../src/scheduler/directoryThreads.ts"],"names":[],"mappings":";;AAgBA,8DAaC;AA7BD,8CAAoD;AAEpD,8CAA6D;AAE7D;;;;;;;;;;;GAWG;AACH,SAAgB,yBAAyB,CACvC,QAAuD,EACvD,QAAgB,EAChB,SAAiB;IAEjB,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,QAAQ,EAAE,CAAC;QACrC,MAAM,QAAQ,GAAG,IAAA,gCAAmB,EAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QACrD,IAAI,QAAQ,CAAC,IAAI,KAAK,SAAS,IAAI,QAAQ,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YAClE,OAAO,CAAC,IAAI,CAAC,IAAA,wBAAW,EAAC,GAAG,CAAC,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/scheduler/engine.d.ts

@@ -0,0 +1,77 @@
+import type { StateStore } from '../state';
+import type { RunLedger } from './runLedger';
+import type { DeliveryOutcome, FireContext, ScheduleRecord } from './types';
+/**
+ * @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.
+ */
+export declare const maxTimeoutMs = 2147483647;
+/**
+ * @name SchedulerEngineDeps
+ * @description Everything the engine needs from the outside world. `store` and
+ * `ledger` are the persistence seams; `deliver` is the actual fire action
+ * (announce + pin + forward, implemented in S4); `now` is the injectable clock;
+ * `setTimeoutFn`/`clearTimeoutFn` let tests drive a fake timer queue.
+ */
+export interface SchedulerEngineDeps {
+    store: Pick<StateStore, 'getSchedules' | 'upsertSchedule' | 'removeSchedule' | 'flush'>;
+    ledger: Pick<RunLedger, 'append'>;
+    /** Fire the job: announce, pin, deliver to the agent. Resolves with the outcome. */
+    deliver: (job: ScheduleRecord, fireContext: FireContext) => Promise<DeliveryOutcome>;
+    /** Current epoch ms. Injected so tests run on a fake clock. */
+    now: () => number;
+    setTimeoutFn?: (callback: () => void, delayMs: number) => NodeJS.Timeout;
+    clearTimeoutFn?: (handle: NodeJS.Timeout) => void;
+}
+/**
+ * @name SchedulerEngine
+ * @description Public engine surface. `armJob`/`disarmJob` manage a single
+ * job's timer; `rearmAll` is the boot step (walks the store, fires catch-ups,
+ * arms the rest); `shutdown` clears every timer.
+ */
+export interface SchedulerEngine {
+    /** Arm (or re-arm) a single job's timer to its `nextRunAt`. */
+    armJob(record: ScheduleRecord): void;
+    /** Cancel a job's timer if one is armed. Idempotent. */
+    disarmJob(jobId: string): void;
+    /** Boot replay: arm every persisted job, firing one catch-up per missed run. */
+    rearmAll(): Promise<void>;
+    /**
+     * Resolve once every fire chain currently in flight (delivery + bookkeeping +
+     * flush + ledger end record) has settled. A timer-driven fire is dispatched
+     * fire-and-forget, so this is the seam a caller (or a test) uses to await it.
+     */
+    whenIdle(): Promise<void>;
+    /** Clear every armed timer (process shutdown). */
+    shutdown(): void;
+}
+export declare function createSchedulerEngine(deps: SchedulerEngineDeps): SchedulerEngine;
+//# sourceMappingURL=engine.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/scheduler/engine.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,YAAY,aAAgB,CAAC;AAK1C;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE,cAAc,GAAG,gBAAgB,GAAG,gBAAgB,GAAG,OAAO,CAAC,CAAC;IACxF,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAClC,oFAAoF;IACpF,OAAO,EAAE,CAAC,GAAG,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;IACrF,+DAA+D;IAC/D,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC,OAAO,CAAC;IACzE,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,KAAK,IAAI,CAAC;CACnD;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,MAAM,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IACrC,wDAAwD;IACxD,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,gFAAgF;IAChF,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,kDAAkD;IAClD,QAAQ,IAAI,IAAI,CAAC;CAClB;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,mBAAmB,GAAG,eAAe,CAuThF"}