@songsid/agend 2.1.12 → 2.2.0-alpha.1

package/dist/needs-you-live.js

@@ -0,0 +1,228 @@
+export const DEBOUNCE_MS = 3_000;
+export const EDIT_MIN_MS = 10_000;
+export const POST_MIN_MS = 60_000;
+export const RENEW_MS = 10 * 60_000;
+/** A failed post backs off from POST_MIN_MS, doubling, up to this (#1398 review: never a tight retry loop). */
+export const POST_BACKOFF_MAX_MS = 15 * 60_000;
+/** Telegram General is topic "1" on input and no thread on the wire: both are the same place. */
+export function canonicalTarget(target) {
+    const thread = target.threadId === undefined || target.threadId === "" || target.threadId === "1" ? undefined : String(target.threadId);
+    return thread === undefined ? { chatId: String(target.chatId) } : { chatId: String(target.chatId), threadId: thread };
+}
+export function samePlace(a, b) {
+    const x = canonicalTarget(a), y = canonicalTarget(b);
+    return x.chatId === y.chatId && x.threadId === y.threadId;
+}
+export class NeedsYouLiveMessage {
+    deps;
+    generation = 0;
+    pointer;
+    inFlight = false;
+    rerun = false;
+    timer = null;
+    dueAt = Infinity;
+    lastEditAt = -Infinity;
+    /** No post (of any kind: first, moved, new item, edit fallback) before this monotonic time. */
+    nextPostAt = -Infinity;
+    postFailures = 0;
+    postWanted = false;
+    retired = false;
+    constructor(deps) {
+        this.deps = deps;
+        this.pointer = deps.loadPointer();
+        // A restart has no capabilities: render at once so the message gets fresh ones (pre-restart buttons are stale).
+        this.requestAt(deps.now());
+    }
+    /** The list changed. `newIds`: an item appeared that this world has not shown before (→ a new post, rate-limited). */
+    changed(newIds) {
+        if (this.retired)
+            return;
+        if (newIds)
+            this.postWanted = true;
+        const now = this.deps.now();
+        let at = now + DEBOUNCE_MS;
+        if (this.postWanted)
+            at = Math.max(at, Math.min(this.nextPostAt, this.lastEditAt + EDIT_MIN_MS));
+        else
+            at = Math.max(at, this.lastEditAt + EDIT_MIN_MS);
+        this.requestAt(at);
+    }
+    /** Current generation (tests and the ack handler's generation check). */
+    get currentGeneration() { return this.generation; }
+    get currentPointer() { return this.pointer; }
+    requestAt(at) {
+        if (this.retired || at >= this.dueAt)
+            return;
+        if (this.timer !== null)
+            this.deps.clearTimer(this.timer);
+        this.dueAt = at;
+        this.timer = this.deps.setTimer(() => { this.timer = null; this.dueAt = Infinity; void this.render(); }, Math.max(0, at - this.deps.now()));
+    }
+    scheduleRenewal() {
+        this.requestAt(this.deps.now() + RENEW_MS);
+    }
+    /** One render. Public for tests; normal use goes through changed(). */
+    async render() {
+        if (this.retired)
+            return;
+        if (this.inFlight) {
+            this.rerun = true;
+            return;
+        }
+        this.inFlight = true;
+        try {
+            await this.renderOnce();
+        }
+        finally {
+            this.inFlight = false;
+            if (this.rerun && !this.retired) {
+                this.rerun = false;
+                this.requestAt(this.deps.now());
+            }
+            else if (!this.retired) {
+                // A new item shown by an edit inside the post window is posted when the window opens.
+                if (this.postWanted)
+                    this.requestAt(Math.max(this.deps.now(), this.nextPostAt));
+                if (this.timer === null)
+                    this.scheduleRenewal();
+            }
+        }
+    }
+    fenced(generation, target) {
+        const now = this.deps.target();
+        return generation === this.generation && !this.retired && this.deps.enabled() && !this.deps.stopping()
+            && this.deps.worldExists() && now !== null && samePlace(now, target);
+    }
+    async renderOnce() {
+        const target = this.deps.target();
+        if (!this.deps.enabled() || this.deps.stopping() || !this.deps.worldExists() || target === null)
+            return;
+        const generation = ++this.generation;
+        // Revoke before await: every earlier generation's buttons are stale from here on, whatever happens below.
+        this.deps.revokeAcks();
+        const content = this.deps.content();
+        const now = this.deps.now();
+        // Nothing to say and nothing said yet: a fleet that never needed anyone posts nothing.
+        if (this.pointer === null && content.empty) {
+            this.postWanted = false;
+            return;
+        }
+        const moved = this.pointer !== null && !samePlace(this.pointer, target);
+        const mayPost = now >= this.nextPostAt;
+        if (this.pointer === null || moved) {
+            // Only a post will do. Not yet allowed (a failed one is backing off): try again when it is.
+            if (!mayPost) {
+                this.postWanted = true;
+                return;
+            }
+            await this.postNew(generation, target, content, moved);
+            return;
+        }
+        if (this.postWanted && mayPost) {
+            await this.postNew(generation, target, content, false);
+            return;
+        }
+        const pointer = this.pointer;
+        const acks = this.deps.mintAcks(generation, pointer, content.ackable);
+        try {
+            await this.deps.edit(pointer, content.text, acks.choices);
+        }
+        catch (err) {
+            if (!this.fenced(generation, target)) {
+                this.deps.revokeAcks();
+                return;
+            }
+            this.deps.revokeAcks();
+            if (this.deps.now() < this.nextPostAt) {
+                // The fallback post is rate-limited like any other: try again when it may.
+                this.deps.log("live message edit failed; will post when allowed", { world: this.deps.world, err: String(err?.message ?? err) });
+                this.postWanted = true;
+                return;
+            }
+            this.deps.log("live message edit failed; posting a new one", { world: this.deps.world, err: String(err?.message ?? err) });
+            const next = ++this.generation;
+            await this.postNew(next, target, this.deps.content(), false);
+            return;
+        }
+        if (!this.fenced(generation, target)) {
+            this.deps.revokeAcks();
+            return;
+        }
+        this.lastEditAt = this.deps.now();
+    }
+    async postNew(generation, target, content, moved) {
+        const old = this.pointer;
+        const acks = this.deps.mintAcks(generation, canonicalTarget(target), content.ackable);
+        let sent;
+        try {
+            sent = await this.deps.post(target, content.text, acks.choices);
+        }
+        catch (err) {
+            this.deps.revokeAcks();
+            this.postFailures++;
+            const backoff = Math.min(POST_MIN_MS * 2 ** (this.postFailures - 1), POST_BACKOFF_MAX_MS);
+            this.nextPostAt = this.deps.now() + backoff;
+            this.postWanted = true; // retried — no sooner than nextPostAt
+            this.deps.log("live message post failed", { world: this.deps.world, err: String(err?.message ?? err), retryInMs: backoff });
+            return;
+        }
+        if (!this.fenced(generation, target)) {
+            // A late ACK: disabled, rebound, superseded or stopping meanwhile. Publish nothing current.
+            this.deps.revokeAcks();
+            void this.deps.remove(sent).catch(() => { });
+            return;
+        }
+        acks.bind(sent);
+        this.pointer = sent;
+        this.deps.savePointer(sent);
+        const at = this.deps.now();
+        this.nextPostAt = at + POST_MIN_MS;
+        this.postFailures = 0;
+        this.lastEditAt = at;
+        this.postWanted = false;
+        // The previous message goes — without new content, so a moved target's former destination never gets this list.
+        if (old !== null && !(old.messageId === sent.messageId && samePlace(old, sent))) {
+            void this.deps.remove(old).catch(err => this.deps.log(moved ? "could not remove the live message at its former target" : "could not remove the previous live message", { world: this.deps.world, err: String(err?.message ?? err) }));
+        }
+    }
+    /** Shutdown: revoke first, then say so on the message, without buttons. No further renders. */
+    async retire() {
+        if (this.retired)
+            return;
+        this.retired = true;
+        if (this.timer !== null) {
+            this.deps.clearTimer(this.timer);
+            this.timer = null;
+        }
+        this.deps.revokeAcks();
+        this.generation++;
+        if (this.pointer)
+            await this.deps.edit(this.pointer, this.deps.text.stopped, []).catch(() => { });
+    }
+    /** Replaced by another renderer (a new adapter under this world's id): stop and revoke, touching nothing remote. */
+    abandon() {
+        if (this.timer !== null) {
+            this.deps.clearTimer(this.timer);
+            this.timer = null;
+        }
+        this.retired = true;
+        this.deps.revokeAcks();
+        this.generation++;
+    }
+    /** live_message turned off (or the world removed): revoke, mark the message, forget it. */
+    async disable() {
+        if (this.timer !== null) {
+            this.deps.clearTimer(this.timer);
+            this.timer = null;
+        }
+        this.retired = true;
+        this.deps.revokeAcks();
+        this.generation++;
+        const pointer = this.pointer;
+        this.pointer = null;
+        this.deps.savePointer(null);
+        if (pointer)
+            await this.deps.edit(pointer, this.deps.text.off, []).catch(() => { });
+    }
+}
+//# sourceMappingURL=needs-you-live.js.map

