@north-light/api 0.3.580 → 0.3.587

package/dist/clients/attach/session/layout.js

@@ -0,0 +1,59 @@
+// session/layout.ts — the viewer's visual skeleton: its containers, editor,
+// and one full-pane frame.
+//
+// Pure construction. Nothing here reads session state, talks to the socket, or
+// handles a key — a reader chasing behavior can skip this file entirely, and a
+// reader asking "where does this line get painted?" needs only this one.
+//
+// The render order is asserted in ONE place (`ViewerFrame`'s bottom list).
+// Top to bottom: pinned recap header · inline ticket page · virtualized chat ·
+// cockpit padding · fixed activity · above-editor extension widgets · queued ·
+// editor · picker panel · below-editor extension widgets · roster · search bar ·
+// status bar. The frame owns the pane rectangle,
+// so every region remains on screen and none can enter terminal scrollback.
+import { Container, Spacer } from '@earendil-works/pi-tui';
+import { getSelectListTheme } from '@earendil-works/pi-coding-agent';
+import { TitledEditor } from '../input/titled-editor.js';
+import { ViewerFrame } from './frame.js';
+/** Build the layout around the transcript viewport. The viewer creates the
+ * terminal and chat first because the viewport measures that chat source. */
+export function createLayout(procTerminal, tui, chat, activity, pal, km, viewport, searchBar) {
+    const containers = {
+        chat,
+        header: new Container(),
+        aboveWidgets: new Container(),
+        activity,
+        reports: new Container(),
+        queued: new Container(),
+        pickerPanel: new Container(),
+        ticketPanel: new Container(),
+        belowWidgets: new Container(),
+        footer: new Container(),
+    };
+    const editorTheme = { borderColor: pal.border, selectList: getSelectListTheme() };
+    // TitledEditor paints the session name into its top border (solid-background
+    // chip) and tracks a thinking-level border color, both set from live state.
+    const editor = new TitledEditor(tui, editorTheme, km, { paddingX: 1 });
+    const frame = new ViewerFrame(procTerminal, {
+        header: containers.header,
+        ticket: containers.ticketPanel,
+        viewport,
+        bottom: [
+            { slot: 'cockpitPadding', component: new Spacer(1) },
+            { slot: 'activity', component: containers.activity },
+            { slot: 'aboveWidgets', component: containers.aboveWidgets },
+            { slot: 'queued', component: containers.queued },
+            { slot: 'editor', component: editor },
+            { slot: 'pickerPanel', component: containers.pickerPanel },
+            { slot: 'belowWidgets', component: containers.belowWidgets },
+            { slot: 'reports', component: containers.reports },
+            { slot: 'search', component: searchBar },
+            { slot: 'footer', component: containers.footer },
+        ],
+    });
+    const mount = () => {
+        tui.addChild(frame);
+        tui.setFocus(editor);
+    };
+    return { procTerminal, tui, containers, editor, frame, mount };
+}

package/dist/clients/attach/session/mouse.d.ts

@@ -0,0 +1,27 @@
+import type { TUI } from '@earendil-works/pi-tui';
+import type { MouseModeDefault } from '../../../types.js';
+/** Lines moved for one terminal wheel notch. */
+export declare const WHEEL_LINES = 3;
+export interface MouseReporting {
+    /** Reporting currently on. */
+    enabled(): boolean;
+    /** Flip, write the DECSET/DECRST, return the new state. */
+    toggle(): boolean;
+    /** Re-emit the current setting after another terminal program returned. */
+    reassert(): void;
+    /** Turn off unconditionally — teardown and process exit. */
+    disable(): void;
+    /** Install the SGR listener; returns the remover. */
+    install(tui: TUI, handlers: MouseHandlers): () => void;
+}
+export interface MouseHandlers {
+    onWheel(direction: 'up' | 'down', lines: number, column: number): void;
+    /** A primary-button press with no Shift, Alt, or Control modifier. */
+    onPrimaryPress(column: number, row: number): void;
+    /** Pointer motion with the primary button held. */
+    onPrimaryDrag(column: number, row: number): void;
+    /** The primary button came back up, wherever the pointer ended. */
+    onPrimaryRelease(column: number, row: number): void;
+}
+/** Create per-viewer mouse reporting from the user's saved starting mode. */
+export declare function createMouseReporting(write: (data: string) => void, defaultMode: MouseModeDefault): MouseReporting;

