@north-light/api 0.3.579 → 0.3.587

package/dist/clients/attach/render/viewport.js

@@ -0,0 +1,184 @@
+/** Exactly one line retained for each clipped row of an inline-image block. */
+const CLIPPED_IMAGE_ROW = '\x1b[2m⌸ image — scroll to view\x1b[22m';
+const NO_VISIBLE_BLOCKS = { first: -1, last: -1, lastFullyVisible: -1 };
+function isInlineImageBlock(lines) {
+    return lines.some((line) => line.includes('\x1b_G') || line.includes('\x1b]1337;File='));
+}
+/** The first block whose rendered range extends beyond `line`. */
+function firstBlockAfter(source, line, width) {
+    let low = 0;
+    let high = source.blockCount();
+    while (low < high) {
+        const middle = Math.floor((low + high) / 2);
+        const end = source.blockStart(middle, width) + source.blockHeight(middle, width);
+        if (end > line)
+            high = middle;
+        else
+            low = middle + 1;
+    }
+    return low;
+}
+export function createTranscriptViewport(source, decorate) {
+    const state = { follow: true, anchor: undefined };
+    let lastWidth;
+    let lastRows = 0;
+    let cachedVisibleBlocks = NO_VISIBLE_BLOCKS;
+    let cachedVisibleRevision;
+    /** Resolve the identity anchor only against the source's current measurements. */
+    function resolveTop(width, rows, total) {
+        const bottom = Math.max(0, total - rows);
+        if (state.follow)
+            return bottom;
+        if (!state.anchor) {
+            state.follow = true;
+            return bottom;
+        }
+        const anchoredTop = source.anchorLine(state.anchor, width);
+        if (anchoredTop === undefined) {
+            state.follow = true;
+            state.anchor = undefined;
+            return bottom;
+        }
+        return Math.min(Math.max(0, anchoredTop), bottom);
+    }
+    function visibleRange(width, rows, total, top) {
+        const bottom = Math.min(total, top + rows);
+        if (top >= bottom)
+            return { top, bottom, total, blocks: NO_VISIBLE_BLOCKS };
+        const count = source.blockCount();
+        let index = firstBlockAfter(source, top, width);
+        let first = -1;
+        let last = -1;
+        let lastFullyVisible = -1;
+        while (index < count) {
+            const start = source.blockStart(index, width);
+            if (start >= bottom)
+                break;
+            const height = source.blockHeight(index, width);
+            const end = start + height;
+            if (end > top) {
+                if (first === -1)
+                    first = index;
+                last = index;
+                if (start >= top && end <= bottom)
+                    lastFullyVisible = index;
+            }
+            index++;
+        }
+        return { top, bottom, total, blocks: first === -1 ? NO_VISIBLE_BLOCKS : { first, last, lastFullyVisible } };
+    }
+    function currentSlice() {
+        if (lastWidth === undefined || lastRows <= 0)
+            return undefined;
+        const total = source.totalHeight(lastWidth);
+        const top = resolveTop(lastWidth, lastRows, total);
+        return visibleRange(lastWidth, lastRows, total, top);
+    }
+    return {
+        renderSlice(width, rows) {
+            const viewportRows = Math.max(0, rows);
+            lastWidth = width;
+            lastRows = viewportRows;
+            if (viewportRows === 0) {
+                cachedVisibleBlocks = NO_VISIBLE_BLOCKS;
+                cachedVisibleRevision = source.revision();
+                return [];
+            }
+            const total = source.totalHeight(width);
+            const top = resolveTop(width, viewportRows, total);
+            const slice = visibleRange(width, viewportRows, total, top);
+            const content = [];
+            for (let index = slice.blocks.first; index !== -1 && index <= slice.blocks.last; index++) {
+                const start = source.blockStart(index, width);
+                const lines = source.blockLines(index, width);
+                const height = source.blockHeight(index, width);
+                const end = start + height;
+                const visibleStart = Math.max(0, slice.top - start);
+                const visibleEnd = Math.min(height, slice.bottom - start);
+                if (visibleStart >= visibleEnd)
+                    continue;
+                const partiallyClipped = start < slice.top || end > slice.bottom;
+                if (partiallyClipped && isInlineImageBlock(lines)) {
+                    content.push(...Array(visibleEnd - visibleStart).fill(CLIPPED_IMAGE_ROW));
+                }
+                else if (decorate === undefined) {
+                    content.push(...lines.slice(visibleStart, visibleEnd));
+                }
+                else {
+                    for (let row = visibleStart; row < visibleEnd; row++)
+                        content.push(decorate(start + row, lines[row], width));
+                }
+            }
+            const padded = content.length >= viewportRows
+                ? content.slice(0, viewportRows)
+                : [...Array(viewportRows - content.length).fill(''), ...content];
+            cachedVisibleBlocks = slice.blocks;
+            cachedVisibleRevision = source.revision();
+            return padded;
+        },
+        scrollBy(lines) {
+            if (lastWidth === undefined || lastRows <= 0 || lines === 0)
+                return false;
+            const beforeFollow = state.follow;
+            const beforeAnchor = state.anchor;
+            const total = source.totalHeight(lastWidth);
+            const currentTop = resolveTop(lastWidth, lastRows, total);
+            const bottom = Math.max(0, total - lastRows);
+            const newTop = Math.min(Math.max(0, currentTop + lines), bottom);
+            if (newTop >= bottom) {
+                state.follow = true;
+                state.anchor = undefined;
+            }
+            else {
+                state.follow = false;
+                state.anchor = source.anchorAt(newTop, lastWidth);
+                if (!state.anchor)
+                    state.follow = true;
+            }
+            return state.follow !== beforeFollow || state.anchor !== beforeAnchor;
+        },
+        pageRows() {
+            return Math.max(0, lastRows - 1);
+        },
+        goLive() {
+            state.follow = true;
+            state.anchor = undefined;
+        },
+        scrollToLine(line) {
+            if (lastWidth === undefined || lastRows <= 0)
+                return;
+            const total = source.totalHeight(lastWidth);
+            const bottom = Math.max(0, total - lastRows);
+            const top = Math.min(Math.max(0, line - Math.floor(lastRows / 3)), bottom);
+            if (top >= bottom) {
+                state.follow = true;
+                state.anchor = undefined;
+                return;
+            }
+            state.follow = false;
+            state.anchor = source.anchorAt(top, lastWidth);
+            if (!state.anchor)
+                state.follow = true;
+        },
+        topLine() {
+            if (lastWidth === undefined || lastRows <= 0)
+                return undefined;
+            return resolveTop(lastWidth, lastRows, source.totalHeight(lastWidth));
+        },
+        isLive() {
+            return state.follow;
+        },
+        visibleBlocks() {
+            const revision = source.revision();
+            if (cachedVisibleRevision === revision)
+                return cachedVisibleBlocks;
+            const slice = currentSlice();
+            cachedVisibleBlocks = slice?.blocks ?? NO_VISIBLE_BLOCKS;
+            cachedVisibleRevision = revision;
+            return cachedVisibleBlocks;
+        },
+        invalidate() {
+            source.invalidate();
+        },
+    };
+}

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