package/dist/needs-you-live.js.map

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

package/dist/needs-you.d.ts

@@ -0,0 +1,132 @@
+/**
+ * #1386 "Needs you": one list of everything currently waiting on the person, derived — on demand, never stored —
+ * from state the fleet already holds. Design: docs/design/1386-needs-you-inbox.md (§3 sources, §4 derivation).
+ *
+ * This module is pure: the fleet collects the inputs, this decides the items, which world owns each, what the
+ * rendered list is (its signature), and the live chat message's text and links. Nothing here touches a socket,
+ * a file or a clock of its own.
+ */
+export type NeedsYouType = "prompt" | "awaiting_input" | "instance" | "delivery";
+export interface NeedsYouItem {
+    /** Stable per occurrence: a new episode, crash or delivery is a new id (§3). */
+    id: string;
+    type: NeedsYouType;
+    /** The instance to open; a delivery's is its target. */
+    instance: string;
+    /** The world (adapter id) that owns the instance, or undefined: listed only in /ui (§5.0). */
+    owner?: string;
+    /** Which kind of wait, for the title (localized by the renderer, not here). */
+    reason: NeedsYouReason;
+    /** One line, may be "": a prompt's text, an interaction summary, "source → target · kind". */
+    detail: string;
+    /** Epoch ms when it started waiting. */
+    since: number;
+    /** prompt: the nonce the web answers through POST /ui/prompt, its buttons, and where the buttons are. */
+    nonce?: string;
+    actions?: Array<{
+        id: string;
+        label: string;
+    }>;
+    promptAt?: {
+        adapterId: string;
+        chatId: string;
+        threadId?: string;
+        messageId?: string;
+    };
+    /** delivery: the outbox row; Acknowledge offered. */
+    deliveryId?: string;
+}
+export type NeedsYouReason = "hang" | "exited" | "assist" | "permission" | "dangerous_command" | "login" | "dialog" | "terminal_input" | "auth_paused" | "crashed" | "delivery_uncertain" | "delivery_failed";
+/** A fleet prompt offered on the dashboard (hang / exit-restart / interactive-assist), as the fleet holds it. */
+export interface PromptInput {
+    nonce: string;
+    prefix: string;
+    instance: string;
+    text: string;
+    actions: Array<{
+        id: string;
+        label: string;
+    }>;
+    createdAt: number;
+    adapterId: string;
+    chatId: string;
+    threadId?: string;
+    messageId?: string;
+    /** interactive-assist only: the interaction wait it was raised for (§3.2). */
+    assistFor?: {
+        owner: string | null;
+        episode: number | null;
+    };
+}
+export interface InstanceInput {
+    name: string;
+    /** presentation state: "awaiting_input" when the CLI waits at its terminal and that is not stale/suspected. */
+    state?: string;
+    interaction?: {
+        kind?: string | null;
+        owner?: string | null;
+        episode?: number | null;
+        since?: number | null;
+    } | null;
+    interactionSummary?: string | null;
+    /** The pause marker's reason, for a paused instance; and when it was paused. */
+    pauseReason?: string | null;
+    pausedAt?: number | null;
+    /** "crashed" with the time the fleet first saw it so (§3.3). */
+    crashedAt?: number | null;
+}
+export interface DeliveryInput {
+    deliveryId: string;
+    state: "uncertain" | "failed";
+    source: string;
+    target: string;
+    kind: string;
+    finishedAt: number;
+}
+export interface NeedsYouInputs {
+    prompts: PromptInput[];
+    instances: InstanceInput[];
+    deliveries: DeliveryInput[];
+    /** The live world that owns an instance, or undefined (no channel, or its world is gone). */
+    ownerOf: (instance: string) => string | undefined;
+}
+/** §3: every item, from the inputs only. Ordered by instance (the one with the oldest item first), then oldest first. */
+export declare function deriveNeedsYou(inputs: NeedsYouInputs): NeedsYouItem[];
+/** §5.0: the items a world's chat surfaces show — only those whose instance it owns. */
+export declare function itemsForWorld(items: readonly NeedsYouItem[], world: string): NeedsYouItem[];
+/** The age bucket shown next to an item: changes of it re-render, nothing finer does. */
+export declare function ageLabel(sinceMs: number, nowMs: number): string;
+/**
+ * §4.2: what a surface shows, as a string — ids in order, each item's displayed text and age bucket, and its action
+ * coordinates (the prompt message it links to, its owning world). Two lists with the same signature render the same.
+ * New-item notification is keyed on ids, separately; a re-render never notifies.
+ */
+export declare function renderSignature(items: readonly NeedsYouItem[], nowMs: number): string;
+export interface WorldPlace {
+    type: "discord" | "telegram" | string;
+    /** Discord: the guild id. Telegram: the supergroup id (-100…). */
+    groupId?: string;
+}
+/** A link to a message (a prompt's own buttons), or undefined when none can be built for this platform/place. */
+export declare function messageLink(place: WorldPlace, at: {
+    chatId: string;
+    threadId?: string;
+    messageId?: string;
+}): string | undefined;
+/** A way to the instance's own thread: Discord's channel mention (clickable in place), Telegram's topic link. */
+export declare function instanceLink(place: WorldPlace, topicId: string | undefined): string | undefined;
+export interface LiveLine {
+    item: NeedsYouItem;
+    title: string;
+    link?: string;
+}
+export declare const LIVE_MAX_LINES = 10;
+export declare const LIVE_MAX_ACKS = 5;
+/**
+ * The live message for one world: header, at most LIVE_MAX_LINES lines (then "… and N more"), and which delivery
+ * items get an Acknowledge button (the newest LIVE_MAX_ACKS of those shown). `t` localizes.
+ */
+export declare function renderLiveMessage(lines: readonly LiveLine[], nowMs: number, t: (key: string, ...args: Array<string | number>) => string): {
+    text: string;
+    ackable: NeedsYouItem[];
+};

