sensorium-mcp 3.1.2 → 3.1.3-board.10

package/dist/services/board/board-signals.js

@@ -0,0 +1,170 @@
+/**
+ * Board awareness signals — exactly four kinds, one line each, no description
+ * (invariant #4). STARTED / DONE / BLOCKED / DECISION_NEEDED reach the board bot
+ * or the configured operator main thread.
+ *
+ * Delivery mode is deliberately isolated in this one function while decision
+ * #2 is with the operator (thread 1327, 2026-08-01):
+ *   - "passive" (default, orchestrator's lean): rides the passive-notice
+ *     channel — seen on the main thread's next delivered turn, never acted on.
+ *   - "mailbox": appended to the main thread's pending-task mailbox
+ *     — wakes it with an FYI-framed line.
+ * Flip via BOARD_SIGNAL_DELIVERY=mailbox; no other code changes.
+ */
+import { appendFileSync } from "node:fs";
+import { join } from "node:path";
+import { config } from "../../config/index.js";
+import { log } from "../../lib/logger.js";
+import { errorMessage } from "../../lib/utils.js";
+import { ensureDirs, PENDING_TASKS_DIR } from "../process.service.js";
+import { pushPassiveNotice } from "../passive-notice.service.js";
+import { TelegramClient } from "../telegram.js";
+import { Optional } from "../../data/optional.js";
+const CARD_TITLE_EXCERPT_MAX_LENGTH = 80;
+const DECISION_QUESTION_EXCERPT_MAX_LENGTH = 300;
+const ESCALATION_UPDATE_EXCERPT_MAX_LENGTH = 300;
+/** Production delivery: the configured board bot, else the main thread from the environment. */
+export const DEFAULT_BOARD_SIGNAL_DELIVERY = {
+    boardBot: Optional.empty(),
+    boardBotToken: Optional.empty(),
+    boardChatId: Optional.empty(),
+    warningSink: Optional.empty(),
+    mainThreadId: Optional.empty(),
+};
+function boardBotFor(token, delivery) {
+    if (delivery.boardBot.has())
+        return delivery.boardBot.get();
+    return new TelegramClient(token);
+}
+function boardBotToken(delivery) {
+    return delivery.boardBotToken.orElse(config.BOARD_BOT_TOKEN);
+}
+function boardChatId(delivery) {
+    return delivery.boardChatId.orElse(config.BOARD_CHAT_ID);
+}
+function usesBoardBot(delivery) {
+    return boardBotToken(delivery) !== "" && boardChatId(delivery) !== "";
+}
+function sendToBoardBot(line, delivery, failure) {
+    const warn = delivery.warningSink.orElse(log.warn.bind(log));
+    try {
+        void boardBotFor(boardBotToken(delivery), delivery)
+            .sendMessage(boardChatId(delivery), line)
+            .catch((err) => warn(`${failure}: ${errorMessage(err)}`));
+    }
+    catch (err) {
+        warn(`${failure}: ${errorMessage(err)}`);
+    }
+}
+/** Worker-authored text entering another thread's context block is an
+ *  instruction-injection surface: strip control chars (no fake newline-framed
+ *  "directives"), drop backticks, and cap length so the excerpt reads as an
+ *  inert quoted fragment, never as markup or a fresh instruction line. */
+function sanitizeExcerpt(text, maxLen) {
+    return (text
+        // eslint-disable-next-line no-control-regex -- stripping control chars is the point
+        .replace(/[\x00-\x1f\x7f\u0085\u2028\u2029]+/g, " ")
+        .replace(/`/g, "'")
+        .replace(/\s+/g, " ")
+        .trim()
+        .slice(0, maxLen));
+}
+function deliveryMode() {
+    return process.env.BOARD_SIGNAL_DELIVERY === "mailbox" ? "mailbox" : "passive";
+}
+/** One-line, FYI-framed state transition. `detail` is used for BLOCKED and
+ *  DECISION_NEEDED, where it makes the ping actionable for the operator. */
+export function sendBoardSignal(db, card, kind, detail, delivery = DEFAULT_BOARD_SIGNAL_DELIVERY) {
+    const suffix = kind === "STARTED" && card.workerThreadId != null
+        ? ` (worker ${card.workerThreadId})`
+        : (kind === "BLOCKED" || kind === "DECISION_NEEDED") && detail
+            ? ` — "${sanitizeExcerpt(detail.split("\n")[0], 160)}"`
+            : "";
+    const line = `[Board FYI — no action needed] Card #${card.cardId} "${sanitizeExcerpt(card.title, CARD_TITLE_EXCERPT_MAX_LENGTH)}" ${kind}${suffix}`;
+    try {
+        if (usesBoardBot(delivery)) {
+            sendToBoardBot(line, delivery, `[board] signal delivery failed for card ${card.cardId}`);
+        }
+        else {
+            const mainThreadId = mainThreadFor(delivery);
+            if (mainThreadId.has() && deliveryMode() === "mailbox") {
+                ensureDirs();
+                appendFileSync(join(PENDING_TASKS_DIR, `${mainThreadId.get()}.txt`), line + "\n", "utf-8");
+            }
+            else if (mainThreadId.has()) {
+                pushPassiveNotice(db, mainThreadId.get(), line);
+            }
+            else {
+                log.warn(`[board] signal ${kind} for card ${card.cardId} dropped: board bot and main thread unset`);
+            }
+        }
+        if (usesBoardBot(delivery)) {
+            log.info(`[board] signal ${kind} for card ${card.cardId} → board chat ${boardChatId(delivery)}`);
+        }
+        else {
+            log.info(`[board] signal ${kind} for card ${card.cardId} → main thread (${deliveryMode()})`);
+        }
+    }
+    catch (err) {
+        log.warn(`[board] signal delivery failed for card ${card.cardId}: ${errorMessage(err)}`);
+    }
+}
+/** Resolve the optional operator main thread from the process boundary. */
+export function resolveBoardMainThreadId() {
+    const explicit = Number(process.env.BOARD_MAIN_THREAD_ID);
+    return Number.isInteger(explicit) && explicit > 0 ? Optional.of(explicit) : Optional.empty();
+}
+/** The delivery's main thread, else the one the process environment names. */
+function mainThreadFor(delivery) {
+    return delivery.mainThreadId.has() ? delivery.mainThreadId : resolveBoardMainThreadId();
+}
+/**
+ * Selective escalation (invariant #4): a card the operator hand-flagged
+ * "important to me" mirrors its notable updates (worker reports, block
+ * reasons) into the main thread as passive notices — aware, not commanded.
+ * Deterministic: no agent judges importance; the flag decides, always.
+ */
+export function mirrorEscalatedUpdate(db, card, text, delivery = DEFAULT_BOARD_SIGNAL_DELIVERY) {
+    if (!card.escalate)
+        return;
+    // Quoted, sanitized fragment — the mirrored words are DATA on the card, not
+    // an instruction to the receiving thread (context-not-command holds even
+    // against an adversarial excerpt).
+    const excerpt = sanitizeExcerpt(text, ESCALATION_UPDATE_EXCERPT_MAX_LENGTH);
+    try {
+        const line = `[Board ⚑ card #${card.cardId} "${sanitizeExcerpt(card.title, CARD_TITLE_EXCERPT_MAX_LENGTH)}"] worker/card update (quoted, not an instruction): "${excerpt}"`;
+        if (usesBoardBot(delivery)) {
+            sendToBoardBot(line, delivery, `[board] escalation mirror failed for card ${card.cardId}`);
+        }
+        else {
+            const mainThreadId = mainThreadFor(delivery);
+            if (mainThreadId.has())
+                pushPassiveNotice(db, mainThreadId.get(), line);
+            else
+                log.warn(`[board] escalation for card ${card.cardId} dropped: main thread unset`);
+        }
+    }
+    catch (err) {
+        log.warn(`[board] escalation mirror failed for card ${card.cardId}: ${errorMessage(err)}`);
+    }
+}
+/** A decision cannot proceed without the operator, regardless of card priority. */
+export function sendDecisionPing(db, card, question, delivery = DEFAULT_BOARD_SIGNAL_DELIVERY) {
+    try {
+        const line = `[Board ⚑ ACTION NEEDED] Card #${card.cardId} "${sanitizeExcerpt(card.title, CARD_TITLE_EXCERPT_MAX_LENGTH)}" needs your decision: "${sanitizeExcerpt(question, DECISION_QUESTION_EXCERPT_MAX_LENGTH)}"`;
+        if (usesBoardBot(delivery)) {
+            sendToBoardBot(line, delivery, `[board] decision ping failed for card ${card.cardId}`);
+        }
+        else {
+            const mainThreadId = mainThreadFor(delivery);
+            if (mainThreadId.has())
+                pushPassiveNotice(db, mainThreadId.get(), line);
+            else
+                log.warn(`[board] decision ping for card ${card.cardId} dropped: main thread unset`);
+        }
+    }
+    catch (err) {
+        log.warn(`[board] decision ping failed for card ${card.cardId}: ${errorMessage(err)}`);
+    }
+}
+//# sourceMappingURL=board-signals.js.map

package/dist/services/board/board-signals.js.map

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

package/dist/services/board/card-briefing.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Card-worker briefing renderer (design §3.2).
+ *
+ * The rendered payload is pre-queued into the worker's pending-task mailbox
+ * before spawn, ON TOP of the root-thread briefing the worker already
+ * inherits via memorySourceThreadId. Card + comments carry the task's whole
+ * world; the profile is rendered as imperative standing orders; the report
+ * contract makes the worker's exit path unambiguous (STATUS: DONE / BLOCKED / DECISION,
+ * then exit — never wait, never loop on a blocker).
+ */
+import type { BoardCard, BoardComment, ExecutionProfile } from "../../data/board/board-types.js";
+/**
+ * The words every report-capture reply that means "exit now" carries, and no
+ * other reply does. The brief tells a worker to exit only on these, so a
+ * progress reply must never mention exiting.
+ */
+export declare const REPORT_EXIT_SIGNAL = "Now EXIT";
+export declare function renderProfileDirectives(profile: ExecutionProfile, cardId: number): string[];
+/**
+ * Render the complete task payload for a fresh card-worker.
+ * `workerThreadId` is known before spawn (the dispatch mints it first).
+ */
+export declare function renderCardBriefing(card: BoardCard, comments: BoardComment[], workerThreadId: number): string;
+//# sourceMappingURL=card-briefing.d.ts.map

package/dist/services/board/card-briefing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"card-briefing.d.ts","sourceRoot":"","sources":["../../../src/services/board/card-briefing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAEjG;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,aAAa,CAAC;AAW7C,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAkE3F;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,YAAY,EAAE,EACxB,cAAc,EAAE,MAAM,GACrB,MAAM,CA+DR"}

package/dist/services/board/card-briefing.js

@@ -0,0 +1,132 @@
+/**
+ * Card-worker briefing renderer (design §3.2).
+ *
+ * The rendered payload is pre-queued into the worker's pending-task mailbox
+ * before spawn, ON TOP of the root-thread briefing the worker already
+ * inherits via memorySourceThreadId. Card + comments carry the task's whole
+ * world; the profile is rendered as imperative standing orders; the report
+ * contract makes the worker's exit path unambiguous (STATUS: DONE / BLOCKED / DECISION,
+ * then exit — never wait, never loop on a blocker).
+ */
+/**
+ * The words every report-capture reply that means "exit now" carries, and no
+ * other reply does. The brief tells a worker to exit only on these, so a
+ * progress reply must never mention exiting.
+ */
+export const REPORT_EXIT_SIGNAL = "Now EXIT";
+/** Oldest-first truncation cap for the comment history (design §3.2). */
+const MAX_COMMENT_CHARS = 24_000;
+const AUTONOMY_DIRECTIVES = {
+    Autonomous: "Work autonomously to completion; only surface blockers or the final result.",
+    Checkpoints: "Pause at meaningful checkpoints for operator confirmation before continuing.",
+    Collaborative: "Work closely with the operator, confirming each significant step.",
+};
+export function renderProfileDirectives(profile, cardId) {
+    const d = [];
+    if (profile.repository)
+        d.push(`Work in repository: ${profile.repository}.`);
+    d.push(profile.createBranch
+        ? `Create a work branch (suggested: card-${cardId}) before changing anything.`
+        : "Do NOT create a new branch unless the current branch is unusable.");
+    if (profile.skills?.length)
+        d.push(`Load these skills via get_skill first: ${profile.skills.join(", ")}.`);
+    if (profile.autonomy)
+        d.push(AUTONOMY_DIRECTIVES[profile.autonomy]);
+    if (profile.phases?.length) {
+        d.push("Execute this task in the following ordered phases:");
+        for (const [index, phase] of profile.phases.entries()) {
+            const overrides = [];
+            if (phase.provider !== "Inherit" && phase.provider.toLowerCase() !== profile.agentType)
+                overrides.push(`provider: ${phase.provider}`);
+            if (phase.model && phase.model !== profile.model)
+                overrides.push(`model: ${phase.model}`);
+            d.push(`${index + 1}. ${phase.name}.${overrides.length ? ` Overrides: ${overrides.join(", ")}.` : ""}`);
+            if (phase.review)
+                d.push(`after the ${phase.name} phase, delegate an expert code review to a SEPARATE worker via the Handoff skill (do not review your own work)`);
+        }
+    }
+    d.push(profile.runTests
+        ? "Run the relevant tests and make them pass."
+        : "Do not run test suites unless a change demands it.");
+    if (profile.build)
+        d.push("Run the build and make it pass.");
+    if (profile.verifyDone)
+        d.push("Before reporting STATUS: DONE, spawn a fresh, SEPARATE verification worker via start_thread and the Handoff skill to independently check the acceptance criteria; do NOT verify your own work, use the SAME provider and model as yourself, and report DONE only after it confirms the criteria are met.");
+    d.push(profile.push ? "Push your commits." : "Do NOT push.");
+    if (profile.openPr) {
+        d.push("Open a pull request with the changes.");
+        d.push(profile.prDraft !== false
+            ? "Open it as a draft pull request; mark it ready only after review."
+            : "Open it as a ready (non-draft) pull request.");
+        d.push(profile.prProvider === "GitHub"
+            ? "Target the pull request at GitHub."
+            : profile.prProvider === "Azure DevOps"
+                ? "Target the pull request at Azure DevOps."
+                : "Detect the PR target from the repo remote.");
+    }
+    else {
+        d.push("Do NOT open a pull request.");
+    }
+    if (profile.expertReview)
+        d.push(`Before finishing, delegate an expert code review of your diff to a ${profile.reviewAgentType ?? "claude"} worker and address its findings.`);
+    if (profile.ciCheck && profile.ciCheck !== "none")
+        d.push(`After pushing, verify CI is green on ${profile.ciCheck === "github" ? "GitHub" : "Azure DevOps"} before reporting DONE.`);
+    if (profile.operatorReview)
+        d.push("The operator wants to review the result — say so explicitly in your final report.");
+    return d;
+}
+/**
+ * Render the complete task payload for a fresh card-worker.
+ * `workerThreadId` is known before spawn (the dispatch mints it first).
+ */
+export function renderCardBriefing(card, comments, workerThreadId) {
+    const lines = [];
+    lines.push(`# Task Board card #${card.cardId}: ${card.title}`);
+    lines.push(`Correlation ID: ${card.correlationId} (include this in worker log and report lines).`);
+    lines.push(`You are a STATELESS card-worker (thread ${workerThreadId}) executing this card. ` +
+        `This card plus the history below is the task's complete context on top of your inherited thread briefing.`);
+    lines.push("");
+    lines.push(`Execution profile: ${card.profileId} | Priority: ${card.priority}`);
+    lines.push("");
+    lines.push("## Description");
+    lines.push(card.description || "(none — the title is the task)");
+    if (/implementation_plans[\\/][\w.-]+\.md/.test(card.description)) {
+        lines.push("");
+        lines.push("The description references an implementation_plans/ file — READ THAT FILE FIRST and in full; it is the task's spec.");
+    }
+    if (card.acceptance) {
+        lines.push("");
+        lines.push("## Acceptance criteria");
+        lines.push(card.acceptance);
+    }
+    lines.push("");
+    lines.push("## Standing orders (execution profile — do not ask, these ARE the answers)");
+    for (const directive of renderProfileDirectives(card.profile, card.cardId))
+        lines.push(`- ${directive}`);
+    if (comments.length > 0) {
+        let history = comments
+            .map((c) => `[${c.createdAt}] ${c.author.toUpperCase()}:\n${c.content}`)
+            .join("\n---\n");
+        if (history.length > MAX_COMMENT_CHARS) {
+            history = "[…older history truncated…]\n" + history.slice(history.length - MAX_COMMENT_CHARS);
+        }
+        lines.push("");
+        lines.push("## Card history (oldest first — prior workers' reports and operator guidance)");
+        lines.push(history);
+    }
+    lines.push("");
+    lines.push("## Report contract (MANDATORY)");
+    lines.push(`When finished, call send_message_to_thread with mode:"reply", targetThreadId:${workerThreadId}, ` +
+        `senderThreadId:${workerThreadId}, senderName:"card-${card.cardId}". The message MUST start with its first line being exactly ` +
+        `"STATUS: DONE", "STATUS: BLOCKED: <one-line reason>", or "STATUS: DECISION: <question>". For a decision with choices, put an optional next line "OPTIONS: option A | option B | option C". Follow with your real report (what you did, ` +
+        `commits/PR links, review results, anything the next worker or the operator needs).`);
+    lines.push("Then EXIT: do not call wait_for_instructions again, do not wait for replies, do not loop on a blocker — " +
+        "if you need an OPERATOR DECISION to proceed, report STATUS: DECISION: <question> and exit. Reserve " +
+        "STATUS: BLOCKED for genuine blockers or errors. A fresh worker will be re-briefed from the card when " +
+        "the operator responds.");
+    lines.push("Optional progress updates: the same call with a first line that is NOT a STATUS line is kept as a comment " +
+        `on the card while it is still yours, and you keep working; exit only if the reply says "${REPORT_EXIT_SIGNAL}". ` +
+        "The final report still needs the STATUS first line, then EXIT.");
+    return lines.join("\n");
+}
+//# sourceMappingURL=card-briefing.js.map

package/dist/services/board/card-briefing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"card-briefing.js","sourceRoot":"","sources":["../../../src/services/board/card-briefing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,UAAU,CAAC;AAE7C,yEAAyE;AACzE,MAAM,iBAAiB,GAAG,MAAM,CAAC;AAEjC,MAAM,mBAAmB,GAAwE;IAC/F,UAAU,EAAE,6EAA6E;IACzF,WAAW,EAAE,8EAA8E;IAC3F,aAAa,EAAE,mEAAmE;CACnF,CAAC;AAEF,MAAM,UAAU,uBAAuB,CAAC,OAAyB,EAAE,MAAc;IAC/E,MAAM,CAAC,GAAa,EAAE,CAAC;IACvB,IAAI,OAAO,CAAC,UAAU;QAAE,CAAC,CAAC,IAAI,CAAC,uBAAuB,OAAO,CAAC,UAAU,GAAG,CAAC,CAAC;IAC7E,CAAC,CAAC,IAAI,CACJ,OAAO,CAAC,YAAY;QAClB,CAAC,CAAC,yCAAyC,MAAM,6BAA6B;QAC9E,CAAC,CAAC,mEAAmE,CACxE,CAAC;IACF,IAAI,OAAO,CAAC,MAAM,EAAE,MAAM;QACxB,CAAC,CAAC,IAAI,CAAC,0CAA0C,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACjF,IAAI,OAAO,CAAC,QAAQ;QAAE,CAAC,CAAC,IAAI,CAAC,mBAAmB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IACpE,IAAI,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;QAC3B,CAAC,CAAC,IAAI,CAAC,oDAAoD,CAAC,CAAC;QAC7D,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,CAAC;YACtD,MAAM,SAAS,GAAa,EAAE,CAAC;YAC/B,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS,IAAI,KAAK,CAAC,QAAQ,CAAC,WAAW,EAAE,KAAK,OAAO,CAAC,SAAS;gBACpF,SAAS,CAAC,IAAI,CAAC,aAAa,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;YAChD,IAAI,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,KAAK,KAAK,OAAO,CAAC,KAAK;gBAAE,SAAS,CAAC,IAAI,CAAC,UAAU,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;YAC1F,CAAC,CAAC,IAAI,CACJ,GAAG,KAAK,GAAG,CAAC,KAAK,KAAK,CAAC,IAAI,IAAI,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,eAAe,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAChG,CAAC;YACF,IAAI,KAAK,CAAC,MAAM;gBACd,CAAC,CAAC,IAAI,CACJ,aAAa,KAAK,CAAC,IAAI,iHAAiH,CACzI,CAAC;QACN,CAAC;IACH,CAAC;IACD,CAAC,CAAC,IAAI,CACJ,OAAO,CAAC,QAAQ;QACd,CAAC,CAAC,4CAA4C;QAC9C,CAAC,CAAC,oDAAoD,CACzD,CAAC;IACF,IAAI,OAAO,CAAC,KAAK;QAAE,CAAC,CAAC,IAAI,CAAC,iCAAiC,CAAC,CAAC;IAC7D,IAAI,OAAO,CAAC,UAAU;QACpB,CAAC,CAAC,IAAI,CACJ,0SAA0S,CAC3S,CAAC;IACJ,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC;IAC7D,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,CAAC,CAAC,IAAI,CAAC,uCAAuC,CAAC,CAAC;QAChD,CAAC,CAAC,IAAI,CACJ,OAAO,CAAC,OAAO,KAAK,KAAK;YACvB,CAAC,CAAC,mEAAmE;YACrE,CAAC,CAAC,8CAA8C,CACnD,CAAC;QACF,CAAC,CAAC,IAAI,CACJ,OAAO,CAAC,UAAU,KAAK,QAAQ;YAC7B,CAAC,CAAC,oCAAoC;YACtC,CAAC,CAAC,OAAO,CAAC,UAAU,KAAK,cAAc;gBACrC,CAAC,CAAC,0CAA0C;gBAC5C,CAAC,CAAC,4CAA4C,CACnD,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,CAAC,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAC;IACxC,CAAC;IACD,IAAI,OAAO,CAAC,YAAY;QACtB,CAAC,CAAC,IAAI,CACJ,sEAAsE,OAAO,CAAC,eAAe,IAAI,QAAQ,mCAAmC,CAC7I,CAAC;IACJ,IAAI,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,OAAO,KAAK,MAAM;QAC/C,CAAC,CAAC,IAAI,CACJ,wCAAwC,OAAO,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,cAAc,yBAAyB,CAC1H,CAAC;IACJ,IAAI,OAAO,CAAC,cAAc;QACxB,CAAC,CAAC,IAAI,CAAC,mFAAmF,CAAC,CAAC;IAC9F,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAAe,EACf,QAAwB,EACxB,cAAsB;IAEtB,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,sBAAsB,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;IAC/D,KAAK,CAAC,IAAI,CACR,mBAAmB,IAAI,CAAC,aAAa,iDAAiD,CACvF,CAAC;IACF,KAAK,CAAC,IAAI,CACR,2CAA2C,cAAc,yBAAyB;QAChF,2GAA2G,CAC9G,CAAC;IACF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,sBAAsB,IAAI,CAAC,SAAS,gBAAgB,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;IAChF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;IAC7B,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,IAAI,gCAAgC,CAAC,CAAC;IACjE,IAAI,sCAAsC,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;QAClE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CACR,qHAAqH,CACtH,CAAC;IACJ,CAAC;IACD,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QACpB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC;QACrC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC9B,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,4EAA4E,CAAC,CAAC;IACzF,KAAK,MAAM,SAAS,IAAI,uBAAuB,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC;QACxE,KAAK,CAAC,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC,CAAC;IAE/B,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,IAAI,OAAO,GAAG,QAAQ;aACnB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,SAAS,KAAK,CAAC,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,OAAO,EAAE,CAAC;aACvE,IAAI,CAAC,SAAS,CAAC,CAAC;QACnB,IAAI,OAAO,CAAC,MAAM,GAAG,iBAAiB,EAAE,CAAC;YACvC,OAAO,GAAG,+BAA+B,GAAG,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,GAAG,iBAAiB,CAAC,CAAC;QAChG,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,+EAA+E,CAAC,CAAC;QAC5F,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACtB,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,gCAAgC,CAAC,CAAC;IAC7C,KAAK,CAAC,IAAI,CACR,gFAAgF,cAAc,IAAI;QAChG,kBAAkB,cAAc,sBAAsB,IAAI,CAAC,MAAM,8DAA8D;QAC/H,yOAAyO;QACzO,oFAAoF,CACvF,CAAC;IACF,KAAK,CAAC,IAAI,CACR,0GAA0G;QACxG,qGAAqG;QACrG,uGAAuG;QACvG,wBAAwB,CAC3B,CAAC;IACF,KAAK,CAAC,IAAI,CACR,4GAA4G;QAC1G,2FAA2F,kBAAkB,KAAK;QAClH,gEAAgE,CACnE,CAAC;IACF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/services/board/card-diagnostics.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Per-card observability read model. It intentionally derives dispatch history
+ * from the card's append-only board comments: dispatch has no separate table.
+ */
+import type { BoardCard, BoardComment } from "../../data/board/board-types.js";
+import type { Database } from "../../data/memory/db-types.js";
+export interface CardDiagnostics {
+    card: BoardCard;
+    dispatch: {
+        correlationId: string;
+        workerThreadId: number | null;
+        log: BoardComment[];
+    };
+    workerLog: {
+        threadId: number | null;
+        tail: string;
+    };
+    lastError: BoardComment | null;
+}
+export interface CardDiagnosticsDeps {
+    readWorkerLogTail?: (threadId: number) => Promise<string>;
+}
+/** Return undefined for an unknown card; callers map that to their own error shape. */
+export declare function getCardDiagnostics(db: Database, cardId: number, deps?: CardDiagnosticsDeps): Promise<CardDiagnostics | undefined>;
+//# sourceMappingURL=card-diagnostics.d.ts.map

package/dist/services/board/card-diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"card-diagnostics.d.ts","sourceRoot":"","sources":["../../../src/services/board/card-diagnostics.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAC/E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAM9D,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,EAAE;QACR,aAAa,EAAE,MAAM,CAAC;QACtB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;QAC9B,GAAG,EAAE,YAAY,EAAE,CAAC;KACrB,CAAC;IACF,SAAS,EAAE;QAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACrD,SAAS,EAAE,YAAY,GAAG,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,mBAAmB;IAClC,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CAC3D;AAED,uFAAuF;AACvF,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,QAAQ,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,mBAAwB,GAC7B,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CA0BtC"}

package/dist/services/board/card-diagnostics.js

@@ -0,0 +1,50 @@
+/**
+ * Per-card observability read model. It intentionally derives dispatch history
+ * from the card's append-only board comments: dispatch has no separate table.
+ */
+import { readFile } from "node:fs/promises";
+import { getCard } from "../../data/board/card.repository.js";
+import { listComments } from "../../data/board/comment.repository.js";
+import { findLatestThreadLogFile } from "../thread-log-reader.js";
+const WORKER_LOG_TAIL_BYTES = 16_384;
+const ERROR_COMMENT_PATTERN = /(?:\berror\b|\bfailed\b|\bexception\b)/i;
+/** Return undefined for an unknown card; callers map that to their own error shape. */
+export async function getCardDiagnostics(db, cardId, deps = {}) {
+    const card = getCard(db, cardId);
+    if (!card.has())
+        return undefined;
+    const foundCard = card.get();
+    const comments = listComments(db, cardId);
+    const dispatchLog = comments.filter((comment) => comment.author === "board");
+    const lastError = [...comments]
+        .reverse()
+        .find((comment) => ERROR_COMMENT_PATTERN.test(comment.content));
+    const workerThreadId = foundCard.workerThreadId;
+    const readWorkerLogTail = deps.readWorkerLogTail ?? readLatestWorkerLogTail;
+    return {
+        card: foundCard,
+        dispatch: {
+            correlationId: foundCard.correlationId,
+            workerThreadId,
+            log: dispatchLog,
+        },
+        workerLog: {
+            threadId: workerThreadId,
+            tail: workerThreadId === null ? "" : await readWorkerLogTail(workerThreadId),
+        },
+        lastError: lastError ?? null,
+    };
+}
+async function readLatestWorkerLogTail(threadId) {
+    const logFile = await findLatestThreadLogFile(threadId);
+    if (!logFile)
+        return "";
+    try {
+        const contents = await readFile(logFile, "utf-8");
+        return contents.slice(-WORKER_LOG_TAIL_BYTES);
+    }
+    catch {
+        return "";
+    }
+}
+//# sourceMappingURL=card-diagnostics.js.map

package/dist/services/board/card-diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"card-diagnostics.js","sourceRoot":"","sources":["../../../src/services/board/card-diagnostics.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,qCAAqC,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,wCAAwC,CAAC;AAGtE,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAElE,MAAM,qBAAqB,GAAG,MAAM,CAAC;AACrC,MAAM,qBAAqB,GAAG,yCAAyC,CAAC;AAiBxE,uFAAuF;AACvF,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,EAAY,EACZ,MAAc,EACd,OAA4B,EAAE;IAE9B,MAAM,IAAI,GAAG,OAAO,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE;QAAE,OAAO,SAAS,CAAC;IAClC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAE7B,MAAM,QAAQ,GAAG,YAAY,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IAC1C,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,KAAK,OAAO,CAAC,CAAC;IAC7E,MAAM,SAAS,GAAG,CAAC,GAAG,QAAQ,CAAC;SAC5B,OAAO,EAAE;SACT,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,qBAAqB,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;IAClE,MAAM,cAAc,GAAG,SAAS,CAAC,cAAc,CAAC;IAChD,MAAM,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,IAAI,uBAAuB,CAAC;IAE5E,OAAO;QACL,IAAI,EAAE,SAAS;QACf,QAAQ,EAAE;YACR,aAAa,EAAE,SAAS,CAAC,aAAa;YACtC,cAAc;YACd,GAAG,EAAE,WAAW;SACjB;QACD,SAAS,EAAE;YACT,QAAQ,EAAE,cAAc;YACxB,IAAI,EAAE,cAAc,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,iBAAiB,CAAC,cAAc,CAAC;SAC7E;QACD,SAAS,EAAE,SAAS,IAAI,IAAI;KAC7B,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,uBAAuB,CAAC,QAAgB;IACrD,MAAM,OAAO,GAAG,MAAM,uBAAuB,CAAC,QAAQ,CAAC,CAAC;IACxD,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IACxB,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAClD,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,qBAAqB,CAAC,CAAC;IAChD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/services/board/live-root-thread.d.ts

@@ -0,0 +1,8 @@
+import type { AgentType } from "../../config/index.js";
+/** Parameters required to create a persistent root-agent thread. */
+export interface LiveRootThreadInput {
+    name: string;
+    agentType: AgentType;
+    workingDirectory: string;
+}
+//# sourceMappingURL=live-root-thread.d.ts.map

package/dist/services/board/live-root-thread.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-root-thread.d.ts","sourceRoot":"","sources":["../../../src/services/board/live-root-thread.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAEvD,oEAAoE;AACpE,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,SAAS,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;CAC1B"}

package/dist/services/board/live-root-thread.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=live-root-thread.js.map

package/dist/services/board/live-root-thread.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-root-thread.js","sourceRoot":"","sources":["../../../src/services/board/live-root-thread.ts"],"names":[],"mappings":""}

package/dist/services/board/orchestrator.service.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Board orchestrator — the server-side loop that drains the board (design §3).
+ *
+ * Tick (default 30 s): while the global cap (default 3) is not reached,
+ * dispatch top-priority Backlog cards: spawn stateless card-workers, move the
+ * cards to In Progress, and emit STARTED signals. Workers are independent
+ * processes; no source thread needs to be active for dispatch.
+ *
+ * Spawn failure is an immediate BLOCKED (reason on the card) — the operator
+ * hears about it once, on the card, per the fire-and-forget metric.
+ *
+ * Report capture / exit reconciliation / recurrence land in Phases 5 and 7.
+ */
+import type { initMemoryDb } from "../../data/memory/index.js";
+import type { ThreadLifecycleService } from "../thread-lifecycle.service.js";
+import { withProcessIdentity } from "../process.service.js";
+import { claimCardForDispatch } from "../../data/board/card.repository.js";
+import { spawnCardWorker } from "./worker-spawn.js";
+import { getUsageSnapshotProvider } from "../usage/usage-snapshot-provider.js";
+import { releaseWorkerForCard } from "./release-worker.js";
+export declare function boardTickMs(): number;
+export declare function boardGlobalMaxConcurrent(): number;
+/** Kill-switch: BOARD_ENABLED=false skips orchestrator start entirely (the
+ *  board stays a dormant UI/API). Default: enabled. */
+export declare function boardEnabled(): boolean;
+export interface BoardOrchestratorDeps {
+    getMemoryDb: () => ReturnType<typeof initMemoryDb>;
+    telegram: {
+        createForumTopic(chatId: string, name: string): Promise<{
+            message_thread_id: number;
+        }>;
+        sendMessage(chatId: string, text: string, parseMode?: string, threadId?: number): Promise<void>;
+        deleteForumTopic(chatId: string, threadId: number): Promise<void>;
+    };
+    chatId: string;
+    threadLifecycle: ThreadLifecycleService;
+    /** Test seam — defaults to the real card-worker spawn path. */
+    spawnFn?: typeof spawnCardWorker;
+    /** Test seam — defaults to the atomic database-backed dispatch claim. */
+    claimFn?: typeof claimCardForDispatch;
+    /** Test seam — defaults to the process-wide usage read model. */
+    usageProvider?: Pick<ReturnType<typeof getUsageSnapshotProvider>, "isProviderLimited">;
+    /** Test seam — defaults to the batched pid/startedAt lookup. */
+    lookupProcessIdentityFn?: typeof withProcessIdentity;
+    /** Test seam — defaults to broker-routed thread liveness. */
+    isThreadAliveFn?: (threadId: number, fallbackPid?: number, spawnedAtMs?: number) => Promise<boolean>;
+    /** Test seam — defaults to the ordinary operator-release teardown. */
+    releaseWorkerFn?: typeof releaseWorkerForCard;
+}
+export declare class BoardOrchestrator {
+    private readonly deps;
+    private timer;
+    private inFlightTick;
+    private stopped;
+    constructor(deps: BoardOrchestratorDeps);
+    /** Begin ticking. A no-op once stop() has run: stop is end-of-life, so a start
+     *  that arrives late (after a self-update handed the port over) cannot bring a
+     *  second dispatcher back onto the board. */
+    start(): void;
+    /** Stop scheduling ticks, for good — a later start() is ignored. Resolves once a
+     *  tick already in flight has settled, so a caller handing dispatch to another
+     *  process can wait out its spawn. */
+    stop(): Promise<void>;
+    tick(): Promise<void>;
+    private runTick;
+    /**
+     * Retire every reported worker whose reply window has closed. The deadline is
+     * durable, so this covers a restart inside the window as well as the ordinary
+     * case; teardown clears the deadline, so a retirement is executed once. One
+     * failure must not strand the rest, hence the per-worker catch.
+     */
+    private executeDueRetirements;
+    private releaseUnboundBoardWorkers;
+    private releaseWorker;
+    /**
+     * Board-owned recurrence (design §4): a Done recurring card whose delay has
+     * elapsed — and whose group has no live instance (enforced in SQL) — puts a
+     * fresh identical copy back into Backlog. The original's next_spawn_at is
+     * cleared so it never respawns twice; the copy carries the group id forward.
+     * schedule_wake_up is untouched — this is a different mechanism by design.
+     */
+    private respawnDueRecurrences;
+    /** Retry due rate-limited cards in place without freeing their global slot. */
+    private respawnDueRateLimited;
+    private dispatchDueCards;
+    /** Spawn a card already CAS-claimed as in_progress and resolved for dispatch.
+     *  The card takes the worker inside the spawn path (see bindWorker below), so
+     *  this returns with the binding already durable. */
+    private spawnClaimedCard;
+    /**
+     * A card must never get a second worker beside a live one (duplicate branch,
+     * PR and push). The candidate set is the card's own launch history in
+     * `worker_lifecycle` — durable, so unlike the process-local map it replaces it
+     * survives a restart, and it covers a shared-checkout card as well as one
+     * running in its own worktree, which a scan of worktree paths could not.
+     * Liveness is still the probe's verdict, never the stored phase: a worker can
+     * die without any actor recording it. A candidate proven dead has its card link
+     * dropped here, which is the only place a link is retired — that also collects
+     * the link of a dispatch whose agent never came up.
+     */
+    private hasLivePriorWorker;
+    /**
+     * A prior worker with a pending retirement already reported and is finished —
+     * it is lingering only so the capture reply can reach it. Retiring it now and
+     * then probing is what keeps a promptly answered DECISION from being blocked by
+     * its own worker; the window exists for the reply, not for the next dispatch.
+     * The probe still decides: a worker that survived its kill is genuinely live.
+     */
+    private isPriorWorkerStillLive;
+    /**
+     * Park a claimed card whose dispatch cannot continue. A dispatch that got as
+     * far as binding its worker unbinds through the same CAS a dead bound worker
+     * uses — which is also what keeps an operator release that started during the
+     * spawn from being overwritten (that CAS requires operator_releasing = 0).
+     * A dispatch that failed before the bind is still unbound.
+     */
+    private blockClaimedCard;
+}
+//# sourceMappingURL=orchestrator.service.d.ts.map

package/dist/services/board/orchestrator.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.service.d.ts","sourceRoot":"","sources":["../../../src/services/board/orchestrator.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAO7E,OAAO,EAAiB,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC3E,OAAO,EAKL,oBAAoB,EAUrB,MAAM,qCAAqC,CAAC;AAc7C,OAAO,EAA6C,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC/F,OAAO,EAAE,wBAAwB,EAAE,MAAM,qCAAqC,CAAC;AAC/E,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAqB3D,wBAAgB,WAAW,IAAI,MAAM,CAGpC;AAED,wBAAgB,wBAAwB,IAAI,MAAM,CAGjD;AAED;uDACuD;AACvD,wBAAgB,YAAY,IAAI,OAAO,CAEtC;AAED,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;IACnD,QAAQ,EAAE;QACR,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;YAAE,iBAAiB,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACvF,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAChG,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;KACnE,CAAC;IACF,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,sBAAsB,CAAC;IACxC,+DAA+D;IAC/D,OAAO,CAAC,EAAE,OAAO,eAAe,CAAC;IACjC,yEAAyE;IACzE,OAAO,CAAC,EAAE,OAAO,oBAAoB,CAAC;IACtC,iEAAiE;IACjE,aAAa,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,OAAO,wBAAwB,CAAC,EAAE,mBAAmB,CAAC,CAAC;IACvF,gEAAgE;IAChE,uBAAuB,CAAC,EAAE,OAAO,mBAAmB,CAAC;IACrD,6DAA6D;IAC7D,eAAe,CAAC,EAAE,CAChB,QAAQ,EAAE,MAAM,EAChB,WAAW,CAAC,EAAE,MAAM,EACpB,WAAW,CAAC,EAAE,MAAM,KACjB,OAAO,CAAC,OAAO,CAAC,CAAC;IACtB,sEAAsE;IACtE,eAAe,CAAC,EAAE,OAAO,oBAAoB,CAAC;CAC/C;AAED,qBAAa,iBAAiB;IAKhB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAJjC,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,YAAY,CAAmC;IACvD,OAAO,CAAC,OAAO,CAAS;gBAEK,IAAI,EAAE,qBAAqB;IAExD;;iDAE6C;IAC7C,KAAK,IAAI,IAAI;IAmBb;;0CAEsC;IACtC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAOf,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAWb,OAAO;IA4BrB;;;;;OAKG;YACW,qBAAqB;YAWrB,0BAA0B;IA8BxC,OAAO,CAAC,aAAa;IAYrB;;;;;;OAMG;IACH,OAAO,CAAC,qBAAqB;IAiD7B,+EAA+E;YACjE,qBAAqB;YAgBrB,gBAAgB;IAwC9B;;yDAEqD;YACvC,gBAAgB;IA6D9B;;;;;;;;;;OAUG;YACW,kBAAkB;IAahC;;;;;;OAMG;YACW,sBAAsB;IAWpC;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB;CAczB"}