@@ -0,0 +1,13 @@
+export interface BannerInfo {
+    version?: string;
+    profile?: string;
+    cwd?: string;
+    hint?: string;
+}
+/** Shown only when crouter itself started tmux for this person (the front door's
+ *  tmux handoff sets the env var), since only then can they not know the keys. */
+export declare const TMUX_SURVIVAL_HINT = "Ctrl+B d leaves \u2014 the agent keeps running \u00B7 Ctrl+B n / p switches windows";
+export declare function buildBannerInfo(meta: {
+    cwd?: string;
+    profile_id?: string | null;
+}): BannerInfo;

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

@@ -0,0 +1,33 @@
+// session/banner.ts — the crouton banner's session facts.
+//
+// Every field is best-effort: a missing one just drops its line from the
+// banner, so a viewer never fails to open over cosmetic metadata.
+import { homedir } from 'node:os';
+import { loadProfileManifest } from '../../../core/profiles/manifest.js';
+import { currentVersion } from '../../../core/self-update.js';
+/** Shown only when crouter itself started tmux for this person (the front door's
+ *  tmux handoff sets the env var), since only then can they not know the keys. */
+export const TMUX_SURVIVAL_HINT = 'Ctrl+B d leaves — the agent keeps running · Ctrl+B n / p switches windows';
+export function buildBannerInfo(meta) {
+    let version;
+    try {
+        version = currentVersion();
+    }
+    catch { /* skip version line */ }
+    let profile;
+    try {
+        if (meta.profile_id)
+            profile = loadProfileManifest(meta.profile_id).manifest.name;
+    }
+    catch { /* skip profile line */ }
+    let cwd = meta.cwd;
+    if (cwd) {
+        const home = homedir();
+        if (cwd === home)
+            cwd = '~';
+        else if (cwd.startsWith(home + '/'))
+            cwd = '~' + cwd.slice(home.length);
+    }
+    const hint = process.env['CRTR_TMUX_STARTED'] === '1' ? TMUX_SURVIVAL_HINT : undefined;
+    return { version, profile, cwd, ...(hint !== undefined ? { hint } : {}) };
+}

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