package/dist/needs-you.js

@@ -0,0 +1,164 @@
+/**
+ * #1386 "Needs you": one list of everything currently waiting on the person, derived — on demand, never stored —
+ * from state the fleet already holds. Design: docs/design/1386-needs-you-inbox.md (§3 sources, §4 derivation).
+ *
+ * This module is pure: the fleet collects the inputs, this decides the items, which world owns each, what the
+ * rendered list is (its signature), and the live chat message's text and links. Nothing here touches a socket,
+ * a file or a clock of its own.
+ */
+const PROMPT_REASON = {
+    "hang:": "hang",
+    "exit-restart:": "exited",
+    "interactive-assist:": "assist",
+};
+const INTERACTION_REASON = {
+    permission: "permission",
+    dangerous_command: "dangerous_command",
+    login: "login",
+    dialog: "dialog",
+    suspected_terminal_input: "terminal_input",
+};
+const oneLine = (text, max = 160) => {
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+};
+/** §3: every item, from the inputs only. Ordered by instance (the one with the oldest item first), then oldest first. */
+export function deriveNeedsYou(inputs) {
+    const items = [];
+    // §3.1 prompts.
+    for (const p of inputs.prompts) {
+        const reason = PROMPT_REASON[p.prefix];
+        if (!reason)
+            continue;
+        items.push({
+            id: `prompt:${p.nonce}`, type: "prompt", instance: p.instance, reason,
+            detail: oneLine(p.text), since: p.createdAt, nonce: p.nonce, actions: p.actions,
+            promptAt: { adapterId: p.adapterId, chatId: p.chatId, ...(p.threadId !== undefined ? { threadId: p.threadId } : {}), ...(p.messageId ? { messageId: p.messageId } : {}) },
+        });
+    }
+    for (const inst of inputs.instances) {
+        // §3.2 awaiting_input — folded into an interactive-assist prompt only when it was raised for this same wait.
+        if (inst.state === "awaiting_input" && inst.interaction) {
+            const episode = inst.interaction.episode ?? null;
+            const owner = inst.interaction.owner ?? null;
+            const folded = inputs.prompts.some(p => p.prefix === "interactive-assist:" && p.instance === inst.name
+                && p.assistFor !== undefined && p.assistFor.episode === episode && p.assistFor.owner === owner);
+            if (!folded) {
+                items.push({
+                    id: `awaiting:${inst.name}:${owner ?? "-"}:${episode ?? "-"}`, type: "awaiting_input", instance: inst.name,
+                    reason: INTERACTION_REASON[inst.interaction.kind ?? ""] ?? "dialog",
+                    detail: oneLine(inst.interactionSummary ?? ""), since: inst.interaction.since ?? 0,
+                });
+            }
+        }
+        // §3.3 instance: paused for sign-in, or crashed.
+        if (inst.pauseReason === "auth") {
+            items.push({ id: `auth:${inst.name}:${inst.pausedAt ?? 0}`, type: "instance", instance: inst.name, reason: "auth_paused", detail: "", since: inst.pausedAt ?? 0 });
+        }
+        if (inst.crashedAt != null) {
+            items.push({ id: `crashed:${inst.name}:${inst.crashedAt}`, type: "instance", instance: inst.name, reason: "crashed", detail: "", since: inst.crashedAt });
+        }
+    }
+    // §3.4 deliveries (already filtered by the outbox: unacknowledged, last 24 h, newest 50).
+    for (const d of inputs.deliveries) {
+        items.push({
+            id: `delivery:${d.deliveryId}`, type: "delivery", instance: d.target,
+            reason: d.state === "uncertain" ? "delivery_uncertain" : "delivery_failed",
+            detail: oneLine(`${d.source} → ${d.target} · ${d.kind}`), since: d.finishedAt, deliveryId: d.deliveryId,
+        });
+    }
+    for (const item of items) {
+        const owner = inputs.ownerOf(item.instance);
+        if (owner !== undefined)
+            item.owner = owner;
+    }
+    // Group by instance; instances ordered by their oldest item, items oldest first.
+    const oldest = new Map();
+    for (const item of items)
+        oldest.set(item.instance, Math.min(oldest.get(item.instance) ?? Infinity, item.since));
+    return items.sort((a, b) => (oldest.get(a.instance) - oldest.get(b.instance)) || a.instance.localeCompare(b.instance) || (a.since - b.since) || a.id.localeCompare(b.id));
+}
+/** §5.0: the items a world's chat surfaces show — only those whose instance it owns. */
+export function itemsForWorld(items, world) {
+    return items.filter(item => item.owner === world);
+}
+/** The age bucket shown next to an item: changes of it re-render, nothing finer does. */
+export function ageLabel(sinceMs, nowMs) {
+    const minutes = Math.max(0, Math.floor((nowMs - sinceMs) / 60_000));
+    if (minutes < 1)
+        return "<1m";
+    if (minutes < 60)
+        return `${minutes}m`;
+    const hours = Math.floor(minutes / 60);
+    return hours < 24 ? `${hours}h` : `${Math.floor(hours / 24)}d`;
+}
+/**
+ * §4.2: what a surface shows, as a string — ids in order, each item's displayed text and age bucket, and its action
+ * coordinates (the prompt message it links to, its owning world). Two lists with the same signature render the same.
+ * New-item notification is keyed on ids, separately; a re-render never notifies.
+ */
+export function renderSignature(items, nowMs) {
+    return JSON.stringify(items.map(i => [
+        i.id, i.reason, i.detail, ageLabel(i.since, nowMs), i.owner ?? null,
+        i.promptAt ? [i.promptAt.adapterId, i.promptAt.chatId, i.promptAt.threadId ?? null, i.promptAt.messageId ?? null] : null,
+    ]));
+}
+const SNOWFLAKE = /^\d{5,25}$/;
+/** A link to a message (a prompt's own buttons), or undefined when none can be built for this platform/place. */
+export function messageLink(place, at) {
+    if (!at.messageId)
+        return undefined;
+    if (place.type === "discord") {
+        const channel = at.threadId ?? at.chatId;
+        if (!place.groupId || !SNOWFLAKE.test(place.groupId) || !SNOWFLAKE.test(channel) || !SNOWFLAKE.test(at.messageId))
+            return undefined;
+        return `https://discord.com/channels/${place.groupId}/${channel}/${at.messageId}`;
+    }
+    if (place.type === "telegram") {
+        const internal = telegramInternalId(at.chatId);
+        if (!internal || !/^\d+$/.test(at.messageId))
+            return undefined;
+        const topic = at.threadId && at.threadId !== "1" && /^\d+$/.test(at.threadId) ? `${at.threadId}/` : "";
+        return `https://t.me/c/${internal}/${topic}${at.messageId}`;
+    }
+    return undefined;
+}
+/** A way to the instance's own thread: Discord's channel mention (clickable in place), Telegram's topic link. */
+export function instanceLink(place, topicId) {
+    if (!topicId)
+        return undefined;
+    if (place.type === "discord")
+        return SNOWFLAKE.test(topicId) ? `<#${topicId}>` : undefined;
+    if (place.type === "telegram") {
+        const internal = telegramInternalId(place.groupId ?? "");
+        return internal && /^\d+$/.test(topicId) && topicId !== "1" ? `https://t.me/c/${internal}/${topicId}` : undefined;
+    }
+    return undefined;
+}
+/** t.me/c/ links take a supergroup's id without its -100 prefix; anything else has no such link. */
+function telegramInternalId(chatId) {
+    const m = /^-100(\d+)$/.exec(chatId);
+    return m ? m[1] : undefined;
+}
+export const LIVE_MAX_LINES = 10;
+export const LIVE_MAX_ACKS = 5;
+/**
+ * The live message for one world: header, at most LIVE_MAX_LINES lines (then "… and N more"), and which delivery
+ * items get an Acknowledge button (the newest LIVE_MAX_ACKS of those shown). `t` localizes.
+ */
+export function renderLiveMessage(lines, nowMs, t) {
+    if (lines.length === 0)
+        return { text: t("needs.live_empty"), ackable: [] };
+    const shown = lines.slice(0, LIVE_MAX_LINES);
+    const body = shown.map(l => {
+        const age = ageLabel(l.item.since, nowMs);
+        const head = `• ${l.item.instance} — ${l.title} (${age})`;
+        return l.link ? `${head} · ${l.link}` : head;
+    });
+    if (lines.length > shown.length)
+        body.push(t("needs.live_more", lines.length - shown.length));
+    const ackable = shown.filter(l => l.item.type === "delivery").map(l => l.item)
+        .sort((a, b) => b.since - a.since).slice(0, LIVE_MAX_ACKS);
+    return { text: [t("needs.live_header", lines.length), ...body].join("\n"), ackable };
+}
+//# sourceMappingURL=needs-you.js.map

