@crouton-kit/humanloop 0.3.39 → 0.4.1

package/dist/inbox/maintenance.js

@@ -0,0 +1,145 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { inboxRootsDirectory, listInboxRoots } from './registry.js';
+import { reconcileCompletions } from './completion.js';
+import { dispatchVisualCleanup, listVisualCleanupObligationsForRoot, reconcileStaleVisualRequestsForRoot } from './visual.js';
+const LEASE_STALE_MS = 300_000;
+function leasePath() { return join(dirname(inboxRootsDirectory()), 'maintenance.lock'); }
+function roots() { return listInboxRoots().filter((root) => root.available).map((root) => root.root); }
+function leaseOwner(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(path, 'owner.json'), 'utf8'));
+        return typeof parsed.pid === 'number' && Number.isInteger(parsed.pid) ? parsed.pid : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function staleLease(path) {
+    const owner = leaseOwner(path);
+    if (owner !== undefined)
+        return !processIsAlive(owner);
+    try {
+        return Date.now() - statSync(path).mtimeMs > LEASE_STALE_MS;
+    }
+    catch {
+        return true;
+    }
+}
+/** Start one detached repair pass. The lease makes repeated UI gestures free. */
+export function kickInboxMaintenance() {
+    const lease = leasePath();
+    try {
+        mkdirSync(dirname(lease), { recursive: true, mode: 0o700 });
+    }
+    catch {
+        return;
+    }
+    try {
+        mkdirSync(lease, { mode: 0o700 });
+    }
+    catch {
+        if (!staleLease(lease))
+            return;
+        try {
+            rmSync(lease, { recursive: true, force: true });
+            mkdirSync(lease, { mode: 0o700 });
+        }
+        catch {
+            return;
+        }
+    }
+    const builtEntry = fileURLToPath(new URL('../cli.js', import.meta.url));
+    const sourceEntry = fileURLToPath(new URL('../cli.ts', import.meta.url));
+    const entry = existsSync(builtEntry) ? builtEntry : sourceEntry;
+    if (!existsSync(entry)) {
+        rmSync(lease, { recursive: true, force: true });
+        return;
+    }
+    // A built CLI needs no parent flags. Source-mode launches retain their tsx
+    // loader, but always execute Humanloop's CLI rather than the caller's
+    // entrypoint (which may be a test or a consuming application).
+    const runtimeArgs = entry.endsWith('.ts') ? process.execArgv : [];
+    const child = spawn(process.execPath, [...runtimeArgs, entry, 'inbox', '_maintain', '--lease', lease], {
+        detached: true,
+        stdio: 'ignore',
+    });
+    if (child.pid === undefined) {
+        rmSync(lease, { recursive: true, force: true });
+        return;
+    }
+    try {
+        writeFileSync(join(lease, 'owner.json'), JSON.stringify({ pid: child.pid }));
+    }
+    catch {
+        child.kill();
+        rmSync(lease, { recursive: true, force: true });
+        return;
+    }
+    child.unref();
+}
+function dueTasks(allRoots) {
+    const tasks = [];
+    for (const root of allRoots) {
+        try {
+            tasks.push(...listVisualCleanupObligationsForRoot(root));
+        }
+        catch { /* malformed historical state is isolated to its root */ }
+    }
+    return tasks;
+}
+async function repairOnce() {
+    const allRoots = roots();
+    for (const root of allRoots) {
+        try {
+            await reconcileCompletions(root);
+        }
+        catch { /* receipt remains durable for the next pass */ }
+    }
+    const retirements = allRoots.flatMap((root) => {
+        try {
+            return reconcileStaleVisualRequestsForRoot(root).map((entry) => entry.delivery);
+        }
+        catch {
+            return [];
+        }
+    });
+    await Promise.all(retirements);
+    const tasks = dueTasks(allRoots);
+    await Promise.all(tasks.filter((task) => Date.parse(task.nextAttemptAt) <= Date.now()).map((task) => dispatchVisualCleanup(task.root, task.dir, task.requestId)));
+    return dueTasks(roots());
+}
+function releaseLease(lease) {
+    if (leaseOwner(lease) !== process.pid)
+        return;
+    rmSync(lease, { recursive: true, force: true });
+}
+/** Run repair and stay alive only until the durable cleanup retry queue is empty. */
+export async function runInboxMaintenance(lease) {
+    try {
+        while (true) {
+            const tasks = await repairOnce();
+            const next = tasks.reduce((earliest, task) => {
+                const due = Date.parse(task.nextAttemptAt);
+                return Number.isFinite(due) && (earliest === undefined || due < earliest) ? due : earliest;
+            }, undefined);
+            if (next === undefined)
+                return;
+            await new Promise((resolve) => setTimeout(resolve, Math.max(0, next - Date.now())));
+        }
+    }
+    finally {
+        releaseLease(lease);
+    }
+}

