@crouton-kit/humanloop 0.4.0 → 0.4.2

package/dist/cli.js

@@ -7,6 +7,7 @@ import { validateDeck } from './inbox/deck-schema.js';
 import { managedInboxRoot, registerInboxRoot, registeredInboxRoot, unregisterInboxRoot, listInboxRoots } from './inbox/registry.js';
 import { submitDeck, submitReview } from './inbox/tickets.js';
 import { scanInbox } from './inbox/scan.js';
+import { runInboxMaintenance } from './inbox/maintenance.js';
 import { openInboxPopup } from './surfaces/inbox-popup.js';
 import { toggleInboxPopup } from './tui/tmux.js';
 import { ask } from './api.js';
@@ -47,11 +48,11 @@ function requireRegisteredRoot(root) {
 const program = new Command();
 program.name('hl').description('Humanloop durable inbox and review surface.').helpOption('-h, --help');
 const inbox = program.command('inbox').description('Open, inspect, and configure the centralized human inbox.');
-inbox.command('open').description('Open the inbox controller in this human TTY.').option('--root <path>', 'filter to a registered root', (value, prior) => [...prior, value], []).option('--control-socket <path>', 'popup control socket').action(async (options) => {
+inbox.command('open').description('Open the inbox controller in this human TTY.').option('--root <path>', 'filter to a registered root', (value, prior) => [...prior, value], []).option('--control-socket <path>', 'popup control socket').option('--target-pane <pane>', 'tmux pane underneath the popup').action(async (options) => {
     if (!process.stdin.isTTY || !process.stdout.isTTY)
         fail('hl inbox open requires an interactive TTY; use hl inbox list for read-only output');
     try {
-        await openInboxPopup(options.controlSocket, roots(options.root));
+        await openInboxPopup(options.controlSocket, roots(options.root), options.targetPane);
     }
     catch (error) {
         fail(error);
@@ -73,6 +74,9 @@ inbox.command('toggle').description('Toggle the inbox popup for one tmux client.
     process.exit(result === 'failed' || result === 'ambiguous_client' ? 1 : 0);
 });
 inbox.command('list').description('Print pending tickets newest first as JSON.').option('--root <path>', 'filter to a root', (value, prior) => [...prior, value], []).action((options) => emit(scanInbox(roots(options.root))));
+inbox.command('_maintain', { hidden: true }).requiredOption('--lease <path>').action(async (options) => {
+    await runInboxMaintenance(resolve(options.lease));
+});
 const root = inbox.command('roots').description('Manage durable interaction roots.');
 root.command('register').description('Register a root owned by a host.').requiredOption('--root <path>').requiredOption('--owner <owner>').option('--handler-command <path>').option('--handler-arg <arg>', 'repeatable direct-exec handler argument', (value, prior) => [...prior, value], []).action((options) => {
     if ((options.handlerCommand === undefined) !== (options.handlerArg.length === 0))

package/dist/inbox/controller.d.ts

@@ -10,6 +10,9 @@ export interface InboxControllerOptions {
     startDeckBrowser?: typeof startWebServer;
     openBrowser?: (url: string) => void;
     visualProvider?: VisualProvider;
+    /** Pane underneath a tmux popup. Enables a registered focus handler to
+     * reveal the host surface that created the selected ticket. */
+    targetPane?: string;
 }
 type Screen = 'list' | 'detail';
 /** One terminal owner for scanning, stable selection, claims, and frame diffs. */
@@ -33,12 +36,10 @@ export declare class InboxController {
     private deckBrowserFinalizing;
     private deckBrowserStarting;
     private deckBrowserStartingGeneration;
+    private focusingSource;
     /** Invalidates an in-flight asynchronous browser start when ownership ends. */
     private deckBrowserGeneration;
     private claim;
-    private reconciling;
-    private visualReconciling;
-    private readonly visualCleanupExecutor;
     private suspended;
     private submittingDir;
     private stdinListener;
@@ -91,11 +92,6 @@ export declare class InboxController {
     /** Retake the TTY after the child exits and force a full repaint. */
     private resumeAfterChild;
     private resolvedRoots;
-    /** Owner-boundary reconciliation for resolved results still lacking an ack.
-     *  Guarded so overlapping fs events cannot stack concurrent scans. */
-    private reconcileRoots;
-    /** Reconciliation owns stale-claim retirement and durable cleanup, never a Visual start. */
-    private reconcileVisualWork;
     /** Automatic ticket capability is deliberately marker + current-root-handler only. */
     private visualProviderFor;
     private startTicketVisual;
@@ -104,6 +100,11 @@ export declare class InboxController {
     private scrollPreview;
     private detailSize;
     private detailLines;
+    private focusAvailable;
+    /** Ask the registered host to reveal this ticket's source beside the pane
+     * underneath the popup. The popup closes only after the host acknowledges
+     * that focus succeeded, so a failure remains visible as status. */
+    private focusSelectedSource;
     private passiveDetailLines;
     private previewViewport;
     private withStatus;

package/dist/inbox/controller.js

@@ -1,5 +1,5 @@
 import { readFileSync, watch } from 'node:fs';
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
 import { getTerminalSize, parseKeypress, restoreTerminal, setupTerminal } from '../tui/terminal.js';
 import { diffFrame } from '../tui/render.js';
 import { renderMarkdown } from '../render/termrender.js';
@@ -10,72 +10,17 @@ import { BOLD, CYAN, DIM, GRAY, RESET, YELLOW, clipLine } from '../tui/ansi.js';
 import { buildInboxLines } from './tui.js';
 import { inboxLayout } from './layout.js';
 import { scanInbox } from './scan.js';
-import { inboxRootsDirectory, listInboxRoots, registeredInboxRoot } from './registry.js';
+import { inboxActivityPath, inboxRootsDirectory, inboxStateDirectory, listInboxRoots, registeredInboxRoot } from './registry.js';
 import { claimTicket, heartbeatClaim, releaseClaim } from './claim.js';
 import { completeDeck, readTicketResult, ticketRoot } from './tickets.js';
-import { reconcileCompletions } from './completion.js';
-import { clearProgress, deckPath, progressPath, readJson, responsePath, reviewPath, visualsDir } from './convention.js';
+import { clearProgress, deckPath, progressPath, readJson, responsePath, reviewPath, runHandler, visualsDir } from './convention.js';
 import { DeckAdapter } from './deck-adapter.js';
 import { validateDeck } from './deck-schema.js';
 import { ReviewAdapter } from './review-adapter.js';
 import { editBufferInEditor } from '../editor/roundtrip.js';
 import { cancelFollowUp, readFollowUp, requestFollowUp } from './followup.js';
-import { cancelVisualRequest, dispatchVisualCleanup, listVisualCleanupObligationsForRoot, readVisualResult, reconcileStaleVisualRequestsForRoot, reconcileVisualRequestsForTicket, startVisualRequest, VISUAL_CAPABILITY, } from './visual.js';
-/** One controller-owned retry loop for durable cancellation only. */
-class VisualCleanupExecutor {
-    roots;
-    timer;
-    dispatching = new Set();
-    stopped = false;
-    constructor(roots) {
-        this.roots = roots;
-    }
-    reconcile() {
-        if (this.stopped)
-            return;
-        let tasks = [];
-        for (const root of this.roots()) {
-            try {
-                tasks.push(...listVisualCleanupObligationsForRoot(root));
-            }
-            catch { /* the next root reconciliation retries durable work */ }
-        }
-        tasks = tasks.filter((task) => !this.dispatching.has(this.key(task)));
-        const now = Date.now();
-        for (const task of tasks.filter((candidate) => Date.parse(candidate.nextAttemptAt) <= now))
-            this.dispatch(task);
-        this.arm(tasks.filter((task) => !this.dispatching.has(this.key(task))));
-    }
-    stop() {
-        this.stopped = true;
-        if (this.timer !== undefined)
-            clearTimeout(this.timer);
-        this.timer = undefined;
-    }
-    dispatch(task) {
-        const key = this.key(task);
-        if (this.dispatching.has(key))
-            return;
-        this.dispatching.add(key);
-        void dispatchVisualCleanup(task.root, task.dir, task.requestId).catch(() => undefined).finally(() => {
-            this.dispatching.delete(key);
-            this.reconcile();
-        });
-    }
-    arm(tasks) {
-        if (this.timer !== undefined)
-            clearTimeout(this.timer);
-        this.timer = undefined;
-        const earliest = tasks.reduce((next, task) => {
-            const due = Date.parse(task.nextAttemptAt);
-            return Number.isFinite(due) && (next === undefined || due < next) ? due : next;
-        }, undefined);
-        if (earliest === undefined)
-            return;
-        this.timer = setTimeout(() => { this.timer = undefined; this.reconcile(); }, Math.max(0, earliest - Date.now()));
-    }
-    key(task) { return `${task.root}\u0000${task.dir}\u0000${task.requestId}`; }
-}
+import { cancelVisualRequest, readVisualResult, reconcileVisualRequestsForTicket, startVisualRequest, VISUAL_CAPABILITY, } from './visual.js';
+import { kickInboxMaintenance } from './maintenance.js';
 /** One terminal owner for scanning, stable selection, claims, and frame diffs. */
 export class InboxController {
     options;
@@ -97,12 +42,10 @@ export class InboxController {
     deckBrowserFinalizing;
     deckBrowserStarting = false;
     deckBrowserStartingGeneration;
+    focusingSource = false;
     /** Invalidates an in-flight asynchronous browser start when ownership ends. */
     deckBrowserGeneration = 0;
     claim;
-    reconciling = false;
-    visualReconciling = false;
-    visualCleanupExecutor;
     suspended = false;
     submittingDir;
     stdinListener;
@@ -122,9 +65,7 @@ export class InboxController {
         const size = getTerminalSize();
         this.cols = options.cols ?? size.cols;
         this.rows = options.rows ?? size.rows;
-        this.visualCleanupExecutor = new VisualCleanupExecutor(() => this.resolvedRoots());
         this.rescan();
-        this.reconcileVisualWork();
     }
     snapshot() {
         return { items: [...this.items], selectedDir: this.selectedDir, screen: this.screen, inputBuffer: this.adapter?.inputBuffer() };
@@ -213,6 +154,10 @@ export class InboxController {
             return;
         }
         if (this.screen === 'detail' && this.adapter !== undefined) {
+            if ((input === 'g' || input === 'G') && this.adapter.canAcceptHostKeys()) {
+                void this.focusSelectedSource();
+                return;
+            }
             if ((input === 'w' || input === 'W') && this.adapter.canAcceptHostKeys()) {
                 void this.openDeckBrowser();
                 return;
@@ -236,6 +181,8 @@ export class InboxController {
             this.select(this.selectedIndex + 1);
         else if (input === 'k' || key.upArrow)
             this.select(this.selectedIndex - 1);
+        else if (input === 'g' || input === 'G')
+            void this.focusSelectedSource();
         else if (key.return || input === 'a')
             this.activate();
         this.repaint();
@@ -268,7 +215,7 @@ export class InboxController {
             // A newly acquired claim makes every older running generation stale
             // before the panel can mint its own work. This only dispatches cleanup.
             const retirement = reconcileVisualRequestsForTicket(root, item.dir, claim.token);
-            void retirement.delivery.finally(() => this.visualCleanupExecutor.reconcile());
+            void retirement.delivery.finally(kickInboxMaintenance);
         }
         // Notifications use the same canonical deck panel as every other deck:
         // opening is not acknowledgement; panel completion is.
@@ -331,7 +278,6 @@ export class InboxController {
             else {
                 this.resumeAfterChild();
                 this.rescan();
-                this.reconcileRoots();
                 this.repaint(true);
             }
         }
@@ -486,7 +432,6 @@ export class InboxController {
         if (this.claim?.dir === dir)
             this.leaveDetail();
         this.rescan();
-        this.reconcileRoots();
         this.repaint();
     }
     /** Return browser authority to the terminal deck without changing its draft. */
@@ -530,7 +475,6 @@ export class InboxController {
         this.deckBrowser = undefined;
         void browser?.stop();
         this.leaveDetail();
-        this.visualCleanupExecutor.stop();
         for (const watcher of this.watchers)
             watcher.close();
         this.watchers = [];
@@ -542,10 +486,9 @@ export class InboxController {
         setupTerminal();
         this.running = true;
         this.watchRoots();
-        // Close the crash window between an earlier result publication and its
-        // handler launch: dispatch every resolved-but-undelivered ticket now.
-        this.reconcileRoots();
         this.repaint(true);
+        // Crash repair is durable but never part of a human keystroke.
+        kickInboxMaintenance();
         const heartbeat = setInterval(() => {
             if (this.claim !== undefined)
                 heartbeatClaim(this.claim.dir, this.claim.token);
@@ -594,7 +537,6 @@ export class InboxController {
         this.submittingDir = undefined;
         this.leaveDetail(false);
         this.rescan();
-        this.reconcileRoots();
         this.repaint();
     }
     /** The controller owns the terminal handoff and repaint around $EDITOR. */
@@ -636,52 +578,6 @@ export class InboxController {
     resolvedRoots() {
         return this.options.roots ?? listInboxRoots().filter((root) => root.available).map((root) => root.root);
     }
-    /** Owner-boundary reconciliation for resolved results still lacking an ack.
-     *  Guarded so overlapping fs events cannot stack concurrent scans. */
-    reconcileRoots() {
-        if (this.reconciling)
-            return;
-        this.reconciling = true;
-        const roots = this.resolvedRoots();
-        void (async () => {
-            try {
-                for (const root of roots) {
-                    try {
-                        await reconcileCompletions(root);
-                    }
-                    catch { /* undelivered stays for the next pass */ }
-                }
-            }
-            finally {
-                this.reconciling = false;
-            }
-        })();
-        this.reconcileVisualWork();
-    }
-    /** Reconciliation owns stale-claim retirement and durable cleanup, never a Visual start. */
-    reconcileVisualWork() {
-        if (this.visualReconciling)
-            return;
-        this.visualReconciling = true;
-        const roots = this.resolvedRoots();
-        void (async () => {
-            try {
-                const deliveries = roots.flatMap((root) => {
-                    try {
-                        return reconcileStaleVisualRequestsForRoot(root).map((entry) => entry.delivery);
-                    }
-                    catch {
-                        return [];
-                    }
-                });
-                await Promise.all(deliveries);
-            }
-            finally {
-                this.visualReconciling = false;
-                this.visualCleanupExecutor.reconcile();
-            }
-        })();
-    }
     /** Automatic ticket capability is deliberately marker + current-root-handler only. */
     visualProviderFor(dir, deck, claimToken) {
         // An inline provider is intentional host injection, independent of ticket capability.
@@ -744,7 +640,7 @@ export class InboxController {
             cancel: () => {
                 watcher?.close();
                 watcher = undefined;
-                void cancelVisualRequest(root, dir, request.requestId).finally(() => this.visualCleanupExecutor.reconcile());
+                void cancelVisualRequest(root, dir, request.requestId).finally(kickInboxMaintenance);
             },
         };
     }
@@ -755,7 +651,6 @@ export class InboxController {
         this.deckBrowserStarting = false;
         this.adapter?.close();
         this.adapter = undefined;
-        this.visualCleanupExecutor.reconcile();
         this.activeDeck = undefined;
         this.selectedWatcher?.close();
         this.selectedWatcher = undefined;
@@ -790,11 +685,42 @@ export class InboxController {
         const selected = this.items[this.selectedIndex];
         if (selected === undefined)
             return this.previewViewport(this.passiveDetailLines(width), width, rows);
+        const focusHint = this.focusAvailable(selected.dir) ? `  ${DIM}g${RESET} chat` : '';
         const footer = selected.kind === 'deck'
-            ? [`  ${DIM}Enter${RESET} opens the full ticket  ${DIM}u/d${RESET} scroll  ${DIM}j/k${RESET} select`, `  ${DIM}Active ask:${RESET} c comment  u/d scroll  w browser  ${DIM}q${RESET} close`]
-            : [`  ${DIM}Enter${RESET} opens the full review  ${DIM}u/d${RESET} scroll  ${DIM}j/k${RESET} select`, `  ${DIM}q${RESET} close`];
+            ? [`  ${DIM}Enter${RESET} opens the full ticket  ${DIM}u/d${RESET} scroll  ${DIM}j/k${RESET} select`, `  ${DIM}Active ask:${RESET} c comment  u/d scroll  w browser${focusHint}  ${DIM}q${RESET} close`]
+            : [`  ${DIM}Enter${RESET} opens the full review  ${DIM}u/d${RESET} scroll  ${DIM}j/k${RESET} select`, ` ${focusHint}  ${DIM}q${RESET} close`];
         return [...this.previewViewport(this.passiveDetailLines(width), width, Math.max(0, rows - footer.length)), ...footer.map((line) => clipLine(line, width))];
     }
+    focusAvailable(dir) {
+        const root = ticketRoot(dir);
+        return this.options.targetPane !== undefined && root !== null && registeredInboxRoot(root)?.focusHandler !== undefined;
+    }
+    /** Ask the registered host to reveal this ticket's source beside the pane
+     * underneath the popup. The popup closes only after the host acknowledges
+     * that focus succeeded, so a failure remains visible as status. */
+    async focusSelectedSource() {
+        const item = this.items[this.selectedIndex];
+        const targetPane = this.options.targetPane;
+        if (item === undefined || targetPane === undefined || this.focusingSource)
+            return;
+        const root = ticketRoot(item.dir);
+        const registration = root === null ? null : registeredInboxRoot(root);
+        if (root === null || registration?.focusHandler === undefined)
+            return;
+        const event = { schema: 'humanloop.focus/v1', root, dir: item.dir, ticketId: item.id, targetPane };
+        this.focusingSource = true;
+        try {
+            await runHandler(registration.focusHandler.command, registration.focusHandler.args, event);
+            this.close();
+        }
+        catch (error) {
+            this.status = error instanceof Error ? error.message : String(error);
+            this.repaint();
+        }
+        finally {
+            this.focusingSource = false;
+        }
+    }
     passiveDetailLines(width) {
         const selected = this.items[this.selectedIndex];
         if (selected === undefined)
@@ -888,15 +814,21 @@ export class InboxController {
         this.frame = diff.nextPrevFrame;
     }
     watchRoots() {
-        for (const root of this.resolvedRoots()) {
-            try {
-                this.watchers.push(watch(root, () => { this.invalidate(); this.reconcileRoots(); }));
-            }
-            catch { /* unavailable roots remain discoverable through later rescans */ }
+        // A single state-level activity marker replaces one watcher per historical
+        // root. Closing hundreds of fs watchers was itself a multi-second UI path.
+        const activity = basename(inboxActivityPath());
+        try {
+            this.watchers.push(watch(inboxStateDirectory(), (_event, file) => {
+                if (String(file) === activity) {
+                    this.invalidate();
+                    kickInboxMaintenance();
+                }
+            }));
         }
+        catch { /* the state directory appears when the next ticket is submitted */ }
         if (this.options.roots === undefined) {
             try {
-                this.watchers.push(watch(inboxRootsDirectory(), () => this.invalidate()));
+                this.watchers.push(watch(inboxRootsDirectory(), () => { this.invalidate(); kickInboxMaintenance(); }));
             }
             catch { /* registry appears after the next explicit open */ }
         }

package/dist/inbox/deck-factories.js

@@ -2,6 +2,7 @@ import { validateDeck } from './deck-schema.js';
 /** Build a validated single-option notify deck. id: 'notify', kind: 'notify'. */
 export function notifyDeck(title, opts = {}) {
     return validateDeck({
+        title,
         interactions: [{
                 id: 'notify',
                 title,

package/dist/inbox/deck-schema.d.ts

@@ -12,7 +12,7 @@ export declare const preAnswerSchema: z.ZodObject<{
     label: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const deckSchema: z.ZodObject<{
-    title: z.ZodOptional<z.ZodString>;
+    title: z.ZodString;
     source: z.ZodOptional<z.ZodObject<{
         sessionName: z.ZodOptional<z.ZodString>;
         askedBy: z.ZodOptional<z.ZodString>;

package/dist/inbox/deck-schema.js

@@ -8,11 +8,11 @@ export const interactionOptionSchema = z.object({ id: z.string().min(1), label:
 export const preAnswerSchema = z.object({ selectedOptionId: z.string().optional(), selectedOptionIds: z.array(z.string()).optional(), freetext: z.string().optional(), label: z.string().optional() });
 const interactionSchema = z.object({
     id: z.string().regex(/^[A-Za-z0-9_-]+$/, { error: 'interaction id must match /^[A-Za-z0-9_-]+$/' }).min(1).max(64),
-    title: z.string().min(1), subtitle: z.string().min(1).optional(), body: z.string().optional(), bodyPath: z.string().optional(),
+    title: z.string().trim().min(1), subtitle: z.string().min(1).optional(), body: z.string().optional(), bodyPath: z.string().optional(),
     options: z.array(interactionOptionSchema), multiSelect: z.boolean().optional(), allowFreetext: z.boolean().optional(), freetextLabel: z.string().optional(), kind: z.enum(INTERACTION_KINDS).optional(), preAnswered: preAnswerSchema.optional(),
 });
 const deckSourceSchema = z.object({ sessionName: z.string().optional(), askedBy: z.string().optional(), blockedSince: z.string().optional(), nodeId: z.string().optional(), visual: z.literal('humanloop.visual/v1').optional() });
-export const deckSchema = z.object({ title: z.string().optional(), source: deckSourceSchema.optional(), interactions: z.array(interactionSchema).min(1) }).superRefine((input, ctx) => {
+export const deckSchema = z.object({ title: z.string().trim().min(1), source: deckSourceSchema.optional(), interactions: z.array(interactionSchema).min(1) }).superRefine((input, ctx) => {
     const seen = new Set();
     input.interactions.forEach((interaction, index) => {
         if (interaction.body !== undefined && interaction.bodyPath !== undefined)

package/dist/inbox/maintenance.d.ts

@@ -0,0 +1,4 @@
+/** Start one detached repair pass. The lease makes repeated UI gestures free. */
+export declare function kickInboxMaintenance(): void;
+/** Run repair and stay alive only until the durable cleanup retry queue is empty. */
+export declare function runInboxMaintenance(lease: string): Promise<void>;

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

@@ -10,6 +10,7 @@ export interface InboxRootRegistration {
     handler?: CompletionHandler;
     followUpHandler?: CompletionHandler;
     visualHandler?: CompletionHandler;
+    focusHandler?: CompletionHandler;
 }
 export interface InboxRootStatus extends InboxRootRegistration {
     available: boolean;
@@ -20,8 +21,13 @@ export interface RegisterInboxRootOptions {
     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);
@@ -31,6 +41,7 @@ function validateRegistration(raw) {
             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 {
@@ -51,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), visualHandler: validateHandler(opts.visualHandler) };
+        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/scan.js

@@ -32,7 +32,7 @@ function deckSummary(dir, id) {
             return null;
         }
     }
-    return { dir, id, kind: 'deck', title: deck.title ?? first.title, subtitle: first.subtitle, interactionKind: first.kind, source: deck.source ?? {}, blockedSince, claim: claimSummary(dir) };
+    return { dir, id, kind: 'deck', title: deck.title, subtitle: first.subtitle, interactionKind: first.kind, source: deck.source ?? {}, blockedSince, claim: claimSummary(dir) };
 }
 function reviewSummary(dir, id) {
     const raw = readJson(reviewPath(dir));