package/dist/needs-you.js.map

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

package/dist/node-version-guard.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Runtime version guard: better-sqlite3 v13 requires Node-API 10.
+ *
+ * Node-API 10 is available from:
+ *   Node 22.14.0 (LTS) — released 2025-02-06
+ *   Node 23.6.0         — released 2025-01-13
+ *   Node 24+            — all releases
+ *
+ * This function is exported so tests can verify the exact boundary without
+ * duplicating the logic. The CLI bootstrap calls checkNodeVersion() at the
+ * very top so that even the OLD updater's `agend --version` verification
+ * will fail on an incompatible runtime, aborting the install.
+ *
+ * References:
+ *   https://github.com/WiseLibs/better-sqlite3/blob/v13.0.3/binding.gyp
+ *   https://nodejs.org/api/n-api.html#node-api-version-matrix
+ */
+/** Returns true when the running Node supports N-API 10. */
+export declare function isNodeCompatible(nodeVersion?: string): boolean;
+/**
+ * Call at binary bootstrap. Prints a clear error and calls process.exit(1)
+ * when the running Node cannot load better-sqlite3's N-API 10 prebuilt.
+ *
+ * Placing this guard at bootstrap means:
+ * - `agend --version` exits 1 on incompatible Node
+ * - The OLD updater's verification step (`agend --version` → failUpdate on
+ *   non-zero) aborts the install rather than letting a restart crash the fleet
+ * - Any DB command (`schedule list`, daemon start, …) is also blocked
+ */
+export declare function checkNodeVersion(): void;

