@north-light/api 0.3.579 → 0.3.587

package/dist/build-root.js

@@ -0,0 +1,401 @@
+import { defineBranch, defineRoot, GLOBAL_TOKENS } from './core/command.js';
+import { createCoreHookCatalog } from './core/command-hooks/catalog.js';
+import { composeCoreHooks } from './core/command-hooks/compose.js';
+import { mark } from './core/timing.js';
+import { ApiError } from './api/errors.js';
+import { CrtrError } from './core/errors.js';
+import { envNodeId, envScopes, isSandboxedNode, providerProjectionOverBrokerRelay, scopeAllowed } from './shared/env.js';
+const TAGLINE = 'crtr: agentic runtime.';
+/** Flags handled before dispatch, so they belong to no leaf schema and are
+ *  stated once at root (help.ts renders them as the Globals footer). */
+const GLOBALS = [
+    {
+        name: '--json',
+        desc: "stdout as the leaf's declared outputs in raw JSON instead of prose — for scripts (a cron's bash, external tooling) that must branch on canvas state; prose stays the contract for what you read yourself.",
+    },
+];
+/** Lazy registry: subtree name → dynamic importer that builds its BranchDef.
+ *  The whole point is that each `import()` only compiles that one subtree's
+ *  module graph. The hot path (`crtr surface node focus …`, `crtr push …`, …) dispatches
+ *  into a single leaf, so it must load ONE subtree — not the attach TUI and
+ *  every other subtree it never touches. `crtr` cold-start is dominated by Node
+ *  module loading; keeping the
+ *  other subtrees off the path is the biggest, lowest-risk win.
+ *
+ *  Null-prototype: `resolveRoot` indexes this by the raw first argv token, so a
+ *  normal object literal would resolve `Object.prototype` members — `crtr
+ *  toString` would build a root from a non-loader and report "Valid children:"
+ *  with nothing after it, and `crtr hasOwnProperty` would die untyped. With no
+ *  prototype every non-subtree token misses and falls through to the real
+ *  unknown-path error. */
+const SUBTREE_LOADERS = Object.assign(Object.create(null), {
+    doc: async () => (await import('./commands/doc.js')).registerDoc(),
+    'custom-object': async () => (await import('./commands/custom-object.js')).registerCustomObject(),
+    profile: async () => (await import('./commands/profile.js')).registerProfile(),
+    pkg: async () => (await import('./commands/pkg.js')).registerPkg(),
+    human: async () => (await import('./commands/human.js')).registerHuman(),
+    sys: async () => (await import('./commands/sys.js')).registerSys(),
+    node: async () => (await import('./commands/node.js')).registerNode(),
+    push: async () => (await import('./commands/push.js')).registerPush(),
+    cron: async () => (await import('./commands/cron.js')).registerCron(),
+    canvas: async () => (await import('./commands/canvas.js')).registerCanvas(),
+    surface: async () => (await import('./commands/surface.js')).registerSurface(),
+});
+/** Every shipped subtree name. Cheap (no module loading) — the front-door
+ *  recursion guard and the dispatcher's first-token routing need only names. */
+export const SUBTREE_NAMES = Object.freeze(Object.keys(SUBTREE_LOADERS));
+const SUBTREE_SCOPES = {
+    human: ['crtr:act'],
+    cron: ['crtr:schedule'],
+    doc: ['crtr:memory:read:user', 'crtr:memory:rw:user'],
+};
+function allowedSubtrees(core) {
+    const scopes = envScopes();
+    if (scopes === null)
+        return core;
+    return core.filter((branch) => {
+        const required = SUBTREE_SCOPES[branch.name];
+        return required === undefined || required.some((scope) => scopeAllowed(scopes, scope)) ||
+            // A node can always write and revise documents in its own app space;
+            // user-memory scopes govern only the person's space, not its own.
+            (branch.name === 'doc' && process.env['CRTR_GRANTEE']?.startsWith('app:') === true);
+    });
+}
+/** Every core subtree, built once per process and memoized PER SUBTREE, so a
+ *  partial load (one subtree for dispatch, the handful a plugin mount or hook
+ *  target names) and a later complete load share the same module work. */
+const subtreeCache = new Map();
+function loadSubtree(name) {
+    let loaded = subtreeCache.get(name);
+    if (loaded === undefined) {
+        loaded = SUBTREE_LOADERS[name]();
+        subtreeCache.set(name, loaded);
+    }
+    return loaded;
+}
+/** The named core subtrees, in declared order. Unknown names are ignored. */
+function loadCoreSubtreesNamed(names) {
+    return Promise.all(SUBTREE_NAMES.filter((n) => names.has(n)).map(loadSubtree));
+}
+/** Every core subtree. The strict plugin gates, the full root, and the complete
+ *  hook catalog need the whole set; the leaf-dispatch path never does. */
+function loadCoreSubtrees() {
+    return loadCoreSubtreesNamed(new Set(SUBTREE_NAMES));
+}
+/** Every core path is prefixed by its subtree name, so each of these sets is
+ *  partitioned by first token: a membership question about `cron add` is
+ *  answered identically by the cron subtree alone and by the whole tree, and a
+ *  path whose first token is no subtree is absent from both. */
+function subtreesNamedBy(paths) {
+    const names = new Set();
+    for (const path of paths) {
+        const first = path.split(' ')[0];
+        if (SUBTREE_NAMES.includes(first))
+            names.add(first);
+    }
+    return names;
+}
+/** Complete static catalog of hook-eligible core leaves. Lifecycle and recovery
+ *  inspection share the same memoized subtree load as root composition. */
+let hookCatalog;
+export function coreHookCatalog() {
+    mark('cli.hooks.catalog');
+    hookCatalog ??= loadCoreSubtrees().then(createCoreHookCatalog);
+    return hookCatalog;
+}
+/** A loader for the effective hook registry. The catalog only answers "is this
+ *  declared target an eligible core leaf?", and eligibility is per path, so it
+ *  is built over exactly the subtrees the declared targets name — the verdict
+ *  for every declared target is the complete catalog's, while a plugin that
+ *  declares only lifecycle hooks never loads another subtree. Loading is lazy —
+ *  only eligible leaf help or dispatch reaches it, and static help discovery
+ *  never runs a plugin executable. The memoization is per composed root, never
+ *  process-global: discovery reads stored plugin bytes and the caller's scope
+ *  stack, so a plugin install, update, or disable (and a cwd change in a
+ *  long-lived host) must govern the next root instead of being pinned by the
+ *  first one. */
+function hookRegistryLoader() {
+    let registry;
+    return () => {
+        // Dynamic import keeps hook discovery (manifest/artifact validation, plugin
+        // resolution) off the module graph of an invocation that neither renders
+        // eligible leaf help nor dispatches one, matching this file's lazy rationale.
+        registry ??= (async () => {
+            const { compileHookRegistry, declaredCommandHookTargets, effectiveHookPlugins } = await import('./core/command-hooks/discovery.js');
+            const all = effectiveHookPlugins();
+            // A cron or exec execution (no node id) has no broker-class hook plan to ask for.
+            const remote = isSandboxedNode() && envNodeId() !== undefined
+                ? await (await import('./core/command-hooks/transport/plan.js')).remoteHookPlan(process.cwd())
+                : [];
+            mark('cli.hooks.effective_plugins', { count: all.length + remote.length });
+            if (all.length === 0 && remote.length === 0) {
+                mark('cli.hooks.empty_registry');
+                return compileHookRegistry(createCoreHookCatalog([]), []);
+            }
+            const plugins = isSandboxedNode() ? all.filter(plugin => plugin.scope === 'project') : all;
+            const targeted = subtreesNamedBy([...declaredCommandHookTargets(plugins), ...remote.map((entry) => entry.target)]);
+            mark('cli.hooks.catalog', { subtrees: [...targeted].join(',') });
+            return compileHookRegistry(createCoreHookCatalog(await loadCoreSubtreesNamed(targeted)), plugins, remote);
+        })();
+        return registry;
+    };
+}
+function commandPathsFor(core) {
+    const paths = new Set();
+    const visit = (node, prefix) => {
+        if (node.kind === 'branch' && node.passthrough !== undefined)
+            return;
+        paths.add(prefix);
+        if (node.kind === 'branch')
+            for (const child of node.children)
+                visit(child, `${prefix} ${child.name}`);
+    };
+    for (const subtree of core)
+        visit(subtree, subtree.name);
+    return paths;
+}
+export async function coreCommandPaths() {
+    return commandPathsFor(await loadCoreSubtrees());
+}
+/** Core command paths covering `asked`: answers membership for every asked
+ *  path exactly as `coreCommandPaths()` would (paths are partitioned by their
+ *  subtree's name), while loading only the subtrees those paths name. */
+export async function coreCommandPathsCovering(asked) {
+    return commandPathsFor(await loadCoreSubtreesNamed(subtreesNamedBy(asked)));
+}
+function extensibleBranchPaths(core) {
+    const paths = [];
+    const visit = (branch, path) => {
+        if (branch.extensible === true)
+            paths.push(path);
+        for (const child of branch.children)
+            if (child.kind === 'branch')
+                visit(child, [...path, child.name]);
+    };
+    for (const branch of core)
+        visit(branch, [branch.name]);
+    return paths;
+}
+/** Every core branch marked `extensible: true`, space-joined. Declared
+ *  statically so leaf dispatch can decide whether plugin core mounts can reach
+ *  its subtree without importing every subtree to find out; a test pins it to
+ *  the markers the loaded tree actually carries. */
+export const EXTENSIBLE_CORE_BRANCHES = Object.freeze(['human', 'sys tutorial']);
+export async function extensibleCoreBranches() {
+    return new Set(EXTENSIBLE_CORE_BRANCHES);
+}
+/** The extensible branch paths the loaded tree declares — the source of truth
+ *  `EXTENSIBLE_CORE_BRANCHES` must match. */
+export async function declaredExtensibleCoreBranches() {
+    return new Set(extensibleBranchPaths(await loadCoreSubtrees()).map((path) => path.join(' ')));
+}
+function rebuildBranch(branch, children) {
+    const { listing: _listing, ...help } = branch.help;
+    return defineBranch({
+        name: branch.name,
+        description: branch.description,
+        whenToUse: branch.whenToUse,
+        tier: branch.tier,
+        help,
+        rootEntry: branch.rootEntry,
+        extensible: branch.extensible,
+        plugin: branch.plugin,
+        slash: branch.slash,
+        passthrough: branch.passthrough,
+        children,
+    });
+}
+/** Compose accepted plugin core mounts into `core`. `coreCommandPaths` is the
+ *  strict gate's path set; leaf dispatch passes a subset covering every subtree
+ *  the relevant manifests name (see `dispatchCommandPaths`), which yields the
+ *  complete set's verdict for each of them. */
+async function composeCorePluginMounts(core, extensible, coreCommandPaths) {
+    if (extensible.size === 0)
+        return core;
+    const [{ buildExternalCommandSnapshot }, { composeCoreBranchMounts }] = await Promise.all([
+        import('./core/command-plugins/discovery.js'),
+        import('./core/command-plugins/compose.js'),
+    ]);
+    const snapshot = buildExternalCommandSnapshot(new Set(SUBTREE_NAMES), undefined, undefined, coreCommandPaths, extensible);
+    const composeBranch = (branch, path) => {
+        let rebuilt = false;
+        const children = branch.children.map((child) => {
+            if (child.kind !== 'branch')
+                return child;
+            const composed = composeBranch(child, [...path, child.name]);
+            if (composed !== child)
+                rebuilt = true;
+            return composed;
+        });
+        const mounted = branch.extensible === true ? composeCoreBranchMounts(snapshot.coreMounts, path) : [];
+        return rebuilt || mounted.length > 0 ? rebuildBranch(branch, [...children, ...mounted]) : branch;
+    };
+    return core.map((branch) => composeBranch(branch, [branch.name]));
+}
+/** The core path set leaf dispatch into `first` validates manifests against,
+ *  or null when no manifest can mount below `first` at all.
+ *
+ *  The core path set can only REJECT a manifest (a helpAddenda key naming no
+ *  core path, or a core mount colliding with an existing child), never admit
+ *  one. So a tolerant pass without it finds every manifest that could
+ *  contribute a mount below `first`; each of those is then decided strictly
+ *  against the subtrees its own mounts and addenda name, which answers every
+ *  question the gate asks of it exactly as the complete set would. A manifest
+ *  with no mount below `first` contributes nothing to this root whatever its
+ *  verdict, and cross-plugin collision drops only mounts sharing one parent
+ *  path — below `first`, so among the manifests already covered. */
+async function dispatchCommandPaths(first, extensible) {
+    const { validateEffectiveCommandPlugins } = await import('./core/command-plugins/discovery.js');
+    const tolerant = validateEffectiveCommandPlugins(new Set(SUBTREE_NAMES), undefined, undefined, undefined, extensible);
+    const relevant = tolerant.flatMap((validation) => validation.manifest === undefined ? [] : [validation.manifest])
+        .filter((manifest) => manifest.coreMounts.some((mount) => mount.parent[0] === first));
+    if (relevant.length === 0)
+        return null;
+    const named = subtreesNamedBy(relevant.flatMap((manifest) => [
+        ...manifest.coreMounts.map((mount) => mount.parent.join(' ')),
+        ...Object.keys(manifest.helpAddenda ?? {}),
+    ]));
+    named.add(first);
+    return commandPathsFor(await loadCoreSubtreesNamed(named));
+}
+function isSysInvocation(argv, command) {
+    const tokens = argv.slice(2).filter((token) => !GLOBAL_TOKENS.has(token));
+    return tokens[0] === 'sys' && tokens[1] === command;
+}
+/** Command paths that act on the person's machine or installation rather than on an app's records. */
+const PERSON_ONLY_PATHS = [
+    ['surface'], ['sys'], ['pkg'], ['profile', 'default'],
+    ['canvas', 'chord'], ['canvas', 'config'], ['canvas', 'use'], ['canvas', 'browse'], ['canvas', 'issue'],
+];
+/** Leaves inside a person-only subtree that an app's node may still run: the command a node runs when the harness itself misbehaves. */
+const NODE_CALLABLE_PATHS = [['sys', 'feedback']];
+function startsWithPath(tokens, path) {
+    return path.every((name, index) => tokens[index] === name);
+}
+/** The person-only command path `argv` dispatches into, or null. */
+export function personOnlyInvocation(argv) {
+    const tokens = argv.slice(2).filter((token) => !GLOBAL_TOKENS.has(token));
+    if (NODE_CALLABLE_PATHS.some((candidate) => startsWithPath(tokens, candidate)))
+        return null;
+    const path = PERSON_ONLY_PATHS.find((candidate) => startsWithPath(tokens, candidate));
+    return path === undefined ? null : path.join(' ');
+}
+/** Select a smaller canonical tree; `runCli` still parses, renders help, and reports errors. */
+export function isDaemonControlInvocation(argv) { return isSysInvocation(argv, 'daemon'); }
+/** `sys signin` and `sys signout` run when the stored sign-in is gone or a move is unfinished, the states in which the settings load would refuse. */
+export function isSignInInvocation(argv) { return isSysInvocation(argv, 'signin') || isSysInvocation(argv, 'signout'); }
+export function isJoinInvocation(argv) { return isSysInvocation(argv, 'join'); }
+export function isLayoutMigrationInvocation(argv) { return isSysInvocation(argv, 'migrate'); }
+/** Assemble the canonical daemon-control definitions without loading settings or plugin discovery. This path exists so `crtr sys daemon restart` can start the new generation that converts pre-SQL user state. */
+export async function resolveDaemonControlRoot() {
+    const { registerDaemonControlSys } = await import('./commands/sys/daemon.js');
+    return defineRoot({ tagline: TAGLINE, globals: GLOBALS, subtrees: [registerDaemonControlSys()] });
+}
+/** Migration runs offline before command plugins can read or initialize scoped state. */
+export async function resolveLayoutMigrationRoot() {
+    const [{ defineSysBranch }, { sysMigrateLeaf }] = await Promise.all([
+        import('./commands/sys/branch.js'),
+        import('./commands/sys/migrate.js'),
+    ]);
+    return defineRoot({ tagline: TAGLINE, globals: GLOBALS, subtrees: [defineSysBranch([sysMigrateLeaf])] });
+}
+/** Build a root that contains only the subtree `first` dispatches into.
+ *  Returns the FULL root when `first` is not a recognized subtree — bare `crtr`,
+ *  `-h`/`--help`, `--version`, and any unknown leading token all need the
+ *  complete tree (root -h lists every subtree; the unknown-path error names
+ *  every valid child). This keeps every help/error surface byte-identical while
+ *  the common leaf-dispatch path loads exactly one subtree. */
+export async function resolveRoot(first) {
+    return (first !== undefined ? await resolveCoreRoot(first) : null) ?? buildRoot();
+}
+/** The root holding only core subtree `first` (with its plugin mounts and
+ *  hooks), or null when `first` is not a core subtree or this caller's scopes
+ *  hide it. Never composes external command sources, so it never fetches a
+ *  sandboxed node's provider catalog. */
+export async function resolveCoreRoot(first) {
+    if (SUBTREE_LOADERS[first] === undefined)
+        return null;
+    // Only a subtree holding an extensible branch can receive plugin mounts;
+    // every other subtree dispatches exactly as loaded, touching no plugin
+    // manifest and no other subtree.
+    const subtree = await loadSubtree(first);
+    const extensible = await extensibleCoreBranches();
+    const paths = [...extensible].some((path) => path.split(' ')[0] === first) ? await dispatchCommandPaths(first, extensible) : null;
+    const core = allowedSubtrees(paths === null ? [subtree] : await composeCorePluginMounts([subtree], extensible, paths));
+    return core.length > 0 ? defineRoot({ tagline: TAGLINE, globals: GLOBALS, subtrees: composeCoreHooks(core, hookRegistryLoader()) }) : null;
+}
+/** Assemble the full crtr command tree: every core subtree plus every top-level
+ *  branch contributed by an external command source — enabled command plugins
+ *  AND registered HTTP-transport plugins, folded together through ONE unified,
+ *  collision-resolved snapshot (`buildExternalCommandSnapshot`). Used for root
+ *  -h, the unknown-path error, bare-root boot, front-door recognition, and the
+ *  listing-completeness test — i.e. only the FALLTHROUGH path, never the core
+ *  fast path (`resolveRoot` short-circuits a recognized core first token with
+ *  zero plugin transport I/O). Root owns only the tagline; every subtree (core or
+ *  external) declares its own root representation via its rootEntry.
+ *
+ *  Order is deterministic: core subtrees in declared order first, then accepted
+ *  external branches sorted by contributor name (from the unified snapshot).
+ *  Composition is invocation-local — no cache, no persistence — and reads only
+ *  stored manifest bytes, so a plugin enable/update/remove or an HTTP-transport
+ *  plugin manifest replacement takes effect on the next invocation automatically.
+ *  The one network read is the granted provider catalog (`GET /v1/providers/tools`)
+ *  that a sandboxed node, a fleet node and a moved computer ask their control plane
+ *  or daemon for. On a moved computer a failed read does not abort the tree: the
+ *  tree is built from what is known locally and the failure rides on the root
+ *  (`providerCatalogFailure`), which the dispatcher raises in place of
+ *  `unknown_path` when the person types a top-level name the tree lacks. */
+export async function buildRoot() {
+    const core = await loadCoreSubtrees();
+    // Dynamic import keeps external command discovery/compose (plugin +
+    // HTTP-transport plugin, and their resolver/manifest/HTTP deps) OFF the hot leaf
+    // path's module graph — they load only here, on the fallthrough, matching
+    // this file's lazy-subtree rationale.
+    const [{ buildExternalCommandSnapshot }, { composeExternalSubtrees, composeSandboxProviderSubtrees }, { qualifiedTopLevelCommandName }] = await Promise.all([
+        import('./core/command-plugins/discovery.js'),
+        import('./core/command-plugins/compose.js'),
+        import('./core/command-manifests/registry.js'),
+    ]);
+    // ONE collision-resolved snapshot over every command plugin transport. Core always wins: any external contribution claiming a core top-level
+    // name is dropped + recorded as an issue (surfaced via pkg plugin show,
+    // sys doctor). Reads only stored manifests — zero network.
+    const extensible = await extensibleCoreBranches();
+    const composedCore = await composeCorePluginMounts(core, extensible, commandPathsFor(core));
+    const snapshot = buildExternalCommandSnapshot(new Set(SUBTREE_NAMES), undefined, undefined, commandPathsFor(core), extensible);
+    let external = composeExternalSubtrees(snapshot);
+    // A moved computer asks the control plane for the account's commands, as a sandboxed node asks its daemon.
+    const moved = (await import('./daemon/machine-link/config.js')).readMachineConfig() !== undefined;
+    let providerCatalogFailure;
+    if (isSandboxedNode() || providerProjectionOverBrokerRelay() || moved) {
+        // Installed user plugins live outside the broker's mounts, and a fleet sandbox holds no provider bundles. Get only the
+        // granted provider help descriptors from the daemon (through the broker relay on the fleet), never plugin files.
+        const { cliClient } = await import('./commands/api-client.js');
+        mark('cli.providers.request');
+        let providers = [];
+        try {
+            providers = (await cliClient().request('GET', '/v1/providers/tools')).providers;
+        }
+        catch (error) {
+            // Only a moved computer may build without the catalog (signed out, offline, mid-move); a node has no other tree to fall back to.
+            if (!moved || !(error instanceof ApiError || error instanceof CrtrError))
+                throw error;
+            providerCatalogFailure = error;
+        }
+        mark('cli.providers.fetched', { providers: providers.length });
+        const projected = composeSandboxProviderSubtrees(providers, new Set(SUBTREE_NAMES));
+        const providerNames = new Set(projected.map((branch) => branch.name));
+        // A mounted project plugin cannot shadow a granted provider's canonical
+        // command. Keep it reachable by the registry's origin-qualified name.
+        external = [...projected, ...composeExternalSubtrees({ ...snapshot, contributions: snapshot.contributions.map((entry) => providerNames.has(entry.node.name)
+                    ? { ...entry, node: { ...entry.node, name: qualifiedTopLevelCommandName(entry.contributor, entry.node.name) } }
+                    : entry) })];
+    }
+    // Before an account exists the six Northlight commands are listed as previews; a name already provided above keeps its real command.
+    if (!moved) {
+        const { previewBranches } = await import('./core/northlight/previews.js');
+        external = [...external, ...previewBranches(process.platform, new Set(external.map((branch) => branch.name)))];
+    }
+    // Only core leaves are hookable, so external contributions compose unwrapped.
+    const root = defineRoot({ tagline: TAGLINE, globals: GLOBALS, subtrees: [...composeCoreHooks(allowedSubtrees(composedCore), hookRegistryLoader()), ...external] });
+    return providerCatalogFailure === undefined ? root : { ...root, providerCatalogFailure };
+}