package/dist/inbox/registry.d.ts

@@ -9,6 +9,8 @@ export interface InboxRootRegistration {
     owner: string;
     handler?: CompletionHandler;
     followUpHandler?: CompletionHandler;
+    visualHandler?: CompletionHandler;
+    focusHandler?: CompletionHandler;
 }
 export interface InboxRootStatus extends InboxRootRegistration {
     available: boolean;
@@ -18,8 +20,14 @@ export interface RegisterInboxRootOptions {
     owner: string;
     handler?: CompletionHandler;
     followUpHandler?: CompletionHandler;
+    visualHandler?: CompletionHandler;
+    focusHandler?: CompletionHandler;
 }
+export declare function inboxStateDirectory(): string;
 export declare function inboxRootsDirectory(): string;
+export declare function inboxActivityPath(): string;
+/** Signal one durable ticket mutation to every open inbox without watching every root. */
+export declare function signalInboxActivity(): void;
 /** Create/canonicalize a root and claim its user-scoped registration. */
 export declare function registerInboxRoot(opts: RegisterInboxRootOptions): InboxRootRegistration;
 /** Removes a matching available root through its real path, or an unavailable record by its stored canonical path. */

package/dist/inbox/registry.js

@@ -1,10 +1,20 @@
-import { chmodSync, existsSync, mkdirSync, readdirSync, realpathSync, unlinkSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, readdirSync, realpathSync, unlinkSync, writeFileSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { atomicWriteJson, readJson, withExclusiveDirectoryLock } from './convention.js';
 function stateHome() { return process.env['XDG_STATE_HOME'] || join(homedir(), '.local', 'state'); }
-export function inboxRootsDirectory() { return join(stateHome(), 'humanloop', 'inbox-roots'); }
+export function inboxStateDirectory() { return join(stateHome(), 'humanloop'); }
+export function inboxRootsDirectory() { return join(inboxStateDirectory(), 'inbox-roots'); }
+export function inboxActivityPath() { return join(inboxStateDirectory(), 'inbox-activity'); }
+/** Signal one durable ticket mutation to every open inbox without watching every root. */
+export function signalInboxActivity() {
+    try {
+        mkdirSync(inboxStateDirectory(), { recursive: true, mode: 0o700 });
+        writeFileSync(inboxActivityPath(), `${Date.now()}\n`, { mode: 0o600 });
+    }
+    catch { /* a later popup scan is still authoritative */ }
+}
 function recordPath(root) { return join(inboxRootsDirectory(), createHash('sha256').update(root).digest('hex')); }
 function canonicalRoot(root) { try {
     return realpathSync(root);
@@ -15,8 +25,8 @@ catch {
 function validateHandler(handler) {
     if (handler === undefined)
         return undefined;
-    if (!handler.command || !Array.isArray(handler.args) || !handler.args.every((arg) => typeof arg === 'string'))
-        throw new Error('completion handler requires a command and string args');
+    if (typeof handler.command !== 'string' || handler.command.trim() === '' || !Array.isArray(handler.args) || !handler.args.every((arg) => typeof arg === 'string'))
+        throw new Error('handler requires a non-empty command and string args');
     return { command: handler.command, args: [...handler.args] };
 }
 function validateRegistration(raw) {
@@ -30,6 +40,8 @@ function validateRegistration(raw) {
             schema: 'humanloop.inbox-root/v1', root: value.root, owner: value.owner,
             handler: value.handler === undefined ? undefined : validateHandler(value.handler),
             followUpHandler: value.followUpHandler === undefined ? undefined : validateHandler(value.followUpHandler),
+            visualHandler: value.visualHandler === undefined ? undefined : validateHandler(value.visualHandler),
+            focusHandler: value.focusHandler === undefined ? undefined : validateHandler(value.focusHandler),
         };
     }
     catch {
@@ -50,7 +62,7 @@ export function registerInboxRoot(opts) {
             throw new Error(`inbox root is already owned by ${existing.owner}`);
         if (existing !== null && existing.root !== root)
             throw new Error('inbox root registry hash collision');
-        const registration = { schema: 'humanloop.inbox-root/v1', root, owner: opts.owner, handler: validateHandler(opts.handler), followUpHandler: validateHandler(opts.followUpHandler) };
+        const registration = { schema: 'humanloop.inbox-root/v1', root, owner: opts.owner, handler: validateHandler(opts.handler), followUpHandler: validateHandler(opts.followUpHandler), visualHandler: validateHandler(opts.visualHandler), focusHandler: validateHandler(opts.focusHandler) };
         atomicWriteJson(path, registration);
         chmodSync(path, 0o600);
         return registration;

package/dist/inbox/tickets.d.ts

@@ -1,6 +1,11 @@
 import type { Deck, DeckTicketResult, FeedbackResult, ReviewDescriptor, TicketResult } from '../types.js';
 /** Strict decoder for the only canonical final marker. */
 export declare function readTicketResult(dirOrResponsePath: string): TicketResult | null;
+/** Canonical registered-root/direct-child containment shared by host protocols. */
+export declare function requireCanonicalTicket(root: string, dir: string): {
+    root: string;
+    dir: string;
+};
 export interface SubmitDeckOptions {
     root: string;
     id: string;

package/dist/inbox/tickets.js

@@ -1,12 +1,14 @@
-import { existsSync, linkSync, mkdirSync, readFileSync, realpathSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync } from 'node:fs';
 import { basename, dirname, isAbsolute, resolve } from 'node:path';
 import { z } from 'zod';
 import { buildSummary } from '../summary.js';
-import { clearProgress, claimPath, deckPath, deliveryErrorPath, deliveryPath, followupRequestPath, followupResultPath, progressPath, responsePath, reviewPath } from './convention.js';
+import { clearProgress, claimPath, deckPath, deliveryErrorPath, deliveryPath, followupRequestPath, followupResultPath, progressPath, publishJsonExclusive, responsePath, reviewPath, visualsDir } from './convention.js';
 import { validateDeck, validateReviewDescriptor, validateReviewProjection, resolveDeckBodyPaths } from './deck-schema.js';
-import { registeredInboxRoot } from './registry.js';
+import { registeredInboxRoot, signalInboxActivity } from './registry.js';
 import { readTicketClaim, releaseClaimLocked, withTicketLock } from './claim.js';
 import { dispatchCompletion } from './completion.js';
+import { cancelVisualRequestsForTicket } from './visual.js';
+import { kickInboxMaintenance } from './maintenance.js';
 const ticketId = z.string().regex(/^[A-Za-z0-9_-]+$/).min(1).max(128);
 const responseSchema = z.object({ id: z.string().min(1), selectedOptionId: z.string().optional(), selectedOptionIds: z.array(z.string()).optional(), freetext: z.string().optional(), optionComments: z.record(z.string(), z.string()).optional() }).strict();
 const feedbackCommentSchema = z.object({ id: z.string().min(1), line: z.number().int().positive(), endLine: z.number().int().positive(), quote: z.string().optional(), colStart: z.number().int().nonnegative().optional(), colEnd: z.number().int().nonnegative().optional(), lineText: z.string(), comment: z.string().min(1), createdAt: z.string().min(1) }).strict();
@@ -70,7 +72,7 @@ function ticketDir(root, id) {
 function discardCreatedTicket(dir, created) { if (created)
     rmSync(dir, { recursive: true, force: true }); }
 function hasTicketProtocolState(dir) {
-    return [deckPath(dir), reviewPath(dir), responsePath(dir), progressPath(dir), claimPath(dir), deliveryPath(dir), deliveryErrorPath(dir), followupRequestPath(dir), followupResultPath(dir)].some(existsSync);
+    return [deckPath(dir), reviewPath(dir), responsePath(dir), progressPath(dir), claimPath(dir), deliveryPath(dir), deliveryErrorPath(dir), followupRequestPath(dir), followupResultPath(dir), visualsDir(dir)].some(existsSync);
 }
 function requireRegisteredTicket(dir) {
     const canonical = realpathSync(dir);
@@ -82,21 +84,17 @@ function requireRegisteredTicket(dir) {
         throw new Error('ticket has no request descriptor');
     return { root, dir: canonical };
 }
+/** Canonical registered-root/direct-child containment shared by host protocols. */
+export function requireCanonicalTicket(root, dir) {
+    const registration = registeredInboxRoot(root);
+    const ticket = requireRegisteredTicket(dir);
+    if (registration === null || ticket.root !== registration.root)
+        throw new Error('ticket is not a canonical direct child of the registered root');
+    return ticket;
+}
 function publishRequest(path, value) {
-    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-    const temp = `${path}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
-    writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
-    try {
-        linkSync(temp, path);
-    }
-    catch (error) {
-        if (error.code === 'EEXIST')
-            throw new Error(`ticket request already exists: ${path}`);
-        throw error;
-    }
-    finally {
-        unlinkSync(temp);
-    }
+    if (!publishJsonExclusive(path, value))
+        throw new Error(`ticket request already exists: ${path}`);
 }
 export function submitDeck(opts) {
     // Validate shape before mutating caller-owned interaction directories.
@@ -108,6 +106,7 @@ export function submitDeck(opts) {
         const deck = validateDeck(resolveDeckBodyPaths(opts.deck, dir));
         const stamped = { ...deck, source: { ...(deck.source ?? {}), blockedSince: deck.source?.blockedSince ?? new Date().toISOString() } };
         publishRequest(deckPath(dir), stamped);
+        signalInboxActivity();
         return { id: opts.id, dir, kind: 'deck' };
     }
     catch (error) {
@@ -127,6 +126,7 @@ export function submitReview(opts) {
             throw new Error(`ticket protocol state already exists: ${dir}`);
         const descriptor = validateReviewProjection(dir, { schema: 'humanloop.review/v1', file: source, output: resolve(opts.review.output ?? `${dir}/feedback.json`), title: opts.review.title, source: opts.review.source, blockedSince: opts.review.blockedSince ?? new Date().toISOString() });
         publishRequest(reviewPath(dir), descriptor);
+        signalInboxActivity();
         return { id: opts.id, dir, kind: 'review' };
     }
     catch (error) {
@@ -135,21 +135,7 @@ export function submitReview(opts) {
     }
 }
 function exclusiveResult(dir, result) {
-    const path = responsePath(dir);
-    const temp = `${path}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
-    writeFileSync(temp, `${JSON.stringify(result, null, 2)}\n`, { mode: 0o600 });
-    try {
-        linkSync(temp, path);
-        return true;
-    }
-    catch (error) {
-        if (error.code === 'EEXIST')
-            return false;
-        throw error;
-    }
-    finally {
-        unlinkSync(temp);
-    }
+    return publishJsonExclusive(responsePath(dir), result);
 }
 function requireDeck(dir) { return validateDeck(JSON.parse(readFileSync(deckPath(dir), 'utf8'))); }
 function requireReview(dir) { return validateReviewDescriptor(JSON.parse(readFileSync(reviewPath(dir), 'utf8'))); }
@@ -187,19 +173,26 @@ function requireClaimOwnership(dir, token) {
 function clearOwnedWork(dir, claimToken) { clearProgress(dir); releaseClaimLocked(dir, claimToken); }
 export function finalizeDeck(dir, responses, claimToken, completedAt = new Date().toISOString()) {
     const ticket = requireRegisteredTicket(dir);
-    return withTicketLock(ticket.dir, () => {
+    const finalized = withTicketLock(ticket.dir, () => {
         requireClaimOwnership(ticket.dir, claimToken);
         const deck = requireDeck(ticket.dir);
         const parsedResponses = validateDeckResponses(deck, responses);
+        // A valid primary result ends its panel generation before the canonical
+        // response can cross the owner boundary. The protocol persists cancellation
+        // first; its independent cleanup executor owns eventual handler delivery.
+        void cancelVisualRequestsForTicket(ticket.root, ticket.dir).finally(kickInboxMaintenance);
         const result = { schema: 'humanloop.response/v2', kind: 'deck', responses: parsedResponses, summary: buildSummary(deck, parsedResponses), completedAt };
         const won = exclusiveResult(ticket.dir, result);
         clearOwnedWork(ticket.dir, claimToken);
         return { won, result: won ? result : readTicketResult(ticket.dir) ?? result };
     });
+    if (finalized.won)
+        signalInboxActivity();
+    return finalized;
 }
 export function finalizeReview(dir, feedback, claimToken, completedAt = new Date().toISOString()) {
     const ticket = requireRegisteredTicket(dir);
-    return withTicketLock(ticket.dir, () => {
+    const finalized = withTicketLock(ticket.dir, () => {
         requireClaimOwnership(ticket.dir, claimToken);
         const descriptor = requireReview(ticket.dir);
         const parsed = feedbackSchema.parse(feedback);
@@ -210,14 +203,20 @@ export function finalizeReview(dir, feedback, claimToken, completedAt = new Date
         clearOwnedWork(ticket.dir, claimToken);
         return { won, result: won ? result : readTicketResult(ticket.dir) ?? result, descriptor };
     });
+    if (finalized.won)
+        signalInboxActivity();
+    return finalized;
 }
 export function cancelTicketResult(dir, opts = {}) {
     const ticket = requireRegisteredTicket(dir);
-    return withTicketLock(ticket.dir, () => {
+    const canceled = withTicketLock(ticket.dir, () => {
         const result = { schema: 'humanloop.cancel/v1', kind: 'canceled', canceledAt: new Date().toISOString(), ...(opts.reason === undefined ? {} : { reason: opts.reason }), ...(opts.actor === undefined ? {} : { actor: opts.actor }) };
         const won = exclusiveResult(ticket.dir, result);
         return { status: won ? 'canceled' : 'already_resolved', result: won ? result : readTicketResult(ticket.dir) ?? result };
     });
+    if (canceled.status === 'canceled')
+        signalInboxActivity();
+    return canceled;
 }
 export function ticketRoot(dir) {
     try {

package/dist/inbox/visual.d.ts

@@ -0,0 +1,130 @@
+import type { CanonicalInteraction, Interaction, VisualRequest as PanelVisualRequest } from '../types.js';
+import { type CompletionHandler } from './registry.js';
+export declare const VISUAL_CAPABILITY: "humanloop.visual/v1";
+export interface VisualClaimIdentity {
+    token: string;
+    host: string;
+    pid: number;
+    claimedAt: string;
+}
+export interface VisualCleanupObligation {
+    reason: 'canceled' | 'unreceipted_start_error';
+    attempts: number;
+    nextAttemptAt: string;
+    lastAttemptAt?: string;
+    lastError?: string;
+}
+interface VisualBinding {
+    capability: typeof VISUAL_CAPABILITY;
+    owner: string;
+    root: string;
+    dir: string;
+    ticketId: string;
+    requestId: string;
+    generationId: string;
+    interactionId: string;
+    interaction: CanonicalInteraction;
+    claim: VisualClaimIdentity;
+    handler: CompletionHandler;
+}
+export interface VisualProtocolRequest extends VisualBinding {
+    schema: 'humanloop.visual-request/v1';
+    state: 'running' | 'canceled' | 'terminal';
+    requestedAt: string;
+    settledAt?: string;
+    cleanup?: VisualCleanupObligation;
+}
+export interface VisualRequestEvent extends VisualBinding {
+    schema: 'humanloop.visual-request-event/v1';
+    action: 'start' | 'cancel';
+}
+interface VisualResultBinding extends VisualBinding {
+    schema: 'humanloop.visual-result/v1';
+    completedAt: string;
+}
+export type VisualProtocolResult = (VisualResultBinding & {
+    status: 'ready';
+    markdown: string;
+}) | (VisualResultBinding & {
+    status: 'error';
+    error: string;
+});
+export type VisualResultSubmission = {
+    requestId: string;
+    generationId: string;
+    interactionId: string;
+    interaction: CanonicalInteraction;
+    claimToken: string;
+    status: 'ready';
+    markdown: string;
+} | {
+    requestId: string;
+    generationId: string;
+    interactionId: string;
+    interaction: CanonicalInteraction;
+    claimToken: string;
+    status: 'error';
+    error: string;
+};
+export interface StartVisualRequestOptions {
+    root: string;
+    dir: string;
+    claimToken: string;
+    request: PanelVisualRequest;
+}
+export type VisualStartDeliveryResult = 'delivered' | 'already_attempted' | 'ineligible' | 'failed';
+export type VisualCleanupDeliveryResult = 'delivered' | 'pending' | 'none';
+export interface StartedVisualRequest {
+    request: VisualProtocolRequest;
+    /** Resolves after the one permitted start attempt reaches a determinate outcome. */
+    delivery: Promise<VisualStartDeliveryResult>;
+}
+export interface VisualCleanupTask {
+    root: string;
+    dir: string;
+    requestId: string;
+    reason: VisualCleanupObligation['reason'];
+    nextAttemptAt: string;
+}
+/** Normalize one Interaction into the sole persisted/event correlation shape. */
+export declare function canonicalizeInteraction(raw: Interaction | CanonicalInteraction): CanonicalInteraction;
+/** Stable bytes used for every interaction equality check across the protocol. */
+export declare function canonicalInteractionJson(raw: Interaction | CanonicalInteraction): string;
+export declare function parseVisualRequestEvent(raw: unknown): VisualRequestEvent;
+/** Strict, repairing reader; malformed or unbound request bytes return null. */
+export declare function readVisualRequest(root: string, dir: string, requestId: string): VisualProtocolRequest | null;
+/** Strict, repairing reader; canceled and mismatched results are never returned. */
+export declare function readVisualResult(root: string, dir: string, requestId: string): VisualProtocolResult | null;
+/** Decode an event and atomically bind it to Humanloop's immutable request state. */
+export declare function readVisualRequestForEvent(raw: unknown): VisualProtocolRequest | null;
+/** Persist one claim-bound request and dispatch its frozen handler at most once. */
+export declare function startVisualRequest(opts: StartVisualRequestOptions): StartedVisualRequest;
+/** Compare-publish the first fully correlated ready/error result. Stale writers are no-ops. */
+export declare function submitVisualResult(root: string, dir: string, raw: VisualResultSubmission): {
+    published: boolean;
+};
+/** Attempt one due cleanup delivery through the request's frozen handler. */
+export declare function dispatchVisualCleanup(root: string, dir: string, requestId: string): Promise<VisualCleanupDeliveryResult>;
+/** State-first cancellation for one handle; the returned promise is cleanup delivery only. */
+export declare function cancelVisualRequest(root: string, dir: string, requestId: string): Promise<VisualCleanupDeliveryResult>;
+/** State-first cancel every running request, then dispatch every owed cleanup (including start failures). */
+export declare function cancelVisualRequestsForTicket(root: string, dir: string): Promise<{
+    canceled: number;
+    cleanupOwed: number;
+}>;
+/** Durable tasks the next controller-owned retry executor should schedule. */
+export declare function listVisualCleanupObligations(root: string, dir: string): VisualCleanupTask[];
+export interface VisualRequestReconciliation {
+    retired: number;
+    cleanupOwed: number;
+    /** Cleanup delivery only; reconciliation never redelivers a start. */
+    delivery: Promise<VisualCleanupDeliveryResult[]>;
+}
+/** Retire abandoned generations under the ticket claim boundary. A live claim is
+ * authoritative; a newly acquired claim retires every older generation first. */
+export declare function reconcileVisualRequestsForTicket(root: string, dir: string, currentClaimToken?: string): VisualRequestReconciliation;
+/** Enumerate direct ticket children only, including resolved tickets whose cleanup is still owed. */
+export declare function listVisualCleanupObligationsForRoot(root: string): VisualCleanupTask[];
+/** Startup reconciliation only retires stale/missing-claim work; live owners stay untouched. */
+export declare function reconcileStaleVisualRequestsForRoot(root: string): VisualRequestReconciliation[];
+export {};