package/dist/clients/attach/session/mouse.js

@@ -0,0 +1,78 @@
+// session/mouse.ts — terminal mouse reporting for the attach viewport.
+//
+// Mouse reporting starts from the user's configured default. Follow-tmux mode
+// leaves native terminal selection alone when tmux mouse is off; inside a
+// reporting viewer, every mouse sequence is consumed so clicks and drags can
+// never become editor input — which is why the viewer, not the terminal, owns
+// drag-select while reporting is on (session/selection.ts).
+//
+// Mode 1002 is button-event tracking: press, motion while a button is held, and
+// release. Those three are exactly the gesture parts a selection needs, so the
+// drag is reconstructed here and reported as press · drag · release.
+import { spawnSync } from 'node:child_process';
+import { inTmux } from '../../../core/runtime/placement-tmux.js';
+const MOUSE_REPORTING_ON = '\x1b[?1002h\x1b[?1006h';
+const MOUSE_REPORTING_OFF = '\x1b[?1002l\x1b[?1006l';
+/** Lines moved for one terminal wheel notch. */
+export const WHEEL_LINES = 3;
+function detectMouseDefault() {
+    if (!inTmux())
+        return false;
+    const result = spawnSync('tmux', ['show-options', '-gv', 'mouse'], { encoding: 'utf8' });
+    return result.status === 0 && result.stdout?.trim() === 'on';
+}
+/** Create per-viewer mouse reporting from the user's saved starting mode. */
+export function createMouseReporting(write, defaultMode) {
+    let isEnabled = defaultMode === 'on' || (defaultMode === 'tmux' && detectMouseDefault());
+    const reassert = () => {
+        write(isEnabled ? MOUSE_REPORTING_ON : MOUSE_REPORTING_OFF);
+    };
+    const disable = () => {
+        isEnabled = false;
+        try {
+            write(MOUSE_REPORTING_OFF);
+        }
+        catch {
+            // Terminal restoration is best-effort, including during process exit.
+        }
+    };
+    process.once('exit', disable);
+    return {
+        enabled: () => isEnabled,
+        toggle: () => {
+            isEnabled = !isEnabled;
+            reassert();
+            return isEnabled;
+        },
+        reassert,
+        disable,
+        install: (tui, handlers) => tui.addInputListener((data) => {
+            let consumed = false;
+            const withoutSgr = data.replace(/\x1b\[<(\d+);(\d+);(\d+)([Mm])/g, (_match, buttons, column, row, action) => {
+                consumed = true;
+                const code = Number(buttons);
+                // Bits 4/8/16 are Shift/Meta/Control; bit 32 is the motion flag, which
+                // must survive the mask so a drag is distinguishable from a press.
+                const button = code & ~(4 | 8 | 16);
+                if (button === 64)
+                    handlers.onWheel('up', WHEEL_LINES, Number(column));
+                else if (button === 65)
+                    handlers.onWheel('down', WHEEL_LINES, Number(column));
+                else if (button === 32 && action === 'M')
+                    handlers.onPrimaryDrag(Number(column), Number(row));
+                else if (button === 0 && action === 'm')
+                    handlers.onPrimaryRelease(Number(column), Number(row));
+                else if (code === 0 && action === 'M')
+                    handlers.onPrimaryPress(Number(column), Number(row));
+                return '';
+            });
+            const withoutMouse = withoutSgr.replace(/\x1b\[M[\s\S]{3}/g, () => {
+                consumed = true;
+                return '';
+            });
+            if (!consumed)
+                return undefined;
+            return withoutMouse.length > 0 ? { data: withoutMouse } : { consume: true };
+        }),
+    };
+}

package/dist/clients/attach/session/pane-focus.d.ts

@@ -0,0 +1,8 @@
+import type { TitledEditor } from '../input/titled-editor.js';
+export interface PaneFocus {
+    /** Recompute the editor's cursor style from pane focus + the holders. */
+    sync(): void;
+    /** Report real tmux-pane focus (DECSET 1004). Repaints the editor cursor. */
+    setPaneFocused(focused: boolean): void;
+}
+export declare function createPaneFocus(editor: TitledEditor, holders: ReadonlyArray<() => boolean>): PaneFocus;

package/dist/clients/attach/session/pane-focus.js

@@ -0,0 +1,42 @@
+// session/pane-focus.ts — the ONE owner of the editor's hollow-cursor state.
+//
+// The cursor is dimmed whenever the tmux pane is blurred OR any chrome list
+// (the below-editor roster, the top-of-pane inbox strip) holds the highlight:
+// while a list is scrolled the editor is "away", so it must read exactly like
+// an unfocused pane. Both lists report their active state through `holders`;
+// they call `sync()` whenever that state may have flipped, and the viewer
+// feeds real tmux focus (DECSET 1004) in through `setPaneFocused`.
+import { execFileSync } from 'node:child_process';
+/** Seed pane focus from the pane's REAL active state, not an unconditional
+ *  `true`. tmux only emits DECSET 1004 focus events on a TRANSITION, so a viewer
+ *  spawned into a non-active pane (a `split -d` beside another node — the
+ *  auto-viewer for a background child) starts unfocused and NEVER receives a
+ *  FOCUS_OUT, leaving a solid cursor drawn until the user swaps in and back out.
+ *  Query `#{pane_active}` for our own pane once at startup so an unfocused split
+ *  renders hollow immediately; default true when not in tmux or the query fails. */
+function initialPaneActive() {
+    const pane = process.env['TMUX_PANE'];
+    if (pane === undefined || pane === '')
+        return true;
+    try {
+        const out = execFileSync('tmux', ['display-message', '-p', '-t', pane, '#{pane_active}'], { encoding: 'utf8' }).trim();
+        return out !== '0';
+    }
+    catch {
+        return true;
+    }
+}
+export function createPaneFocus(editor, holders) {
+    let paneFocused = initialPaneActive();
+    const sync = () => {
+        editor.paneFocused = paneFocused && !holders.some((holds) => holds());
+    };
+    sync();
+    return {
+        sync,
+        setPaneFocused: (focused) => {
+            paneFocused = focused;
+            sync();
+        },
+    };
+}

package/dist/clients/attach/session/pane-tag.d.ts

@@ -0,0 +1,44 @@
+/** The tag's lifecycle for one viewer: `set()` once the startup checkpoint has
+ *  cleared, `clear()` on teardown so a stray tag can't outlive the pane.
+ *  `pane()` is the id teardown reports as this viewer's home.
+ *
+ *  Split into a claim + a clear because ordering matters: a remote relay's "no
+ *  node"/"no running broker" close can still throw AFTER the socket is up, so
+ *  the tag is claimed only past that checkpoint — while `clear()` must be safe
+ *  to call from a teardown that runs before it was ever claimed.
+ *
+ *  `clear()` also has to survive a SUCCESSOR already owning the pane. tmux
+ *  `respawn-pane -k` only SIGHUPs the old viewer — it does not wait for it, and
+ *  the replacement is running ~50ms later. A departing viewer whose event loop
+ *  was busy when the signal arrived therefore runs its teardown after the
+ *  replacement has claimed the pane, and an unconditional clear then wipes the
+ *  LIVE viewer's identity: `nodeInPane()` returns nothing, so `surface reload`
+ *  and viewer focus refuse the pane until someone re-tags it by hand. So the
+ *  clear is conditional on still owning the pane, decided by `@crtr_viewer_pid`:
+ *  a pane carrying someone else's pid has a successor, and its tags are not
+ *  ours to remove. Skipping leaves at worst a stale tag on a dead pane, which
+ *  `liveViewerPanes` and `surface reload` already validate against the live
+ *  process; wiping a live viewer's tag has no such defense. */
+/** The tmux reads and writes the tag lifecycle makes, injectable so the
+ *  successor race is testable without a live tmux server. */
+export interface PaneTagIo {
+    readOption: (pane: string, name: string) => string | undefined;
+    writeOption: (pane: string, name: string, value: string) => void;
+    stampAsync: (pane: string) => void;
+    currentPane: () => string | undefined;
+    /** This viewer process's identity — the pid, unique per viewer by construction. */
+    ownerId: () => string;
+}
+export declare function createPaneTag(remote: boolean, nodeId: string, io?: PaneTagIo): {
+    set: () => void;
+    stamp: () => void;
+    clear: () => void;
+    pane: () => string | undefined;
+};
+/** Which viewer process owns this pane's tags. Read only by `clear()`, so a
+ *  departing viewer never removes a successor's identity. */
+export declare const VIEWER_OWNER_OPTION = "@crtr_viewer_pid";
+export declare function tagAttachPane(remote: boolean, pane: string | undefined, nodeId: string, setOpt?: (pane: string, name: string, value: string) => void): void;
+export declare function untagAttachPane(remote: boolean, pane: string | undefined, setOpt?: (pane: string, name: string, value: string) => void): void;
+export declare function tagAttachViewerPane(pane: string | undefined, setOpt?: (pane: string, name: string, value: string) => void): void;
+export declare function untagAttachViewerPane(pane: string | undefined, setOpt?: (pane: string, name: string, value: string) => void): void;

package/dist/clients/attach/session/pane-tag.js

@@ -0,0 +1,112 @@
+// session/pane-tag.ts — pane tags owned by an attach viewer.
+//
+// `@crtr_node` is local identity used by nodeInPane(). A remote attach never
+// sets it, so local lifecycle cannot resolve a remote node id (or a colliding
+// local id) from that pane. `@crtr_attach` carries no identity: every local or
+// remote attach viewer sets it so tmux can conditionally forward opted-in root
+// gestures into whichever attach pane currently has focus.
+import { currentTmux, getPaneOption, setPaneOption, stampViewerPaneAsync, VIEWER_STAMP_OPTION, } from '../../../core/runtime/placement-tmux.js';
+const realPaneTagIo = {
+    readOption: getPaneOption,
+    writeOption: (pane, name, value) => { setPaneOption(pane, name, value); },
+    stampAsync: stampViewerPaneAsync,
+    currentPane: () => process.env['TMUX_PANE'] ?? currentTmux()?.pane,
+    ownerId: () => String(process.pid),
+};
+export function createPaneTag(remote, nodeId, io = realPaneTagIo) {
+    let pane;
+    const ownerPid = io.ownerId();
+    /** False once another viewer's pid is on the pane. An unclaimed pane (no pid
+     *  recorded — a viewer that never reached `set()`, or one from a generation
+     *  that predates this option) keeps the old unconditional behavior. */
+    const stillOwnsPane = () => {
+        if (pane === undefined || pane === '')
+            return true;
+        const claimed = io.readOption(pane, VIEWER_OWNER_OPTION);
+        if (claimed === undefined || claimed === '')
+            return true;
+        return claimed === ownerPid;
+    };
+    return {
+        set: () => {
+            pane = io.currentPane();
+            claimAttachPane(pane, ownerPid, io.writeOption);
+            tagAttachPane(remote, pane, nodeId, io.writeOption);
+            tagAttachViewerPane(pane, io.writeOption);
+            stampAttachPane(remote, pane, io.writeOption);
+        },
+        stamp: () => {
+            if (remote || pane === undefined || pane === '')
+                return;
+            io.stampAsync(pane);
+        },
+        clear: () => {
+            if (!stillOwnsPane())
+                return;
+            untagAttachPane(remote, pane, io.writeOption);
+            untagAttachViewerPane(pane, io.writeOption);
+            unstampAttachPane(remote, pane, io.writeOption);
+            claimAttachPane(pane, '', io.writeOption);
+        },
+        pane: () => pane,
+    };
+}
+/** Which viewer process owns this pane's tags. Read only by `clear()`, so a
+ *  departing viewer never removes a successor's identity. */
+export const VIEWER_OWNER_OPTION = '@crtr_viewer_pid';
+function claimAttachPane(pane, ownerPid, setOpt) {
+    if (pane === undefined || pane === '')
+        return;
+    try {
+        setOpt(pane, VIEWER_OWNER_OPTION, ownerPid);
+    }
+    catch { /* best-effort */ }
+}
+function stampAttachPane(remote, pane, setOpt) {
+    if (remote || pane === undefined || pane === '')
+        return;
+    try {
+        setOpt(pane, VIEWER_STAMP_OPTION, String(Date.now()));
+    }
+    catch { /* best-effort */ }
+}
+function unstampAttachPane(remote, pane, setOpt = setPaneOption) {
+    if (remote || pane === undefined || pane === '')
+        return;
+    try {
+        setOpt(pane, VIEWER_STAMP_OPTION, '');
+    }
+    catch { /* best-effort */ }
+}
+export function tagAttachPane(remote, pane, nodeId, setOpt = setPaneOption) {
+    if (remote || pane === undefined || pane === '')
+        return;
+    try {
+        setOpt(pane, '@crtr_node', nodeId);
+    }
+    catch { /* best-effort */ }
+}
+export function untagAttachPane(remote, pane, setOpt = setPaneOption) {
+    if (remote || pane === undefined || pane === '')
+        return;
+    try {
+        setOpt(pane, '@crtr_node', '');
+    }
+    catch { /* best-effort */ }
+}
+export function tagAttachViewerPane(pane, setOpt = setPaneOption) {
+    if (pane === undefined || pane === '')
+        return;
+    try {
+        setOpt(pane, '@crtr_attach', '1');
+    }
+    catch { /* best-effort */ }
+}
+export function untagAttachViewerPane(pane, setOpt = setPaneOption) {
+    if (pane === undefined || pane === '')
+        return;
+    try {
+        setOpt(pane, '@crtr_attach', '');
+    }
+    catch { /* best-effort */ }
+}

package/dist/clients/attach/session/pi-assets.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/clients/attach/session/pi-assets.js

@@ -0,0 +1,24 @@
+// session/pi-assets.ts — point pi-coding-agent at its OWN package dir.
+//
+// `npm run build:attach` esbuild-bundles the viewer into crouter's dist, which
+// relocates the module URL — and that breaks pi's asset resolution: pi finds its
+// theme/asset root by walking up from its own module URL to the nearest
+// package.json (config.js getPackageDir). Inlined into the bundle, that walk
+// lands on CROUTER's package.json, where pi's themes don't exist (ENOENT on
+// dark.json the moment applyTheme runs). PI_PACKAGE_DIR is pi's documented
+// override for exactly this; point it at pi's REAL package dir — resolved with
+// import.meta.resolve, which stays correct in the bundle because it resolves
+// from the output file's node_modules. No-op unbundled (dev/tsx): pi's own walk
+// works, and this just re-asserts the same dir.
+//
+// Import this for side effect at the TOP of the viewer entry, so it precedes
+// any pi theme/asset access during viewer construction.
+import { resolveBundledPiPackageDir } from '../../../core/runtime/pi-cli.js';
+try {
+    // Replace even an inherited value: a parent viewer/daemon may carry a `.pnpm`
+    // package copy that lacks pi's JSON theme assets.
+    process.env['PI_PACKAGE_DIR'] = resolveBundledPiPackageDir();
+}
+catch {
+    /* unbundled/dev — pi resolves its assets from its own location */
+}

package/dist/clients/attach/session/pi-oauth-flows.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/clients/attach/session/pi-oauth-flows.js

@@ -0,0 +1,21 @@
+// session/pi-oauth-flows.ts — hand the bundled viewer pi's OAuth flow modules.
+//
+// Same class of bug as pi-assets.ts: esbuild relocates the module URL. pi-ai
+// 0.82 loads each OAuth flow through a VARIABLE specifier
+// (`import("./anthropic.ts")` in auth/oauth/load.js) specifically so bundlers
+// cannot follow it into Node-only flow code. Bundled, that specifier survives
+// into dist/clients/attach/viewer.js and resolves against the BUNDLE's dir, so
+// /login died on `Cannot find module .../dist/clients/attach/anthropic.js`.
+// (0.80 imported the flows statically, so the bundle carried them and login
+// worked; the 0.82 bump is what broke it.)
+//
+// registerBunOAuthFlows is pi's own escape hatch for statically bundled hosts —
+// it imports every flow module by literal specifier and registers them, so the
+// dynamic path is never taken. Named for Bun's standalone binaries, but the
+// problem it solves is bundling, not the runtime.
+//
+// Import this for side effect at the TOP of the viewer entry, before anything
+// can touch `provider.auth.oauth`. No-op-ish unbundled (dev/tsx): it registers
+// the same flows the lazy path would have loaded.
+import { registerBunOAuthFlows } from '@earendil-works/pi-ai/bun-oauth';
+registerBunOAuthFlows();

package/dist/clients/attach/session/profile-files.d.ts

@@ -0,0 +1,17 @@
+import type { NodeRow } from '../../../core/canvas/types.js';
+interface ProfileFileSearchOptions {
+    cwd: string;
+    nodeDirs: readonly string[];
+    nodes: readonly Pick<NodeRow, 'node_id' | 'grantee'>[];
+    profileId: string | null;
+    fdPath: string | null;
+    onNotice: (message: string) => void;
+}
+/** Return the ids of this node, its complete parent chain, and its full
+ *  descendant subtree. The `parent` hierarchy, rather than the subscription
+ *  graph, is the user-visible child/parent relationship. */
+export declare function relatedNodeIds(nodes: readonly Pick<NodeRow, 'node_id' | 'parent'>[], nodeId: string): string[];
+/** Return the rows of the same node family. */
+export declare function relatedNodes<T extends Pick<NodeRow, 'node_id' | 'parent'>>(nodes: readonly T[], nodeId: string): T[];
+export declare function launchProfileFileSearch(opts: ProfileFileSearchOptions): void;
+export {};

package/dist/clients/attach/session/profile-files.js

@@ -0,0 +1,207 @@
+// session/profile-files.ts — fuzzy file search across a node's working family and local profile.
+//
+// The popup searches the current workspace, every ancestor and descendant
+// node's workspace, the context directories (files) of those same nodes,
+// every project named by the node's profile manifest, and the profile's own
+// directory. fzf owns matching and selection and nvim owns viewing; the
+// attach viewer resolves the related nodes and wires the two popups.
+import { constants, accessSync, existsSync, mkdtempSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { delimiter, join, resolve, sep } from 'node:path';
+import { execFile, spawnSync } from 'node:child_process';
+import { loadProfileManifest, profileDir } from '../../../core/profiles/manifest.js';
+import { contextDir } from '../../../core/canvas/paths.js';
+import { shellQuote } from '../../../core/runtime/placement-tmux.js';
+import { nvimShellCommand } from '../../../core/nvim-launch.js';
+import { surfaceTmuxStyleArgs } from '../../../core/runtime/surface-bg.js';
+/** Return the ids of this node, its complete parent chain, and its full
+ *  descendant subtree. The `parent` hierarchy, rather than the subscription
+ *  graph, is the user-visible child/parent relationship. */
+export function relatedNodeIds(nodes, nodeId) {
+    const byId = new Map(nodes.map((node) => [node.node_id, node]));
+    const included = new Set([nodeId]);
+    for (let current = byId.get(nodeId); current?.parent !== null && current?.parent !== undefined;) {
+        const parentId = current.parent;
+        if (included.has(parentId))
+            break;
+        included.add(parentId);
+        current = byId.get(parentId);
+    }
+    const pending = [nodeId];
+    while (pending.length > 0) {
+        const parentId = pending.pop();
+        for (const child of nodes) {
+            if (child.parent !== parentId || included.has(child.node_id))
+                continue;
+            included.add(child.node_id);
+            pending.push(child.node_id);
+        }
+    }
+    return nodes.filter((node) => included.has(node.node_id)).map((node) => node.node_id);
+}
+/** Return the rows of the same node family. */
+export function relatedNodes(nodes, nodeId) {
+    const family = new Set(relatedNodeIds(nodes, nodeId));
+    return nodes.filter((node) => family.has(node.node_id));
+}
+/** Return the canvas-home directories that hold each family node's shared
+ *  files: its context dir. It lives outside every working directory, so it is
+ *  searched as a root of its own. Pushed reports are canvas documents, not files. */
+function familyDocumentDirs(nodes) {
+    const dirs = [];
+    for (const node of nodes) {
+        try {
+            dirs.push(contextDir(node.node_id, node.grantee));
+        }
+        catch {
+            continue;
+        }
+    }
+    return dedupeExistingDirs(dirs);
+}
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function executableCandidates(name, preferred) {
+    const candidates = [
+        ...(preferred === undefined || preferred === null ? [] : [preferred]),
+        ...(process.env['PATH'] ?? '').split(delimiter).filter(Boolean).map((dir) => join(dir, name)),
+    ];
+    return [...new Set(candidates)];
+}
+/** Return the first PATH candidate that can actually execute. Checking only
+ *  X_OK is insufficient when a managed tool cache contains a binary for a
+ *  different host platform. This runs only when the user opens the search. */
+function workingExecutable(name, preferred) {
+    for (const candidate of executableCandidates(name, preferred)) {
+        try {
+            accessSync(candidate, constants.X_OK);
+        }
+        catch {
+            continue;
+        }
+        const probe = spawnSync(candidate, ['--version'], { stdio: 'ignore' });
+        if (probe.status === 0)
+            return candidate;
+    }
+    return null;
+}
+function profileSearchRoots(profileId) {
+    if (profileId === null || profileId === '')
+        return { projects: [], settings: null };
+    try {
+        const { profileId: resolvedId, manifest } = loadProfileManifest(profileId);
+        return { projects: manifest.projects.map((project) => project.path), settings: profileDir(resolvedId) };
+    }
+    catch {
+        return { projects: [], settings: null };
+    }
+}
+function dedupeExistingDirs(paths) {
+    const seen = new Set();
+    const out = [];
+    for (const path of paths) {
+        const absolute = resolve(path);
+        if (seen.has(absolute) || !isDirectory(absolute))
+            continue;
+        seen.add(absolute);
+        out.push(absolute);
+    }
+    return out;
+}
+/** Keep only the outermost search roots. An outer profile project already
+ *  covers a cwd or another project nested beneath it, and avoiding the second
+ *  fd walk keeps every candidate unique without a separate dedupe process. */
+function outermostDirs(paths) {
+    return paths.filter((path) => !paths.some((other) => other !== path && path.startsWith(other + sep)));
+}
+/** Columns fzf keeps to the right of the matched substring when it scrolls a
+ *  long path into view. Wide enough to show the rest of the filename. */
+const HSCROLL_OFF = 20;
+function selectionPath(path) {
+    try {
+        const bytes = readFileSync(path);
+        if (bytes.length === 0)
+            return null;
+        const end = bytes[bytes.length - 1] === 0 ? bytes.length - 1 : bytes.length;
+        return bytes.subarray(0, end).toString('utf8') || null;
+    }
+    catch {
+        return null;
+    }
+}
+export function launchProfileFileSearch(opts) {
+    const fd = workingExecutable('fd', opts.fdPath);
+    if (fd === null) {
+        opts.onNotice('fd is required for profile file search');
+        return;
+    }
+    const fzf = workingExecutable('fzf');
+    if (fzf === null) {
+        opts.onNotice('fzf is required for profile file search');
+        return;
+    }
+    const nvim = workingExecutable('nvim');
+    if (nvim === null) {
+        opts.onNotice('Neovim is required for profile file search');
+        return;
+    }
+    const profile = profileSearchRoots(opts.profileId);
+    const pointers = dedupeExistingDirs([opts.cwd, ...opts.nodeDirs, ...profile.projects]);
+    if (pointers.length === 0) {
+        opts.onNotice('No profile file-search directories exist');
+        return;
+    }
+    const roots = outermostDirs(pointers);
+    const settingsDirs = dedupeExistingDirs([
+        ...(profile.settings === null ? [] : [profile.settings]),
+    ]);
+    const tempDir = mkdtempSync(join(tmpdir(), 'crtr-profile-files-'));
+    const selected = join(tempDir, 'selection');
+    const candidates = join(tempDir, 'candidates');
+    // A context dir can hold a full repo clone a node made for itself, so ignore
+    // rules stay on (they are what keeps a clone's dependencies out) and the
+    // background-bash log dir directly beneath it is dropped — those are
+    // transient command output named by job id, never a document to open.
+    const documentDirs = familyDocumentDirs(opts.nodes)
+        .filter((dir) => !roots.some((root) => dir === root || dir.startsWith(root + sep)));
+    const scans = [
+        ...roots.map((root) => `${shellQuote(fd)} --type f --hidden --exclude .git . ${shellQuote(root)}`),
+        ...documentDirs.map((dir) => `${shellQuote(fd)} --type f --hidden --exclude .git --exclude ${shellQuote('/jobs')} . ${shellQuote(dir)}`),
+        ...settingsDirs.map((dir) => `${shellQuote(fd)} --type f --hidden --exclude .git --no-ignore . ${shellQuote(dir)}`),
+    ];
+    // Every line is the whole path and nothing else, so fzf matches, ranks, and
+    // horizontally scrolls against the same text — a hidden field would be
+    // unsearchable, and a display slice would silently narrow the query.
+    const yankPath = 'printf \'%s\' {} | { if command -v pbcopy >/dev/null 2>&1; then pbcopy; elif command -v wl-copy >/dev/null 2>&1; then wl-copy; elif command -v xclip >/dev/null 2>&1; then xclip -selection clipboard; else cat >/dev/null; fi; }; printf \'%s\' {} | tmux load-buffer -w -';
+    // `+abort` closes the popup the instant the path is copied — without it the
+    // silent yank leaves the popup unchanged and reads as a dead key. Aborting
+    // writes no selection, so the caller opens no file and just cleans up.
+    const command = `{ ${scans.map((scan) => `${scan} &`).join(' ')} wait; } > ${shellQuote(candidates)} && ${shellQuote(fzf)} --print0 --scheme=path --hscroll-off=${HSCROLL_OFF} --header ${shellQuote('fuzzy path • ctrl-y yank file path')} --bind ${shellQuote(`ctrl-y:execute-silent(${yankPath})+abort`)} --preview ${shellQuote('head -100 -- {}')} < ${shellQuote(candidates)} > ${shellQuote(selected)}`;
+    try {
+        execFile('tmux', ['display-popup', '-E', '-T', ' profile files ', '-w', '80%', '-h', '60%', ...surfaceTmuxStyleArgs(), command], () => {
+            const file = selectionPath(selected);
+            if (file === null || !existsSync(file)) {
+                rmSync(tempDir, { recursive: true, force: true });
+                return;
+            }
+            const open = `exec ${nvimShellCommand('edit', [file], nvim)}`;
+            try {
+                execFile('tmux', ['display-popup', '-E', '-T', ' profile file ', '-w', '90%', '-h', '90%', ...surfaceTmuxStyleArgs(), open], () => rmSync(tempDir, { recursive: true, force: true }));
+            }
+            catch (err) {
+                rmSync(tempDir, { recursive: true, force: true });
+                opts.onNotice(`Could not open profile file: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        });
+    }
+    catch (err) {
+        rmSync(tempDir, { recursive: true, force: true });
+        opts.onNotice(`Could not open profile file search: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}