package/dist/clients/attach/ansi-cells.d.ts

@@ -0,0 +1,44 @@
+/** Read one terminal control sequence so non-printing ANSI never takes a cell.
+ *  `undefined` means the sequence runs off the end of the row. */
+export declare function readEscape(line: string, start: number): {
+    text: string;
+    end: number;
+} | undefined;
+/** One printable grapheme, with the escape sequences that preceded it. */
+export type RowGlyph = {
+    /** The grapheme itself, with no ANSI attached. */
+    text: string;
+    /** 0-indexed terminal cell this grapheme starts at. */
+    cell: number;
+    /** Cells occupied — 2 for a wide grapheme, 0 for a zero-width one. */
+    width: number;
+};
+/** Walk `line` as the terminal does, calling `onGlyph` per printable grapheme
+ *  and `onEscape` per control sequence, in row order. Returns the cell count. */
+export declare function walkRow(line: string, visit: {
+    onGlyph?: (glyph: RowGlyph) => void;
+    onEscape?: (escape: string) => void;
+}): number;
+/** Cells the row occupies on screen. */
+export declare function rowCells(line: string): number;
+/** Plain text of cells `[from, to)` — every escape, link boundary, and cursor
+ *  marker dropped, exactly what a terminal copies out of that span. */
+export declare function sliceCells(line: string, from: number, to: number): string;
+/** The SGR pair `styleCells` asserts over a span. A style that paints color
+ *  sets `restore`, because its `off` cannot un-set one color without also
+ *  discarding whatever color the row had underneath it — with `restore`, the
+ *  span closes by resetting and replaying the SGRs the row had already asserted. */
+export type CellStyle = {
+    on: string;
+    off: string;
+    restore?: boolean;
+};
+export declare const INVERSE_STYLE: CellStyle;
+/** Style cells `[from, to)`, re-asserting `style.on` after any SGR inside the
+ *  span (a reset there would otherwise drop the styling mid-span). A short row
+ *  is padded with spaces so a multi-row span reads as one block, never past
+ *  `maxCells`. Escapes are non-printing, so passes compose: styling an already
+ *  styled row leaves every cell position unmoved. */
+export declare function styleCells(line: string, from: number, to: number, maxCells: number, style?: CellStyle): string;
+/** Reverse-video cells `[from, to)` — the drag-selection highlight. */
+export declare function highlightCells(line: string, from: number, to: number, maxCells: number): string;