@@ -0,0 +1,20 @@
+import { type AttachBindingId, type BindingId, type BindingResolution, type UserKeybindingSettings } from '../../../core/keybindings/index.js';
+export type { AttachBindingId } from '../../../core/keybindings/index.js';
+export type AttachBindings = BindingResolution<BindingId>;
+export type AttachActions = Record<AttachBindingId, () => void>;
+export declare const ATTACH_VIEWPORT_BINDINGS: readonly ["crtr.attach.scroll.up", "crtr.attach.scroll.down", "crtr.attach.scroll.page-up", "crtr.attach.scroll.page-down", "crtr.attach.scroll.live", "crtr.attach.mouse.toggle", "crtr.attach.copy.message"];
+export type AttachViewportBindingId = typeof ATTACH_VIEWPORT_BINDINGS[number];
+export type AttachViewportActions = Record<AttachViewportBindingId, () => void>;
+export { backgroundBashHint, inboxOpenHint } from '../../../core/keybindings/index.js';
+export declare function matchesAttachBinding(bindings: AttachBindings, id: BindingId, data: string): boolean;
+export declare function dispatchAttachAction(id: AttachBindingId, actions: AttachActions): void;
+export declare function dispatchAttachBinding(bindings: AttachBindings, data: string, actions: AttachActions): boolean;
+export declare function dispatchAttachViewportBinding(bindings: AttachBindings, data: string, actions: AttachViewportActions): boolean;
+export declare function detachHint(bindings: AttachBindings): string | undefined;
+/** The dedicated detach binding's spelling (ctrl+d), for pointing the user at
+ *  detach now that a second ctrl+c cancels the running turn instead. */
+export declare function detachBindingHint(bindings: AttachBindings): string | undefined;
+/** Re-resolve the user's binding settings once and republish the same snapshot
+ *  to every consumer: attach dispatch, the graph overlay, and tmux. Binding
+ *  diagnostics must never fail an attach, so an install error is swallowed. */
+export declare function refreshAttachBindingSnapshot(resolve: () => UserKeybindingSettings, setGraphBindings: (bindings: AttachBindings) => void, inTmuxNow: () => boolean, install: (bindings: AttachBindings, tmuxPassthrough: readonly BindingId[]) => void): UserKeybindingSettings;

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