package/dist/node-version-guard.js

@@ -0,0 +1,50 @@
+/**
+ * Runtime version guard: better-sqlite3 v13 requires Node-API 10.
+ *
+ * Node-API 10 is available from:
+ *   Node 22.14.0 (LTS) — released 2025-02-06
+ *   Node 23.6.0         — released 2025-01-13
+ *   Node 24+            — all releases
+ *
+ * This function is exported so tests can verify the exact boundary without
+ * duplicating the logic. The CLI bootstrap calls checkNodeVersion() at the
+ * very top so that even the OLD updater's `agend --version` verification
+ * will fail on an incompatible runtime, aborting the install.
+ *
+ * References:
+ *   https://github.com/WiseLibs/better-sqlite3/blob/v13.0.3/binding.gyp
+ *   https://nodejs.org/api/n-api.html#node-api-version-matrix
+ */
+/** Returns true when the running Node supports N-API 10. */
+export function isNodeCompatible(nodeVersion = process.versions.node) {
+    const [majStr, minStr] = nodeVersion.split(".");
+    const maj = parseInt(majStr, 10);
+    const min = parseInt(minStr, 10);
+    if (maj >= 24)
+        return true;
+    if (maj === 23 && min >= 6)
+        return true;
+    if (maj === 22 && min >= 14)
+        return true;
+    return false;
+}
+/**
+ * Call at binary bootstrap. Prints a clear error and calls process.exit(1)
+ * when the running Node cannot load better-sqlite3's N-API 10 prebuilt.
+ *
+ * Placing this guard at bootstrap means:
+ * - `agend --version` exits 1 on incompatible Node
+ * - The OLD updater's verification step (`agend --version` → failUpdate on
+ *   non-zero) aborts the install rather than letting a restart crash the fleet
+ * - Any DB command (`schedule list`, daemon start, …) is also blocked
+ */
+export function checkNodeVersion() {
+    if (!isNodeCompatible()) {
+        process.stderr.write(`agend requires Node.js ^22.14.0 || ^23.6.0 || >=24.\n` +
+            `better-sqlite3 v13 uses Node-API 10, available from Node 22.14.0 / 23.6.0 / 24+.\n` +
+            `Running: Node ${process.version}.\n` +
+            `Upgrade Node first (e.g. nvm install 22), then restart.\n`);
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=node-version-guard.js.map

package/dist/node-version-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-version-guard.js","sourceRoot":"","sources":["../src/node-version-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,4DAA4D;AAC5D,MAAM,UAAU,gBAAgB,CAAC,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,IAAI;IAClE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAChD,MAAM,GAAG,GAAG,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACjC,MAAM,GAAG,GAAG,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACjC,IAAI,GAAG,IAAI,EAAE;QAAE,OAAO,IAAI,CAAC;IAC3B,IAAI,GAAG,KAAK,EAAE,IAAI,GAAG,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACxC,IAAI,GAAG,KAAK,EAAE,IAAI,GAAG,IAAI,EAAE;QAAE,OAAO,IAAI,CAAC;IACzC,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB;IAC9B,IAAI,CAAC,gBAAgB,EAAE,EAAE,CAAC;QACxB,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,uDAAuD;YACvD,oFAAoF;YACpF,iBAAiB,OAAO,CAAC,OAAO,KAAK;YACrC,2DAA2D,CAC5D,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC"}

package/dist/operator-control-paths.d.ts

@@ -0,0 +1,4 @@
+/** Shared filesystem boundary for independent, same-user operator sockets. */
+export declare function operatorUid(label: string): number;
+export declare function assertOperatorRoot(dataDir: string, label: string): Promise<void>;
+export declare function assertOperatorClientPath(dataDir: string, socketPath: string, label: string): Promise<void>;