package/dist/clients/attach/ansi-cells.js

@@ -0,0 +1,137 @@
+// ansi-cells.ts — cell arithmetic over a rendered terminal row.
+//
+// A composed frame row mixes printable graphemes with SGR colors, OSC-8 link
+// boundaries, and pi-tui's APC cursor marker. Anything that addresses a row by
+// terminal column — link hit tests, mouse selection — has to walk it the way the
+// terminal does: escapes take no cell, wide graphemes take two. Both the attach
+// session and the renderers need that walk, so it lives at the client root
+// rather than inside either peer.
+import stringWidth from 'string-width';
+const GRAPHEMES = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+const INVERSE_ON = '\x1b[7m';
+const INVERSE_OFF = '\x1b[27m';
+/** Read one terminal control sequence so non-printing ANSI never takes a cell.
+ *  `undefined` means the sequence runs off the end of the row. */
+export function readEscape(line, start) {
+    const kind = line[start + 1];
+    if (kind === undefined)
+        return undefined;
+    // OSC, APC, DCS, and PM are string controls terminated by BEL or ST. pi-tui's
+    // cursor marker uses APC, so it must consume no display cells here.
+    if (kind === ']' || kind === '_' || kind === 'P' || kind === '^') {
+        const bel = line.indexOf('\x07', start + 2);
+        const st = line.indexOf('\x1b\\', start + 2);
+        const end = bel === -1 ? st : st === -1 ? bel : Math.min(bel, st);
+        if (end === -1)
+            return undefined;
+        return { text: line.slice(start, end + (end === bel ? 1 : 2)), end: end + (end === bel ? 1 : 2) };
+    }
+    if (kind === '[') {
+        let end = start + 2;
+        while (end < line.length && (line.charCodeAt(end) < 0x40 || line.charCodeAt(end) > 0x7e))
+            end++;
+        if (end >= line.length)
+            return undefined;
+        return { text: line.slice(start, end + 1), end: end + 1 };
+    }
+    return { text: line.slice(start, start + 2), end: start + 2 };
+}
+/** Walk `line` as the terminal does, calling `onGlyph` per printable grapheme
+ *  and `onEscape` per control sequence, in row order. Returns the cell count. */
+export function walkRow(line, visit) {
+    let cell = 0;
+    let index = 0;
+    while (index < line.length) {
+        if (line[index] === '\x1b') {
+            const escape = readEscape(line, index);
+            if (escape === undefined)
+                break;
+            visit.onEscape?.(escape.text);
+            index = escape.end;
+            continue;
+        }
+        const nextEscape = line.indexOf('\x1b', index);
+        const text = line.slice(index, nextEscape === -1 ? undefined : nextEscape);
+        for (const segment of GRAPHEMES.segment(text)) {
+            const width = stringWidth(segment.segment);
+            visit.onGlyph?.({ text: segment.segment, cell, width });
+            cell += width;
+        }
+        index = nextEscape === -1 ? line.length : nextEscape;
+    }
+    return cell;
+}
+/** Cells the row occupies on screen. */
+export function rowCells(line) {
+    return walkRow(line, {});
+}
+/** Plain text of cells `[from, to)` — every escape, link boundary, and cursor
+ *  marker dropped, exactly what a terminal copies out of that span. */
+export function sliceCells(line, from, to) {
+    let text = '';
+    walkRow(line, {
+        onGlyph: (glyph) => {
+            if (glyph.cell >= from && glyph.cell < to)
+                text += glyph.text;
+        },
+    });
+    return text;
+}
+export const INVERSE_STYLE = { on: INVERSE_ON, off: INVERSE_OFF };
+/** Style cells `[from, to)`, re-asserting `style.on` after any SGR inside the
+ *  span (a reset there would otherwise drop the styling mid-span). A short row
+ *  is padded with spaces so a multi-row span reads as one block, never past
+ *  `maxCells`. Escapes are non-printing, so passes compose: styling an already
+ *  styled row leaves every cell position unmoved. */
+export function styleCells(line, from, to, maxCells, style = INVERSE_STYLE) {
+    const end = Math.min(to, maxCells);
+    if (end <= from || from < 0)
+        return line;
+    let out = '';
+    let inside = false;
+    // The SGRs in force at the current point, so a color span can hand the row
+    // back exactly as it found it. A full reset clears the list.
+    const active = [];
+    const open = () => { if (!inside) {
+        out += style.on;
+        inside = true;
+    } };
+    const close = () => {
+        if (!inside)
+            return;
+        out += style.restore === true ? `\x1b[0m${active.join('')}` : style.off;
+        inside = false;
+    };
+    const cells = walkRow(line, {
+        onEscape: (escape) => {
+            out += escape;
+            if (!escape.endsWith('m'))
+                return;
+            if (escape === '\x1b[0m' || escape === '\x1b[m')
+                active.length = 0;
+            else
+                active.push(escape);
+            // An SGR inside the span may have reset every attribute, including ours.
+            if (inside)
+                out += style.on;
+        },
+        onGlyph: (glyph) => {
+            if (glyph.cell >= from && glyph.cell < end)
+                open();
+            else
+                close();
+            out += glyph.text;
+        },
+    });
+    close();
+    if (cells < end) {
+        const gap = Math.max(0, from - cells);
+        const styled = end - Math.max(from, cells);
+        out += ' '.repeat(gap) + style.on + ' '.repeat(styled) + (style.restore === true ? '\x1b[0m' : style.off);
+    }
+    return out;
+}
+/** Reverse-video cells `[from, to)` — the drag-selection highlight. */
+export function highlightCells(line, from, to, maxCells) {
+    return styleCells(line, from, to, maxCells);
+}