@@ -0,0 +1,71 @@
+// session/bindings.ts — the viewer's key-gesture layer: which crouter bindings
+// the attach surface itself consumes, and how a live snapshot is refreshed.
+//
+// Every attach-owned gesture is resolved from the SAME user binding catalog the
+// tmux installer binds from (`core/keybindings`), never from ad-hoc key
+// literals, so a user's rebind is honored by the viewer and tmux alike.
+import { matchesKey } from '@earendil-works/pi-tui';
+import { ATTACH_CONTROL_BINDINGS, formatBinding, matchesPiTuiInput, normalizeShiftedMeta, } from '../../../core/keybindings/index.js';
+export const ATTACH_VIEWPORT_BINDINGS = [
+    'crtr.attach.scroll.up', 'crtr.attach.scroll.down',
+    'crtr.attach.scroll.page-up', 'crtr.attach.scroll.page-down',
+    'crtr.attach.scroll.live',
+    'crtr.attach.mouse.toggle',
+    'crtr.attach.copy.message',
+];
+export { backgroundBashHint, inboxOpenHint } from '../../../core/keybindings/index.js';
+export function matchesAttachBinding(bindings, id, data) {
+    // Match the normalized chunk, never the raw one: a terminal that sends Option
+    // as a meta prefix spells Alt+Shift+M in a form pi-tui rejects. Only matching
+    // reads the rewrite — unclaimed input reaches the editor exactly as typed.
+    return matchesPiTuiInput(bindings, id, normalizeShiftedMeta(data), (input, gesture) => matchesKey(input, gesture));
+}
+export function dispatchAttachAction(id, actions) {
+    actions[id]();
+}
+export function dispatchAttachBinding(bindings, data, actions) {
+    for (const { actionId } of ATTACH_CONTROL_BINDINGS) {
+        if (matchesAttachBinding(bindings, actionId, data)) {
+            dispatchAttachAction(actionId, actions);
+            return true;
+        }
+    }
+    return false;
+}
+export function dispatchAttachViewportBinding(bindings, data, actions) {
+    for (const actionId of ATTACH_VIEWPORT_BINDINGS) {
+        if (matchesAttachBinding(bindings, actionId, data)) {
+            actions[actionId]();
+            return true;
+        }
+    }
+    return false;
+}
+export function detachHint(bindings) {
+    for (const id of ['crtr.attach.clear-or-detach', 'crtr.attach.detach']) {
+        if (bindings.gestures(id).length > 0)
+            return formatBinding(bindings, id);
+    }
+    return undefined;
+}
+/** The dedicated detach binding's spelling (ctrl+d), for pointing the user at
+ *  detach now that a second ctrl+c cancels the running turn instead. */
+export function detachBindingHint(bindings) {
+    return bindings.gestures('crtr.attach.detach').length > 0
+        ? formatBinding(bindings, 'crtr.attach.detach')
+        : undefined;
+}
+/** Re-resolve the user's binding settings once and republish the same snapshot
+ *  to every consumer: attach dispatch, the graph overlay, and tmux. Binding
+ *  diagnostics must never fail an attach, so an install error is swallowed. */
+export function refreshAttachBindingSnapshot(resolve, setGraphBindings, inTmuxNow, install) {
+    const settings = resolve();
+    setGraphBindings(settings.bindings);
+    if (inTmuxNow()) {
+        try {
+            install(settings.bindings, settings.tmuxPassthrough);
+        }
+        catch { /* attaching must not fail on binding diagnostics */ }
+    }
+    return settings;
+}

package/dist/clients/attach/session/chrome-refresh.d.ts

