@crouton-kit/humanloop 0.4.0 → 0.4.1

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/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/tickets.js

@@ -4,10 +4,11 @@ import { z } from 'zod';
 import { buildSummary } from '../summary.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();
@@ -105,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) {
@@ -124,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) {
@@ -170,23 +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);
+        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);
@@ -197,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/index.d.ts

@@ -24,5 +24,5 @@ export { notifyDeck } from './inbox/deck-factories.js';
 export type { NotifyDeckOpts } from './inbox/deck-factories.js';
 export { deckPath, reviewPath, responsePath, progressPath, visualsDir, interactionState, isResolved, isClaimed, atomicWriteJson, readJson, writeResponse, writeProgress, clearProgress, } from './inbox/convention.js';
 export type { InteractionState } from './inbox/convention.js';
-export type { Interaction, InteractionOption, InteractionResponse, InteractionKind, Deck, DeckSource, CanonicalInteractionOption, CanonicalInteraction, MountedPanel, MountedPanelOpts, VisualProvider, VisualRequest, VisualHandle, VisualResult, VisualBlock, FollowUpState, FeedbackComment, FeedbackResult, ResolutionEnvelope, InboxItem, DisplayOpts, ClaimSummary, TicketSummary, DeckTicketSummary, ReviewTicketSummary, ReviewDescriptor, DeckTicketResult, ReviewTicketResult, CanceledTicketResult, TicketResult, CompletionEvent, } from './types.js';
+export type { Interaction, InteractionOption, InteractionResponse, InteractionKind, Deck, DeckSource, CanonicalInteractionOption, CanonicalInteraction, MountedPanel, MountedPanelOpts, VisualProvider, VisualRequest, VisualHandle, VisualResult, VisualBlock, FollowUpState, FeedbackComment, FeedbackResult, ResolutionEnvelope, InboxItem, DisplayOpts, ClaimSummary, TicketSummary, DeckTicketSummary, ReviewTicketSummary, ReviewDescriptor, DeckTicketResult, ReviewTicketResult, CanceledTicketResult, TicketResult, CompletionEvent, FocusEvent, } from './types.js';
 export type { Key } from './tui/terminal.js';

package/dist/surfaces/inbox-popup.d.ts

@@ -1,2 +1,2 @@
 /** Run the inbox controller in a popup-owned TTY and accept graceful close requests. */
-export declare function openInboxPopup(controlSocket?: string, roots?: string[]): Promise<void>;
+export declare function openInboxPopup(controlSocket?: string, roots?: string[], targetPane?: string): Promise<void>;

package/dist/surfaces/inbox-popup.js

@@ -2,8 +2,8 @@ import { createServer } from 'node:net';
 import { rmSync } from 'node:fs';
 import { InboxController } from '../inbox/controller.js';
 /** Run the inbox controller in a popup-owned TTY and accept graceful close requests. */
-export async function openInboxPopup(controlSocket, roots) {
-    const controller = new InboxController({ roots });
+export async function openInboxPopup(controlSocket, roots, targetPane) {
+    const controller = new InboxController({ roots, targetPane });
     const server = controlSocket === undefined ? undefined : createServer((connection) => {
         connection.once('data', (data) => {
             if (data.toString('utf8').trim() === 'close')

package/dist/tui/tmux.js

@@ -87,7 +87,8 @@ export async function toggleInboxPopup(target) {
         }
         if (existsSync(paths.controlSocket))
             rmSync(paths.controlSocket, { force: true });
-        const command = `${quote(process.execPath)} ${quote(fileURLToPath(new URL('../cli.js', import.meta.url)))} inbox open --control-socket ${quote(paths.controlSocket)}`;
+        const targetPaneArg = resolved.targetPane === undefined ? '' : ` --target-pane ${quote(resolved.targetPane)}`;
+        const command = `${quote(process.execPath)} ${quote(fileURLToPath(new URL('../cli.js', import.meta.url)))} inbox open --control-socket ${quote(paths.controlSocket)}${targetPaneArg}`;
         const result = await launchPopup(socket, resolved, paths.controlSocket, command);
         logPopupEvent('toggle.completed', { ...resolved, controlSocket: paths.controlSocket, result });
         return result;

package/dist/types.d.ts

@@ -247,6 +247,16 @@ export interface CompletionEvent {
     outcome: 'resolved' | 'canceled';
     responsePath: string;
 }
+/** A popup request to reveal the host surface that created a ticket. The root's
+ * trusted focus handler decides what that means; humanloop only supplies the
+ * selected ticket and the tmux pane underneath the popup. */
+export interface FocusEvent {
+    schema: 'humanloop.focus/v1';
+    root: string;
+    dir: string;
+    ticketId: string;
+    targetPane: string;
+}
 /** Options for `display()` — the live-watch tmux pane surface. The pane always
  *  watches the file and live-updates on edits; there is no non-watched mode. */
 export interface DisplayOpts {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/humanloop",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Human-in-the-loop decision TUI — agents write questions, humans answer them",
   "engines": {
     "node": ">=22.19.0"
@@ -44,6 +44,7 @@
   "devDependencies": {
     "@types/node": "^22.0.0",
     "@types/ws": "^8.18.1",
+    "esbuild": "^0.27.7",
     "tsx": "^4.0.0",
     "typescript": "^5.7.0"
   }