package/dist/clients/attach/chrome/bash-jobs.d.ts

@@ -0,0 +1,16 @@
+/** A live background job as the cockpit shows it (from the daemon's job list). */
+export interface BashJobStatus {
+    jobId: string;
+    command: string;
+    startedAtMs: number;
+}
+export declare function toBashJobStatus(job: {
+    job_id: string;
+    command: string;
+    started_at: string;
+}): BashJobStatus;
+/** Compact cockpit row: state first (matching the cron row), then the running
+ *  command. `cmdCap` is the columns the caller has left for that command, so the
+ *  cell shrinks with the pane instead of being clipped after the row's own key
+ *  hints. `undefined` for an empty list — the caller omits the row entirely. */
+export declare function bashJobsWaitSummary(jobs: readonly BashJobStatus[], nowMs?: number, cmdCap?: number): string | undefined;

package/dist/clients/attach/chrome/bash-jobs.js

@@ -0,0 +1,34 @@
+// chrome/bash-jobs.ts — the attach-side formatter for live backgrounded bash jobs,
+// mirroring chrome/cron-wait.ts: the compact one-row cockpit summary. Pure — takes
+// the already-scanned job list, never reads the daemon itself (the roster
+// lists the node's running jobs). Enter on that row opens
+// the Inspector's `jobs` section, which owns the drill-in rendering.
+import { bashJobCommandLine, formatBashElapsed } from '../../../core/bash-jobs.js';
+export function toBashJobStatus(job) {
+    return { jobId: job.job_id, command: job.command, startedAtMs: Date.parse(job.started_at) };
+}
+/** The job's command line, capped to `cap` columns. A
+ *  shell one-liner is cut on a word boundary when there is one near the cap, so
+ *  the cell ends on a readable token instead of mid-`$((`. */
+function cmdCell(command, cap) {
+    const oneLine = bashJobCommandLine(command);
+    if (oneLine.length <= cap)
+        return oneLine;
+    const cut = oneLine.slice(0, Math.max(1, cap - 1));
+    const space = cut.lastIndexOf(' ');
+    return `${(space >= cap - 12 ? cut.slice(0, space) : cut).trimEnd()}…`;
+}
+/** Compact cockpit row: state first (matching the cron row), then the running
+ *  command. `cmdCap` is the columns the caller has left for that command, so the
+ *  cell shrinks with the pane instead of being clipped after the row's own key
+ *  hints. `undefined` for an empty list — the caller omits the row entirely. */
+export function bashJobsWaitSummary(jobs, nowMs = Date.now(), cmdCap = 26) {
+    if (jobs.length === 0)
+        return undefined;
+    if (jobs.length === 1) {
+        const job = jobs[0];
+        return `bash job · ${formatBashElapsed(nowMs - job.startedAtMs)} · ${cmdCell(job.command, Math.max(12, cmdCap))}`;
+    }
+    const oldest = jobs[0]; // the job list is oldest-first
+    return `${jobs.length} bash jobs · oldest ${formatBashElapsed(nowMs - oldest.startedAtMs)}`;
+}