@@ -0,0 +1,49 @@
+import type { AttachSession } from './context.js';
+/** The sticky status-line text while crtrd is not answering chrome reads. */
+export declare const DAEMON_STALLED_NOTICE = "crtrd not responding \u2014 retrying";
+/** A failure that says crtrd is slow, restarting or gone — not that the request
+ *  was wrong. The viewer keeps its last chrome and retries; it never exits. */
+export declare function isTransientDaemonFailure(error: unknown): boolean;
+export interface ChromeRefreshHooks {
+    /** True once teardown has begun — stops both the loop and a re-arm. */
+    isTornDown: () => boolean;
+    /** The viewer's transient notice slot — the ONLY failure channel here. */
+    setNotice: (msg: string, opts?: {
+        sticky?: boolean;
+    }) => void;
+    /** Repaint the relationship roster (chrome/roster.ts refresh). */
+    refreshRoster: () => Promise<void>;
+    /** Repaint the graph overlay if open. */
+    refreshGraph: () => void;
+    /** Re-read the node's persona/lifecycle/icon from canvas — a runtime
+     *  promote/reshape changes it with no broker event, so the poll catches it. */
+    refreshIdentity: () => void;
+    renderFooter: () => void;
+    renderExtensionWidgets: () => void;
+    /** Re-measure the tool calls still in flight, so a silent long-running bash
+     *  call still reaches its backgrounding hint with no per-call timer. */
+    refreshInFlightTools: () => void;
+    /** Re-poll this pane's own git context (owned by the editor chrome). */
+    pollGit: () => void;
+}
+export interface ChromeRefresh {
+    /** Refresh all canvas chrome (panels + overlay if open). Coalescing: an
+     *  overlapping request collapses into one queued re-run instead of stacking. */
+    refresh: () => void;
+    /** The live ask-count map, keyed by node id. */
+    asks: () => Record<string, number>;
+    /** Report an async chrome failure through the notice slot — NEVER stderr:
+     *  this process owns an alternate-screen TUI, and a stray stderr write paints
+     *  raw bytes through the current frame and corrupts it. The last good chrome
+     *  snapshot is simply kept; the trimmed cause rides along so a persistent
+     *  failure (e.g. a stale viewer generation talking to a newer crtrd) is
+     *  diagnosable from the pane. */
+    reportFailure: (label: string, cause?: unknown) => void;
+    /** True while crtrd is failing chrome reads with a transient error. */
+    daemonStalled: () => boolean;
+    /** Run the initial poll and arm the poll timer. Call once, after `tui.start()`. */
+    start: () => void;
+    /** Clear the poll timer. Called from teardown's `stopLocal`. */
+    stop: () => void;
+}
+export declare function createChromeRefresh(ctx: Pick<AttachSession, 'nodeId' | 'canvasSource'>, hooks: ChromeRefreshHooks): ChromeRefresh;

package/dist/clients/attach/session/chrome-refresh.js

