@llblab/pi-telegram 0.52.2 → 0.53.0

package/dist/lib/generative-app-worker.mjs

@@ -5,10 +5,12 @@
  */
 
 import { execFile } from "node:child_process";
-import { parentPort, workerData } from "node:worker_threads";
 import { pathToFileURL } from "node:url";
+import { parentPort, workerData } from "node:worker_threads";
 
-if (!parentPort) throw new Error("Generative App worker requires a parent port.");
+if (!parentPort) {
+  throw new Error("Generative App worker requires a parent port.");
+}
 
 const controller = new AbortController();
 const runningChildren = new Set();
@@ -25,11 +27,17 @@ function runBoundedProcess(input) {
   }
   const command = input.command?.trim();
   if (!command) throw new Error("Generative App run.command is required.");
-  if (!Array.isArray(input.args ?? []) || (input.args?.length ?? 0) > workerData.runMaxArgs) {
-    throw new Error(`Generative App run.args accepts at most ${workerData.runMaxArgs} strings.`);
+  if (
+    !Array.isArray(input.args ?? []) ||
+    (input.args?.length ?? 0) > workerData.runMaxArgs
+  ) {
+    throw new Error(
+      `Generative App run.args accepts at most ${workerData.runMaxArgs} strings.`,
+    );
   }
   const args = (input.args ?? []).map((argument) => {
-    if (typeof argument !== "string") throw new Error("Generative App run.args must contain strings.");
+    if (typeof argument !== "string")
+      throw new Error("Generative App run.args must contain strings.");
     return argument;
   });
   if (!input.cwd || typeof input.cwd !== "string") {
@@ -82,11 +90,15 @@ function runBoundedProcess(input) {
 try {
   const module = await import(pathToFileURL(workerData.modulePath).href);
   if (typeof module.init !== "function") {
-    throw new Error(`Generative App ${workerData.app} must export named function init.`);
+    throw new Error(
+      `Generative App ${workerData.app} must export named function init.`,
+    );
   }
   const method = module[workerData.method];
   if (typeof method !== "function") {
-    throw new Error(`Generative App ${workerData.app} does not export method ${workerData.method}.`);
+    throw new Error(
+      `Generative App ${workerData.app} does not export method ${workerData.method}.`,
+    );
   }
   const result = await method({
     ...(workerData.argumentPresent ? { argument: workerData.argument } : {}),

package/dist/lib/generative-apps.d.ts

@@ -174,11 +174,6 @@ export declare function installGenerativeApp(options: GenerativeAppRuntimeOption
     script: string;
 }): Promise<GenerativeAppInvocationResult>;
 export declare function parseGenerativeAppBoundAction(prompt: string): GenerativeAppBoundAction | undefined;
-export declare function invokeGenerativeAppBoundAction(options: GenerativeAppRuntimeOptions & {
-    expectedGeneration?: string;
-    expectedRevision?: number;
-    prompt: string;
-}): Promise<GenerativeAppInvocationResult | undefined>;
 export declare function bindGenerativeApp(options: GenerativeAppRuntimeOptions & {
     argument?: unknown;
     method?: string;

package/dist/lib/generative-apps.js

@@ -8,6 +8,8 @@ import { appendFile, copyFile, lstat, mkdir, readFile, rename, rm, stat, writeFi
 import { basename, dirname, extname, join, resolve } from "node:path";
 import { Worker } from "node:worker_threads";
 import { Type } from "@sinclair/typebox";
+import { renameTelegramPathWithRetry } from "./locks.js";
+import { isProcessAlive } from "./process-identity.js";
 const GENERATIVE_APP_NAME = /^[a-z][a-z0-9-]{0,31}$/u;
 const GENERATIVE_APP_METHOD = /^[a-z][a-z0-9_]{0,31}$/u;
 const GENERATIVE_APP_MAX_MODULE_BYTES = 1024 * 1024;
@@ -29,17 +31,6 @@ function byteLength(value) {
 function wait(ms) {
     return new Promise((resolveWait) => setTimeout(resolveWait, ms));
 }
-function isProcessAlive(pid) {
-    if (!Number.isInteger(pid) || pid <= 0)
-        return false;
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (error) {
-        return error.code === "EPERM";
-    }
-}
 function assertAppName(app) {
     if (!GENERATIVE_APP_NAME.test(app)) {
         throw new Error("Generative App name must match /^[a-z][a-z0-9-]{0,31}$/.");
@@ -102,7 +93,9 @@ async function writeFileAtomic(path, content) {
     await mkdir(dirname(path), { recursive: true });
     const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
     await writeFile(temporary, content, { encoding: "utf8", mode: 0o600 });
-    await rename(temporary, path);
+    // Windows may briefly deny replacing a file another reader or scanner holds; share the bounded retry.
+    if (!renameTelegramPathWithRetry(temporary, path))
+        throw new Error("Generative App staging file disappeared before publication.");
 }
 async function acquireGenerativeAppTransitionLock(appDir, waitMs = GENERATIVE_APP_LOCK_WAIT_MS) {
     const lockDir = `${appDir}.transition.lock`;
@@ -175,7 +168,8 @@ async function acquireGenerativeAppTransitionLock(appDir, waitMs = GENERATIVE_AP
                             .then((metadata) => Date.now() - metadata.mtimeMs > 1_000)
                             .catch(() => false)
                         : false;
-                    if ((currentOwnerPid !== undefined && !isProcessAlive(currentOwnerPid)) ||
+                    if ((currentOwnerPid !== undefined &&
+                        !isProcessAlive(currentOwnerPid)) ||
                         currentOwnerlessStale) {
                         await rm(lockDir, { recursive: true, force: true });
                     }
@@ -278,7 +272,9 @@ async function readStateTimeline(appDir) {
             envelopes.push(parsed);
         }
         catch {
-            const hasLaterContent = lines.slice(index + 1).some((entry) => entry.trim());
+            const hasLaterContent = lines
+                .slice(index + 1)
+                .some((entry) => entry.trim());
             if (!hasLaterContent) {
                 await writeFileAtomic(path, envelopes.map((envelope) => JSON.stringify(envelope)).join("\n") +
                     (envelopes.length > 0 ? "\n" : ""));
@@ -615,24 +611,6 @@ export function parseGenerativeAppBoundAction(prompt) {
         app,
     };
 }
-export async function invokeGenerativeAppBoundAction(options) {
-    const action = parseGenerativeAppBoundAction(options.prompt);
-    if (!action)
-        return undefined;
-    return await invokeGenerativeApp({
-        agentDir: options.agentDir,
-        ...(action.argument !== undefined ? { argument: action.argument } : {}),
-        ...(options.expectedGeneration !== undefined
-            ? { expectedGeneration: options.expectedGeneration }
-            : {}),
-        ...(options.expectedRevision !== undefined
-            ? { expectedRevision: options.expectedRevision }
-            : {}),
-        method: action.method,
-        methodTimeoutMs: options.methodTimeoutMs,
-        app: action.app,
-    });
-}
 export async function bindGenerativeApp(options) {
     const hasScript = typeof options.script === "string";
     const hasMethod = typeof options.method === "string";
@@ -645,7 +623,9 @@ export async function bindGenerativeApp(options) {
     return hasScript
         ? await installGenerativeApp({
             agentDir: options.agentDir,
-            ...(options.argument !== undefined ? { argument: options.argument } : {}),
+            ...(options.argument !== undefined
+                ? { argument: options.argument }
+                : {}),
             methodTimeoutMs: options.methodTimeoutMs,
             app: options.app,
             replace: options.replace,
@@ -653,7 +633,9 @@ export async function bindGenerativeApp(options) {
         })
         : await invokeGenerativeApp({
             agentDir: options.agentDir,
-            ...(options.argument !== undefined ? { argument: options.argument } : {}),
+            ...(options.argument !== undefined
+                ? { argument: options.argument }
+                : {}),
             method: options.method,
             methodTimeoutMs: options.methodTimeoutMs,
             app: options.app,
@@ -739,7 +721,9 @@ export function createGenerativeAppLiveSurfaceRuntime(deps) {
             schedule(record, result.refreshAfterMs);
         }
         catch (error) {
-            const classification = deps.classifyEditError?.(error) ?? { kind: "unknown" };
+            const classification = deps.classifyEditError?.(error) ?? {
+                kind: "unknown",
+            };
             if (!ownsRecord(key, record))
                 return;
             deps.recordRuntimeEvent?.("generative-app", error, {
@@ -785,7 +769,8 @@ export function createGenerativeAppLiveSurfaceRuntime(deps) {
             const handle = frame.digest === surface.initialDigest
                 ? surface.handle
                 : await deps.edit(frame);
-            if (result.refreshAfterMs === undefined || !deps.isCurrent({ ...surface, handle }))
+            if (result.refreshAfterMs === undefined ||
+                !deps.isCurrent({ ...surface, handle }))
                 return;
             open({
                 ...surface,
@@ -842,7 +827,9 @@ export function registerTelegramBindTool(pi, deps) {
         const view = {
             text: planned.markdown,
             parseMode: "markdown",
-            ...(planned.replyMarkup !== undefined ? { replyMarkup: planned.replyMarkup } : {}),
+            ...(planned.replyMarkup !== undefined
+                ? { replyMarkup: planned.replyMarkup }
+                : {}),
         };
         return {
             digest: createHash("sha256").update(JSON.stringify(view)).digest("hex"),
@@ -862,7 +849,9 @@ export function registerTelegramBindTool(pi, deps) {
                 if (!edited.ok)
                     throw Object.assign(new Error(edited.message), {
                         deliveryFailureReason: edited.reason,
-                        ...(edited.retryAfterMs === undefined ? {} : { retryAfterMs: edited.retryAfterMs }),
+                        ...(edited.retryAfterMs === undefined
+                            ? {}
+                            : { retryAfterMs: edited.retryAfterMs }),
                     });
                 return { delivery: edited.value, view };
             },
@@ -878,12 +867,18 @@ export function registerTelegramBindTool(pi, deps) {
                     return { kind: "unavailable" };
                 }
                 return {
-                    kind: failure.deliveryFailureReason === "commit-unknown" ? "unknown" : "terminal",
+                    kind: failure.deliveryFailureReason === "commit-unknown"
+                        ? "unknown"
+                        : "terminal",
                 };
             },
             recordRuntimeEvent: deps.recordRuntimeEvent,
-            ...(deps.liveSurfaceSetTimer ? { setTimer: deps.liveSurfaceSetTimer } : {}),
-            ...(deps.liveSurfaceClearTimer ? { clearTimer: deps.liveSurfaceClearTimer } : {}),
+            ...(deps.liveSurfaceSetTimer
+                ? { setTimer: deps.liveSurfaceSetTimer }
+                : {}),
+            ...(deps.liveSurfaceClearTimer
+                ? { clearTimer: deps.liveSurfaceClearTimer }
+                : {}),
         })
         : undefined;
     deps.setLiveSurfaceRuntime?.(liveSurfaces);
@@ -904,7 +899,9 @@ export function registerTelegramBindTool(pi, deps) {
             try {
                 const result = await bindGenerativeApp({
                     agentDir: deps.agentDir,
-                    ...(params.argument !== undefined ? { argument: params.argument } : {}),
+                    ...(params.argument !== undefined
+                        ? { argument: params.argument }
+                        : {}),
                     ...("method" in params && typeof params.method === "string"
                         ? { method: params.method }
                         : {}),
@@ -917,10 +914,10 @@ export function registerTelegramBindTool(pi, deps) {
                         : {}),
                     methodTimeoutMs: deps.methodTimeoutMs,
                 });
-                const activeTurn = params.display === false
-                    ? undefined
-                    : deps.getActiveTurn?.();
-                if (activeTurn && deps.planOutput && (deps.sendView || deps.sendMarkdownReply)) {
+                const activeTurn = params.display === false ? undefined : deps.getActiveTurn?.();
+                if (activeTurn &&
+                    deps.planOutput &&
+                    (deps.sendView || deps.sendMarkdownReply)) {
                     try {
                         const planned = deps.planOutput(result.output, {
                             binding: {
@@ -973,7 +970,12 @@ export function registerTelegramBindTool(pi, deps) {
                             });
                         }
                         return {
-                            content: [{ type: "text", text: formatDisplayedGenerativeAppToolOutput() }],
+                            content: [
+                                {
+                                    type: "text",
+                                    text: formatDisplayedGenerativeAppToolOutput(),
+                                },
+                            ],
                             details: { ...result, displayed: true, messageId },
                         };
                     }
@@ -984,13 +986,23 @@ export function registerTelegramBindTool(pi, deps) {
                             method: result.method,
                         });
                         return {
-                            content: [{ type: "text", text: formatGenerativeAppToolOutput(result.output) }],
+                            content: [
+                                {
+                                    type: "text",
+                                    text: formatGenerativeAppToolOutput(result.output),
+                                },
+                            ],
                             details: { ...result, displayed: false, displayFailed: true },
                         };
                     }
                 }
                 return {
-                    content: [{ type: "text", text: formatGenerativeAppToolOutput(result.output) }],
+                    content: [
+                        {
+                            type: "text",
+                            text: formatGenerativeAppToolOutput(result.output),
+                        },
+                    ],
                     details: { ...result, displayed: false },
                 };
             }

package/dist/lib/inbound.d.ts

@@ -10,9 +10,13 @@ export interface TelegramInboundHandlerConfig {
     mime?: string | string[];
     type?: string | string[];
     template?: string | TelegramInboundCommandTemplateConfig[];
+    /** Falsy skips this handler so selection continues with the next match. */
+    when?: CommandTemplateObjectConfig["when"];
     args?: string[];
     defaults?: Record<string, unknown>;
     timeout?: number | string;
+    retry?: CommandTemplateObjectConfig["retry"];
+    recover?: CommandTemplateObjectConfig["recover"];
 }
 export interface TelegramInboundHandlerFile {
     path: string;
@@ -38,6 +42,7 @@ export interface TelegramInboundHandlerExecOptions {
     signal?: AbortSignal;
     stdin?: string;
     retry?: number;
+    recover?: () => Promise<void>;
 }
 export interface TelegramInboundHandlerExecResult {
     stdout: string;

package/dist/lib/inbound.js

@@ -5,7 +5,7 @@
  */
 import { readFile } from "node:fs/promises";
 import { basename } from "node:path";
-import { buildCommandTemplateInvocation, expandCommandTemplateConfigs, normalizeCommandTemplateConfig, substituteCommandTemplateToken, } from "./command-templates.js";
+import { buildCommandTemplateInvocation, createCommandTemplateRecovery, getCommandTemplateCompositionSteps, getCommandTemplateConfiguredTimeout, getCommandTemplateStepTimeout, normalizeCommandTemplateConfig, resolveCommandTemplateNumericField, shouldRunCommandTemplateConfig, } from "./command-templates.js";
 import { getTelegramVoiceTranscriptionProviders } from "./voice.js";
 const DEFAULT_INBOUND_HANDLER_TIMEOUT_MS = 120_000;
 const INBOUND_HANDLER_REGISTRY_KEY = "__piTelegramInboundHandlers__";
@@ -155,42 +155,10 @@ export function buildTelegramInboundHandlerInvocation(handler, file, cwd, append
         throw new Error("Inbound handler template is required");
     return buildTelegramInboundTemplateInvocation(handler, file, cwd, appendFileIfMissing);
 }
-function resolveTelegramInboundNumericControlField(value, values, label) {
-    if (value === undefined)
-        return undefined;
-    const resolved = typeof value === "string"
-        ? substituteCommandTemplateToken(value, values, label)
-        : value;
-    if (resolved === "")
-        return undefined;
-    const numeric = Number(resolved);
-    if (!Number.isFinite(numeric) || numeric < 0)
-        throw new Error(`Command template ${label} must be a non-negative number.`);
-    return numeric;
-}
-function getTelegramInboundHandlerConfiguredTimeout(handler) {
-    const timeout = typeof handler === "string" ? undefined : handler.timeout;
-    return resolveTelegramInboundNumericControlField(timeout, {}, "timeout");
-}
 function getTelegramInboundHandlerTimeout(handler) {
-    return (getTelegramInboundHandlerConfiguredTimeout(handler) ??
+    return (getCommandTemplateConfiguredTimeout(handler) ??
         DEFAULT_INBOUND_HANDLER_TIMEOUT_MS);
 }
-function getRemainingTelegramInboundTimeout(timeout, startedAt) {
-    return Math.max(1, timeout - (Date.now() - startedAt));
-}
-function getTelegramInboundInitialCompositionStepTimeout(handler, step) {
-    const timeout = getTelegramInboundHandlerTimeout(handler);
-    const stepTimeout = getTelegramInboundHandlerConfiguredTimeout(step);
-    return stepTimeout === undefined ? timeout : Math.min(stepTimeout, timeout);
-}
-function getTelegramInboundCompositionStepTimeout(handler, step, startedAt) {
-    const remaining = getRemainingTelegramInboundTimeout(getTelegramInboundHandlerTimeout(handler), startedAt);
-    const stepTimeout = getTelegramInboundHandlerConfiguredTimeout(step);
-    return stepTimeout === undefined
-        ? remaining
-        : Math.min(stepTimeout, remaining);
-}
 function getTelegramInboundHandlerKind(handler) {
     if (Array.isArray(handler.template))
         return "composition";
@@ -208,28 +176,31 @@ function formatTelegramInboundHandlerFailure(result) {
         parts.push(`stdout:\n${truncateTelegramInboundFailureStream(result.stdout)}`);
     return parts.join("\n\n");
 }
+function getTelegramInboundHandlerRetryOptions(handler, values, cwd, timeout, deps) {
+    if (typeof handler !== "object" || handler.retry === undefined)
+        return {};
+    const recover = createCommandTemplateRecovery(handler, values, {
+        cwd,
+        timeout,
+        execCommand: deps.execCommand,
+    });
+    return {
+        retry: resolveCommandTemplateNumericField(handler.retry, {}, "retry"),
+        ...(recover ? { recover } : {}),
+    };
+}
 async function executeTelegramInboundHandlerInvocation(handler, file, cwd, deps, appendFileIfMissing = true, timeout = getTelegramInboundHandlerTimeout(handler), stdin) {
     const invocation = buildTelegramInboundHandlerInvocation(handler, file, cwd, appendFileIfMissing);
     const result = await deps.execCommand(invocation.command, invocation.args, {
         cwd,
         timeout,
-        ...(typeof handler === "object" && handler.retry !== undefined
-            ? {
-                retry: resolveTelegramInboundNumericControlField(handler.retry, {}, "retry"),
-            }
-            : {}),
+        ...getTelegramInboundHandlerRetryOptions(handler, getTelegramInboundHandlerTemplateValues(file), cwd, timeout, deps),
         ...(stdin !== undefined ? { stdin } : {}),
     });
     if (result.code !== 0)
         throw new Error(formatTelegramInboundHandlerFailure(result));
     return truncateTelegramInboundOutput(result.stdout);
 }
-function getTelegramInboundHandlerCompositionSteps(handler) {
-    if (Array.isArray(handler.template)) {
-        return expandCommandTemplateConfigs(handler);
-    }
-    return [];
-}
 function getTelegramTextHandlerFile() {
     return {
         path: "",
@@ -264,28 +235,24 @@ async function executeTelegramTextHandlerInvocation(handler, text, cwd, deps, ti
         cwd,
         timeout,
         stdin: text,
-        ...(typeof handler === "object" && handler.retry !== undefined
-            ? {
-                retry: resolveTelegramInboundNumericControlField(handler.retry, {}, "retry"),
-            }
-            : {}),
+        ...getTelegramInboundHandlerRetryOptions(handler, getTelegramInboundHandlerTemplateValues(getTelegramTextHandlerFile(), text), cwd, timeout, deps),
     });
     if (result.code !== 0)
         throw new Error(formatTelegramInboundHandlerFailure(result));
     return truncateTelegramInboundOutput(result.stdout);
 }
 async function executeTelegramTextHandler(handler, text, cwd, deps) {
-    const steps = getTelegramInboundHandlerCompositionSteps(handler);
+    const steps = getCommandTemplateCompositionSteps(handler);
     if (steps.length === 0) {
         return (await executeTelegramTextHandlerInvocation(handler, text, cwd, deps)).trim();
     }
     const startedAt = Date.now();
     let output = text;
     for (const [index, step] of steps.entries()) {
+        if (!shouldRunCommandTemplateConfig(step, getTelegramInboundHandlerTemplateValues(getTelegramTextHandlerFile(), output)))
+            continue;
         try {
-            output = await executeTelegramTextHandlerInvocation(step, output, cwd, deps, index === 0
-                ? getTelegramInboundInitialCompositionStepTimeout(handler, step)
-                : getTelegramInboundCompositionStepTimeout(handler, step, startedAt));
+            output = await executeTelegramTextHandlerInvocation(step, output, cwd, deps, getCommandTemplateStepTimeout(getTelegramInboundHandlerTimeout(handler), step, index === 0 ? undefined : Date.now() - startedAt));
         }
         catch (error) {
             if (typeof step === "object" && step.failure === "root")
@@ -303,6 +270,9 @@ async function processTelegramTextHandlers(options) {
     let text = options.rawText;
     for (const handler of findTelegramTextHandlers(options.handlers)) {
         try {
+            // An unresolvable guard fails only this handler, like its command would.
+            if (!shouldRunCommandTemplateConfig(handler, getTelegramInboundHandlerTemplateValues(getTelegramTextHandlerFile(), text)))
+                continue;
             const output = await executeTelegramTextHandler(handler, text, options.cwd, options);
             if (output)
                 text = output;
@@ -384,18 +354,22 @@ async function readBuiltInTelegramTextAttachment(file) {
     return truncateTelegramInboundOutput(`[${name}]\n${normalized}`);
 }
 async function executeTelegramInboundHandler(handler, file, cwd, deps) {
-    const steps = getTelegramInboundHandlerCompositionSteps(handler);
+    const steps = getCommandTemplateCompositionSteps(handler);
     if (steps.length === 0) {
         const output = await executeTelegramInboundHandlerInvocation(handler, file, cwd, deps);
         return output.trim();
     }
     const startedAt = Date.now();
+    const values = getTelegramInboundHandlerTemplateValues(file);
     let output = "";
-    for (const [index, step] of steps.entries()) {
+    let started = false;
+    for (const step of steps) {
+        if (!shouldRunCommandTemplateConfig(step, values))
+            continue;
+        const first = !started;
+        started = true;
         try {
-            output = await executeTelegramInboundHandlerInvocation(step, file, cwd, deps, false, index === 0
-                ? getTelegramInboundInitialCompositionStepTimeout(handler, step)
-                : getTelegramInboundCompositionStepTimeout(handler, step, startedAt), index === 0 ? undefined : output);
+            output = await executeTelegramInboundHandlerInvocation(step, file, cwd, deps, false, getCommandTemplateStepTimeout(getTelegramInboundHandlerTimeout(handler), step, first ? undefined : Date.now() - startedAt), first ? undefined : output);
         }
         catch (error) {
             if (typeof step === "object" && step.failure === "root")
@@ -420,6 +394,8 @@ export async function processTelegramInboundHandlers(options) {
         const handlers = findTelegramInboundHandlers(options.handlers, file);
         for (const handler of handlers) {
             try {
+                if (!shouldRunCommandTemplateConfig(handler, getTelegramInboundHandlerTemplateValues(file)))
+                    continue;
                 const output = await executeTelegramInboundHandler(handler, file, options.cwd, options);
                 if (output) {
                     outputs.push({ file, output, handler });

package/dist/lib/journal.d.ts

@@ -5,7 +5,7 @@
  * bounded atomic publication, durable queue-receipt/failure state, and compaction.
  * It does not own polling, update execution, queue admission, or follower routing.
  */
-import { type TelegramProcessLiveness } from "./bus.ts";
+import { type TelegramProcessLiveness } from "./process-identity.ts";
 import { type TelegramWorkspaceAdmissionLedger, type TelegramWorkspaceAdmissionScope } from "./workspace-admission.ts";
 export declare const TELEGRAM_UPDATE_JOURNAL_VERSION: 1;
 export declare const TELEGRAM_UPDATE_JOURNAL_EXCLUSION_VERSION: 2;
@@ -150,11 +150,18 @@ export interface TelegramUpdateJournalLegacyCustodyDisposition {
 export type TelegramUpdateJournalOperatorDisposition = TelegramUpdateJournalTerminalOperatorDisposition | TelegramUpdateJournalLegacyCustodyDisposition;
 export declare const TELEGRAM_ROUTING_INPUT_TTL_MS: number;
 /** A source-only choice deadline, never a queue lease or a Thread deletion grant. */
+/** Where a source's chooser was published, so a restarted owner can revive that exact message. */
+export interface TelegramUpdateJournalRoutingChooser {
+    chatId: number;
+    threadId?: number;
+    messageId: number;
+}
 export interface TelegramUpdateJournalRoutingInput {
     operatorUserId: number;
     publishedAtMs: number;
     expiresAtMs: number;
     phase: "waiting" | "selected";
+    chooser?: TelegramUpdateJournalRoutingChooser;
 }
 export interface TelegramUpdateJournalEntry {
     updateId: number;
@@ -381,6 +388,7 @@ export type TelegramRoutingInputExpiryEvidence = Omit<TelegramUpdateJournalAband
 export interface TelegramRoutingInputJournal {
     arm(input: TelegramRoutingInputAuthority & {
         publishedAtMs: number;
+        chooser?: TelegramUpdateJournalRoutingChooser;
     }): TelegramUpdateJournalEntry[];
     select(input: TelegramRoutingInputAuthority): {
         issued: boolean;
@@ -415,7 +423,7 @@ export interface TelegramUpdateJournalStore {
     recoverDeadQueueOwner(input: TelegramUpdateJournalDeadQueueOwnerRecoveryInput): TelegramUpdateJournalDeadQueueOwnerRecoveryResult;
     removeCompleted(updateIds: readonly number[]): TelegramUpdateJournalRemoveResult;
     /** Guarded completion; every supplied source must still match, and absence is a conflict, not an ACK. */
-    removeCompletedExact(updateIds: readonly number[], expectedSources: readonly TelegramUpdateJournalEntryDigest[], completions?: readonly TelegramUpdateJournalSourceCompletion[]): TelegramUpdateJournalRemoveResult;
+    removeCompletedExact(updateIds: readonly number[], expectedSources: readonly TelegramUpdateJournalEntryDigest[], completions?: readonly TelegramUpdateJournalSourceCompletion[], isCurrent?: () => boolean): TelegramUpdateJournalRemoveResult;
     /** Strict read-only observation; neither source absence nor a different scope is completion evidence. */
     inspectSourceCompletion(expected: TelegramUpdateJournalSourceCompletion): TelegramUpdateJournalSourceCompletion | undefined;
     /** Complete strict observation of a retained, unoffered v1 queue receipt; never acquires readiness. */
@@ -716,10 +724,32 @@ export interface TelegramJournalNamespaceInspection {
 export declare function inspectTelegramProfileJournalNamespace(input: TelegramJournalNamespaceInspectionInput): TelegramJournalNamespaceInspection;
 /** Read-only evidence over polling, retained flat recipients and role-neutral session journals. */
 export declare function inspectTelegramSessionJournalNamespace(input: TelegramJournalNamespaceInspectionInput): TelegramJournalNamespaceInspection;
+/** Whether an update addresses this private-chat Thread anywhere in its payload (message, callback, reaction, …). */
+export declare function doesTelegramJournalUpdateNameThread(update: unknown, target: {
+    chatId: number;
+    threadId: number;
+}): boolean;
+/** A button tap alone carries no input, so it never keeps a tab whose inputs are resolved (the in-flight Cancel itself). */
+export declare function isTelegramJournalLoneCallbackUpdate(update: unknown): boolean;
 /** Complete-empty protection only; caller holds source serialization through consumption. Never deletion authority. */
 export declare function isTelegramThreadCleanupJournalNamespaceClear(input: TelegramJournalNamespaceInspectionInput & {
     requiredJournalBindingKeys: readonly string[];
     withSourceReference: NonNullable<TelegramJournalNamespaceInspectionInput["withSourceReference"]>;
+    /**
+     * The tab being cleaned and its own recorded inputs. When given, a plain pending input with no custody that
+     * neither names this tab nor belongs to it cannot be delivered here and does not protect it, nor does a plain
+     * button tap even in this tab; without it, every non-empty journal protects, as before.
+     */
+    cleanup?: {
+        target: {
+            chatId: number;
+            threadId: number;
+        };
+        ownInputs: readonly {
+            journalBindingKey: string;
+            updateIds: readonly number[];
+        }[];
+    };
 }): boolean;
 export declare function publishTelegramUpdateJournalSegment(path: string, segment: TelegramUpdateJournalSegment): TelegramUpdateJournalSegmentPublicationResult;
 export declare function createTelegramUpdateQueueHandoffToken(): string;
@@ -761,7 +791,7 @@ export interface TelegramUpdateJournalRuntimeBindingResolverDeps {
     withSourceSerialization?: TelegramUpdateJournalStoreOptions["withSourceSerialization"];
     getWorkspaceAdmission?: () => Pick<TelegramWorkspaceAdmissionLedger, "acquireAdmission" | "releaseAdmission"> | undefined;
     onRecovery?: (event: TelegramUpdateJournalRecoveryEvent) => void;
-    /** Strict no-follow source handles; defaults to platform support (absent on Windows). */
+    /** Strict private source handles; on by default on every platform (see TELEGRAM_STRICT_READ_FLAGS). */
     strictSourceAccess?: boolean;
 }
 export declare function createTelegramUpdateJournalRuntimeBindingResolver(deps: TelegramUpdateJournalRuntimeBindingResolverDeps): () => TelegramUpdateJournalRuntimeBinding | undefined;