@@ -0,0 +1,154 @@
+// session/chrome-refresh.ts — the canvas-chrome refresh/poll engine: the
+// ask-count map (this module is its ONE writer; everything else reads it
+// through `asks()`), the coalescing refresh loop, and the low-rate 5s poll
+// that catches canvas changes which emit no broker event.
+import { APIError, isDaemonTransportApiError } from '../../../api/errors.js';
+/** Low-rate canvas-chrome poll cadence while crtrd answers. */
+const ASKS_POLL_MS = 5_000;
+/** Poll cadence ceiling while crtrd is not answering. Each failed pass doubles
+ *  the wait from `ASKS_POLL_MS`, so a stalled daemon is not handed a new batch
+ *  of reads every five seconds while the last batch is still timing out. */
+const ASKS_POLL_MAX_MS = 60_000;
+/** The sticky status-line text while crtrd is not answering chrome reads. */
+export const DAEMON_STALLED_NOTICE = 'crtrd not responding — retrying';
+/** A failure that says crtrd is slow, restarting or gone — not that the request
+ *  was wrong. The viewer keeps its last chrome and retries; it never exits. */
+export function isTransientDaemonFailure(error) {
+    return isDaemonTransportApiError(error) || (error instanceof APIError && error.status >= 500);
+}
+export function createChromeRefresh(ctx, hooks) {
+    const { nodeId, canvasSource } = ctx;
+    let asksMap = {};
+    let asksTimer;
+    let stopped = false;
+    // Consecutive chrome passes that failed with a transient daemon error. Zero
+    // means crtrd is answering; above zero the sticky indicator is up and the
+    // poll is backed off.
+    let stalledPasses = 0;
+    // Bumped on every reported failure, so a pass can tell whether anything
+    // inside it failed even when the failing collaborator swallowed the error.
+    let failureSeq = 0;
+    const markStalled = () => {
+        if (stalledPasses === 0)
+            hooks.setNotice(DAEMON_STALLED_NOTICE, { sticky: true });
+        stalledPasses = Math.min(stalledPasses + 1, 16);
+    };
+    const markHealthy = () => {
+        if (stalledPasses === 0)
+            return;
+        stalledPasses = 0;
+        // A transient notice replaces the sticky indicator and fades on its own.
+        hooks.setNotice('crtrd responding again');
+        rearm(ASKS_POLL_MS);
+    };
+    const reportFailure = (label, cause) => {
+        failureSeq++;
+        if (isTransientDaemonFailure(cause)) {
+            markStalled();
+            return;
+        }
+        const detail = (cause instanceof Error ? cause.message : cause === undefined ? '' : String(cause))
+            .replace(/\s+/g, ' ')
+            .trim()
+            .slice(0, 120);
+        hooks.setNotice(detail === '' ? `${label} delayed` : `${label} delayed — ${detail}`);
+    };
+    // Refresh all canvas chrome (panels + overlay if open) from the active canvas source.
+    let chromeRefreshInFlight = false;
+    let chromeRefreshQueued = false;
+    const refresh = () => {
+        chromeRefreshQueued = true;
+        if (chromeRefreshInFlight)
+            return;
+        chromeRefreshInFlight = true;
+        void (async () => {
+            try {
+                while (chromeRefreshQueued && !hooks.isTornDown()) {
+                    chromeRefreshQueued = false;
+                    const seqBefore = failureSeq;
+                    try {
+                        await hooks.refreshRoster();
+                        if (failureSeq === seqBefore)
+                            markHealthy();
+                    }
+                    catch (err) {
+                        reportFailure('canvas panel refresh', err);
+                    }
+                    hooks.refreshGraph();
+                }
+            }
+            finally {
+                chromeRefreshInFlight = false;
+                if (chromeRefreshQueued && !hooks.isTornDown())
+                    refresh();
+            }
+        })().catch((err) => reportFailure('canvas chrome refresh', err));
+    };
+    const climbRootFromSource = async (self) => {
+        let cur = self;
+        const seen = new Set([cur]);
+        for (;;) {
+            const mgr = (await canvasSource.subscribersOf(cur).catch(() => []))[0]?.node_id;
+            if (mgr === undefined || seen.has(mgr))
+                break;
+            seen.add(mgr);
+            cur = mgr;
+        }
+        return cur;
+    };
+    // Low-rate canvas-chrome refresh: repaint panels/overlay from the active canvas
+    // source (child status flips emit no broker event) and re-poll the ask map asynchronously.
+    const pollChrome = () => {
+        refresh();
+        hooks.refreshIdentity();
+        hooks.renderExtensionWidgets();
+        hooks.pollGit();
+        // A long-running SILENT bash call emits no tool-execution update, so this
+        // cadence is what brings its backgrounding hint on screen.
+        hooks.refreshInFlightTools();
+        hooks.renderFooter();
+        void (async () => {
+            const root = await climbRootFromSource(nodeId);
+            const counts = await canvasSource.ticketCountsForView(root);
+            if (JSON.stringify(counts) !== JSON.stringify(asksMap)) {
+                asksMap = counts;
+                refresh();
+                hooks.renderFooter(); // the closed-inbox footer total tracks asksMap
+            }
+        })().catch((err) => reportFailure('canvas attention refresh', err));
+    };
+    const nextDelay = () => stalledPasses === 0 ? ASKS_POLL_MS : Math.min(ASKS_POLL_MS * 2 ** stalledPasses, ASKS_POLL_MAX_MS);
+    // A self-rescheduling timer rather than an interval, so the wait can grow
+    // while crtrd is stalled and snap back to the base cadence on recovery.
+    function rearm(ms) {
+        if (stopped || asksTimer === undefined)
+            return;
+        clearTimeout(asksTimer);
+        schedule(ms);
+    }
+    function schedule(ms) {
+        asksTimer = setTimeout(() => {
+            if (stopped || hooks.isTornDown())
+                return;
+            pollChrome();
+            schedule(nextDelay());
+        }, ms);
+        if (typeof asksTimer.unref === 'function')
+            asksTimer.unref();
+    }
+    return {
+        refresh,
+        asks: () => asksMap,
+        reportFailure,
+        daemonStalled: () => stalledPasses > 0,
+        start: () => {
+            pollChrome();
+            schedule(ASKS_POLL_MS);
+        },
+        stop: () => {
+            stopped = true;
+            if (asksTimer !== undefined)
+                clearTimeout(asksTimer);
+        },
+    };
+}

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

@@ -0,0 +1,54 @@
+import type { BrokerSnapshot, ClientRole } from '../../../core/runtime/broker-protocol.js';
+import type { CanvasSource } from '../../../core/canvas/source.js';
+import type { NodeMeta } from '../../../core/canvas/types.js';
+import { BrokerClient, type RelayTarget } from '../../../core/broker-client/index.js';
+/** A relay target for an imported Mac: the cloud control plane, with the signed-in person's bearer. `relayToken` is read at each dial. */
+export declare function machineRelayTarget(apiUrl: string, directoryUrl: string): Promise<RelayTarget>;
+/** The hello handshake's initial role: controller unless `--observer`. A remote
+ *  attach (`--canvas`) claims it too; crtrd admits a controller only for a
+ *  caller with `message` permission on the node (`read` admits an observer) and
+ *  closes the socket before any frame reaches the broker otherwise. */
+export declare function resolveHelloRole(observer: boolean): ClientRole;
+/** bootRoot spawns the viewer BEFORE its freshly-launched broker has bound
+ *  view.sock, so the viewer's own CLI boot (~0.4s of module load) overlaps the
+ *  broker's ~1s startup instead of serializing after it. When that spawner set
+ *  CRTR_ATTACH_WAIT_MS, poll the socket with throwaway probe connects until it
+ *  accepts or the deadline passes — then fall through and let the normal
+ *  one-shot connect race surface the usual BrokerUnavailableError. Without the
+ *  env var this is a no-op: a plain `crtr surface attach` keeps its fail-fast
+ *  "attach does NOT launch the engine" contract. */
+export declare function preWaitForViewSocket(nodeId: string): Promise<void>;
+/** A connected viewer's transport facts, established before any UI exists. */
+export interface AttachConnection {
+    /** THE single remote fact for the whole session (the node lives on another
+     *  canvas; local-host operations are off), derived ONCE here from `--canvas`. Every local disk/SQLite read or write keyed on the node id
+     *  gates on this one flag; no collaborator re-derives "is this remote". */
+    readonly remote: boolean;
+    /** Canvas read authority: an API source locally, a relayed source remotely. */
+    readonly canvasSource: CanvasSource;
+    /** Viewer-LOCAL concerns only — `cwd` drives theming and this pane's own git
+     *  status, and is the CLI's own cwd under `--canvas`. */
+    readonly meta: Pick<NodeMeta, 'cwd' | 'profile_id' | 'grantee'>;
+    /** The attached node's persona/lifecycle, when this canvas can tell us —
+     *  `undefined` for a remote attach until the viewer refetches it. */
+    readonly nodeIdentity: Pick<NodeMeta, 'kind' | 'mode' | 'lifecycle' | 'icon'> | undefined;
+    /** The one socket target for the node's headless broker. It is intentionally
+     * disconnected only when focus opened an exact parked resident offline. */
+    readonly socket: BrokerClient;
+    /** Saved snapshot used to seed an offline parked viewer. Absent for direct
+     * attach and for focus paths whose broker was live or legitimately woke. */
+    readonly initialSnapshot?: BrokerSnapshot;
+    readonly initialCommands?: ReadonlyArray<{
+        name: string;
+        description: string;
+        source: string;
+    }>;
+    /** Re-throw a connect-adjacent failure that landed AFTER `connect` resolved.
+     *  Call once, synchronously, just before permanent socket wiring takes over;
+     *  a no-op if nothing failed. See the never-removed error listener below. */
+    assertConnected(): void;
+}
+/** Resolve the target, revive the node if it is dormant (server-side), and dial
+ *  the broker. Rejects with a plain `InputError` — no terminal has been taken
+ *  over at this point, so a failure here is an ordinary non-zero CLI exit. */
+export declare function connectToNode(nodeId: string, canvasName?: string, wakeParked?: boolean): Promise<AttachConnection>;