@north-light/crouter 0.3.172 → 0.3.174

package/dist/core/runtime/view-socket.js

@@ -0,0 +1,83 @@
+// Broker view-socket readiness — one connect probe and its distinct wait policies.
+//
+// A successful Unix-socket connect proves a broker is listening; socket-file
+// existence alone can be stale after a broker exit. This stays canvas-db-free so
+// command callers can wait without reaching a runtime placement owner.
+import { createConnection } from 'node:net';
+import { viewSocketPath } from '../canvas/paths.js';
+const BROKER_FOCUS_SOCKET_WAIT_MS = 30_000;
+const BROKER_FOCUS_SOCKET_RETRY_MS = 100;
+/** The shared cold-start deadline (ms) a freshly-opened viewer waits for its
+ * broker's view.sock — one source of truth for CRTR_ATTACH_WAIT_MS. */
+export const BROKER_VIEW_SOCKET_WAIT_MS = BROKER_FOCUS_SOCKET_WAIT_MS;
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+/** Resolve true exactly when `sockPath` accepts a connection within `timeoutMs`. */
+export function probeViewSocket(sockPath, timeoutMs) {
+    return new Promise((resolve) => {
+        let settled = false;
+        let socket = null;
+        const finish = (ok) => {
+            if (settled)
+                return;
+            settled = true;
+            if (socket !== null)
+                socket.destroy();
+            resolve(ok);
+        };
+        try {
+            socket = createConnection(sockPath);
+        }
+        catch {
+            finish(false);
+            return;
+        }
+        socket.once('connect', () => finish(true));
+        socket.once('error', () => finish(false));
+        socket.setTimeout(timeoutMs, () => finish(false));
+    });
+}
+/** Bounded retry for the revive leaf, which has no launch handle to observe. */
+export async function waitForViewSocketReady(nodeId) {
+    const sockPath = viewSocketPath(nodeId);
+    const deadline = Date.now() + BROKER_FOCUS_SOCKET_WAIT_MS;
+    while (Date.now() <= deadline) {
+        if (await probeViewSocket(sockPath, BROKER_FOCUS_SOCKET_RETRY_MS))
+            return true;
+        await sleep(BROKER_FOCUS_SOCKET_RETRY_MS);
+    }
+    return false;
+}
+/** Wait for a launched broker's view.sock, failing fast when its launch handle
+ * exits. `exited` remains optional for existing callers that only need the same
+ * bounded readiness deadline without a handle. */
+export async function waitForBrokerViewSocket(nodeId, exited) {
+    const sockPath = viewSocketPath(nodeId);
+    const deadline = Date.now() + BROKER_FOCUS_SOCKET_WAIT_MS;
+    const exitSeen = exited?.then(() => 'exit');
+    while (Date.now() <= deadline) {
+        const remaining = Math.max(0, deadline - Date.now());
+        const probe = probeViewSocket(sockPath, Math.min(BROKER_FOCUS_SOCKET_RETRY_MS, remaining))
+            .then((ok) => (ok ? 'ready' : 'retry'));
+        const outcome = exitSeen === undefined ? await probe : await Promise.race([probe, exitSeen]);
+        if (outcome === 'ready')
+            return true;
+        if (outcome === 'exit')
+            return false;
+        if (exitSeen !== undefined) {
+            const sleptOrExit = await Promise.race([
+                sleep(BROKER_FOCUS_SOCKET_RETRY_MS).then(() => 'sleep'),
+                exitSeen,
+            ]);
+            if (sleptOrExit === 'exit')
+                return false;
+        }
+        else {
+            await sleep(BROKER_FOCUS_SOCKET_RETRY_MS);
+        }
+    }
+    return false;
+}

package/dist/core/session-model/session-state.d.ts

@@ -36,8 +36,7 @@ export interface SessionState {
      *  a welcome is a COMPLETE catch-up, so a welcome naming none clears it.
      *  (The terminal viewer does not read this field: its overlay is owned by
      *  `InputController`, which holds a live TUI handle rather than data. The field
-     *  is still session state — it is derived solely from broker frames — and the
-     *  web SPA renders straight off it.) */
+     *  remains session state because it is derived solely from broker frames.) */
     dialog: RpcExtensionUIRequest | null;
 }
 export declare function initialSessionState(role?: ClientRole): SessionState;

package/dist/core/session-model/session-state.js

@@ -1,23 +1,20 @@
 // session-state.ts — the ONE model of "what the broker has told this viewer".
 //
-// Both viewers (the terminal `crtr surface attach` client and the web SPA) used
-// to hand-maintain their own copies of the same facts, patched imperatively from
-// their own frame switches, and they DRIFTED: the terminal learned to clear
-// `isStreaming` on `agent_settled` (the frozen-`Working…` fix) and the web never
-// did. One reducer, two heads.
+// Terminal attach folds every broker-derived fact through this reducer instead
+// of patching mutable state in individual frame handlers. One reducer keeps the
+// protocol projection coherent across every terminal consumer.
 //
 // The cut line is mechanical:
 //
 //   SESSION state = anything derived SOLELY from what the broker sent.
-//   VIEWER  state = anything derived from local input or this terminal/tab.
+//   VIEWER  state = anything derived from local input or this terminal viewer.
 //
 // So `role` belongs here even though it differs per viewer (the broker fixes it
 // from this viewer's `hello` and never changes it — "identical across viewers"
 // would get it wrong), while a transient notice, a connection phase, a
 // correlation id this viewer minted, and the transcript
 // RENDERING all stay with the viewer. The transcript itself is deliberately out
-// of scope: the terminal accumulates into a scrollback and the web replaces
-// wholesale, and that difference is legitimate.
+// of scope because the terminal accumulates it into scrollback.
 //
 // `reduce` is pure and total over `BrokerToClient`: unknown/irrelevant frames
 // return the SAME object reference, so a viewer can drive its repaints off

package/dist/core/spawn.d.ts

@@ -5,7 +5,7 @@
  *  nodes of human-in-the-loop. */
 export declare function isInTmux(): boolean;
 /** Is the canvas tmux SERVER reachable? The canvas runs on the DEFAULT tmux
- *  socket (no -L/-S in core/runtime/tmux.ts), so any `crtr` child — including a
+ *  socket (no -L/-S in core/runtime/tmux-driver.ts), so any `crtr` child — including a
  *  headless-broker child that has deleted its own $TMUX — can split panes into
  *  it. The human surface gates on THIS (can I reach the server to open a pane
  *  the user is watching?), not on the caller's $TMUX. `list-clients` exits 0

package/dist/core/spawn.js

@@ -3,7 +3,7 @@
 // The human surface gates on whether the canvas tmux server is reachable
 // (tmuxServerReachable) so it can decide whether to surface a prompt or degrade
 // to the inbox-drain follow-up. The canvas runtime has its own
-// one-window-per-node machinery in core/runtime/tmux.ts.
+// one-window-per-node machinery in core/runtime/placement-tmux.ts.
 import { spawnSync } from 'node:child_process';
 /** Does THIS process sit inside a tmux client (its own $TMUX is set)? NOT the
  *  gate for the human surface — see tmuxServerReachable. A headless-broker child
@@ -14,7 +14,7 @@ export function isInTmux() {
     return Boolean(process.env.TMUX);
 }
 /** Is the canvas tmux SERVER reachable? The canvas runs on the DEFAULT tmux
- *  socket (no -L/-S in core/runtime/tmux.ts), so any `crtr` child — including a
+ *  socket (no -L/-S in core/runtime/tmux-driver.ts), so any `crtr` child — including a
  *  headless-broker child that has deleted its own $TMUX — can split panes into
  *  it. The human surface gates on THIS (can I reach the server to open a pane
  *  the user is watching?), not on the caller's $TMUX. `list-clients` exits 0

package/dist/core/substrate/gate.d.ts

@@ -1,5 +1,5 @@
 import type { SubstrateDoc } from './schema.js';
-import type { NodeConfigSubject } from './subject.js';
+import type { NodeConfigSubject } from './subject-fields.js';
 /** Does `doc` pass its gate for `subject`?
  *
  *  - No gate (field absent) ⇒ `true`: always eligible (the common case).

package/dist/core/substrate/on-read-pure.d.ts

@@ -0,0 +1,7 @@
+import type { NodeConfigSubject } from './subject-fields.js';
+/** Surface docs matched by a successful read tool call using the caller-supplied
+ * daemon snapshot subject. */
+export declare function renderOnReadDocsForSubject(subject: NodeConfigSubject, readFilePath: string, seen?: Set<string>): string;
+/** Workspace boot docs using the snapshot's cwd/profile instead of a canvas
+ * lookup. */
+export declare function renderWorkspaceOpenDocsForSubject(subject: NodeConfigSubject, cwd: string, profileId: string | null): string;

package/dist/core/substrate/on-read-pure.js

@@ -0,0 +1,272 @@
+// on-read.ts — file-context delivery for the document substrate.
+//
+// A memory with file-read visibility participates only through an explicit
+// `applies-to` path glob (authoring lint requires one). Two events use that one
+// routing mechanism:
+//
+//   • A successful `read` tool call evaluates the read file against every
+//     visible substrate doc. Project stores encountered between that file and
+//     the filesystem root join the resolved cwd/profile corpus, so a nested
+//     workspace can contribute guidance exactly when a file beneath it is read.
+//   • Opening a workspace evaluates the reserved `applies-to: "."` target for
+//     every project store mounted by the cwd and selected profile. This happens
+//     while the first-message bearings are assembled, so workspace-wide context
+//     arrives before the task rather than waiting for an arbitrary first file.
+//
+// `read-when` remains an additional OR trigger over a read markdown file's own
+// frontmatter. It does not replace `applies-to`: every non-none file-read rung
+// still declares its path boundary explicitly.
+//
+// Every candidate renders at its own fileReadVisibility rung. Explicit routing
+// is the whole on-read model, so directory INDEX ceilings remain a boot-catalog
+// concern and do not cap a deliberately matched document.
+import { realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, matchesGlob, parse, relative, sep } from 'node:path';
+import { CRTR_DIR_NAME } from '../../types.js';
+import { pathExists, readText, walkFiles } from '../fs-utils.js';
+import { parseFrontmatterGeneric } from '../frontmatter.js';
+import { evalCondition } from '../predicate.js';
+import { listAllMemoryDocs, listProjectMemoryDocs } from '../memory-resolver.js';
+import { userScopeRoot } from '../scope.js';
+import { displayName } from './ceiling.js';
+import { gatePasses } from './gate.js';
+import { normalizeDocName, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, resolveDocName } from './schema.js';
+import { cachedSubstrateDocs } from './session-cache.js';
+const JUNK_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', '.cache', '.yalc']);
+function realpathOrSelf(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+function attr(s) {
+    return s
+        .replace(/&/g, '&')
+        .replace(/"/g, '"')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
+function gitRootOf(p) {
+    let d = p;
+    const root = parse(d).root;
+    while (true) {
+        if (pathExists(`${d}${sep}.git`))
+            return d;
+        if (d === root)
+            return null;
+        const parent = dirname(d);
+        if (parent === d)
+            return null;
+        d = parent;
+    }
+}
+function disp(p) {
+    const root = gitRootOf(p);
+    if (!root)
+        return p;
+    const rel = relative(root, p);
+    return rel === '' ? '.' : rel;
+}
+function isJunkAncestor(dir) {
+    return dir.split(sep).some((segment) => JUNK_DIRS.has(segment));
+}
+function owningRootOf(doc) {
+    const parts = doc.path.split(sep);
+    const idx = parts.lastIndexOf(CRTR_DIR_NAME);
+    if (idx <= 0)
+        return null;
+    return parts.slice(0, idx).join(sep) || sep;
+}
+function loadProjectDoc(file, memoryDir) {
+    try {
+        const raw = relative(memoryDir, file)
+            .replace(/\.md$/i, '')
+            .split(sep)
+            .join('/');
+        const fallbackName = normalizeDocName(raw);
+        if (fallbackName === '')
+            return null;
+        const { data, body } = parseFrontmatterGeneric(readText(file));
+        const schema = parseSubstrateFrontmatter(data);
+        if (schema === null)
+            return null;
+        return {
+            ...schema,
+            name: resolveDocName(data, fallbackName),
+            scope: 'project',
+            path: file,
+            body,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function safeWalkMarkdown(dir) {
+    try {
+        return walkFiles(dir, (name) => name.toLowerCase().endsWith('.md'));
+    }
+    catch {
+        return [];
+    }
+}
+/** Project docs from every workspace store enclosing the read file. This is a
+ * discovery walk only: each returned doc must still match an explicit trigger. */
+function enclosingProjectDocs(absReadFile) {
+    const docs = [];
+    const seen = new Set();
+    const home = realpathOrSelf(homedir());
+    const userRoot = realpathOrSelf(userScopeRoot());
+    const fsRoot = parse(absReadFile).root;
+    let dir = dirname(absReadFile);
+    while (true) {
+        if (dir !== home && dir !== userRoot && !isJunkAncestor(dir)) {
+            const memoryDir = `${dir}${sep}${CRTR_DIR_NAME}${sep}memory`;
+            if (pathExists(memoryDir)) {
+                for (const file of safeWalkMarkdown(memoryDir)) {
+                    const real = realpathOrSelf(file);
+                    if (seen.has(real))
+                        continue;
+                    seen.add(real);
+                    const doc = loadProjectDoc(file, memoryDir);
+                    if (doc !== null)
+                        docs.push(doc);
+                }
+            }
+        }
+        if (dir === home || dir === fsRoot)
+            break;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return docs;
+}
+function resolvedDocs() {
+    try {
+        return cachedSubstrateDocs(listAllMemoryDocs, parseSubstrateDoc);
+    }
+    catch {
+        return [];
+    }
+}
+function dedupeByPhysicalPath(docs) {
+    const seen = new Set();
+    const out = [];
+    for (const doc of docs) {
+        const real = realpathOrSelf(doc.path);
+        if (seen.has(real))
+            continue;
+        seen.add(real);
+        out.push(doc);
+    }
+    return out;
+}
+function globMatches(glob, absReadFile, owningRoot) {
+    const targets = [absReadFile, basename(absReadFile)];
+    if (owningRoot !== null)
+        targets.push(relative(owningRoot, absReadFile));
+    return targets.some((target) => {
+        try {
+            return matchesGlob(target, glob);
+        }
+        catch {
+            return false;
+        }
+    });
+}
+function readFileFrontmatter(absReadFile) {
+    if (!/\.(md|mdx|markdown)$/i.test(absReadFile))
+        return {};
+    try {
+        return parseFrontmatterGeneric(readText(absReadFile)).data ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+function matchesReadEvent(doc, absReadFile, readFrontmatter) {
+    const pathMatch = doc.appliesTo?.some((glob) => globMatches(glob, absReadFile, owningRootOf(doc))) === true;
+    const frontmatterMatch = doc.readWhen !== undefined &&
+        Object.keys(readFrontmatter).length > 0 &&
+        evalCondition(doc.readWhen, readFrontmatter);
+    return pathMatch || frontmatterMatch;
+}
+function envelopeName(doc) {
+    const displayed = displayName(doc.name);
+    if (displayed !== '')
+        return displayed;
+    const root = owningRootOf(doc);
+    return root === null ? doc.name : basename(root);
+}
+function renderDocEnvelope(doc) {
+    const rung = doc.fileReadVisibility;
+    if (rung === 'none')
+        return null;
+    let body = '';
+    if (rung === 'content')
+        body = doc.body.trim();
+    else if (rung === 'preview')
+        body = previewLine(doc);
+    const attrs = `kind="${attr(doc.kind)}" name="${attr(envelopeName(doc))}" src="${attr(disp(doc.path))}"`;
+    return body === '' ? `<memory ${attrs} />` : `<memory ${attrs}>\n${body}\n</memory>`;
+}
+function renderCandidates(subject, docs, seen) {
+    const rendered = [];
+    for (const doc of docs) {
+        const real = realpathOrSelf(doc.path);
+        if (seen.has(real))
+            continue;
+        try {
+            if (!gatePasses(doc, subject))
+                continue;
+            const block = renderDocEnvelope(doc);
+            if (block === null)
+                continue;
+            seen.add(real);
+            rendered.push(block);
+        }
+        catch {
+            continue;
+        }
+    }
+    return rendered.length === 0
+        ? ''
+        : `<auto-loaded-context>\n${rendered.join('\n')}\n</auto-loaded-context>`;
+}
+/** Surface docs matched by a successful read tool call using the caller-supplied
+ * daemon snapshot subject. */
+export function renderOnReadDocsForSubject(subject, readFilePath, seen = new Set()) {
+    const absReadFile = realpathOrSelf(readFilePath);
+    const readFrontmatter = readFileFrontmatter(absReadFile);
+    const docs = dedupeByPhysicalPath([...enclosingProjectDocs(absReadFile), ...resolvedDocs()])
+        .filter((doc) => realpathOrSelf(doc.path) !== absReadFile)
+        .filter((doc) => matchesReadEvent(doc, absReadFile, readFrontmatter));
+    return renderCandidates(subject, docs, seen);
+}
+/** Workspace boot docs using the snapshot's cwd/profile instead of a canvas
+ * lookup. */
+export function renderWorkspaceOpenDocsForSubject(subject, cwd, profileId) {
+    let docs;
+    try {
+        docs = listProjectMemoryDocs(cwd, profileId)
+            .map(parseSubstrateDoc)
+            .filter((doc) => doc !== null);
+    }
+    catch {
+        return '';
+    }
+    docs = dedupeByPhysicalPath(docs)
+        .filter((doc) => doc.appliesTo?.some((glob) => glob.trim() === '.') === true)
+        .sort((a, b) => {
+        const aRoot = owningRootOf(a) ?? '';
+        const bRoot = owningRootOf(b) ?? '';
+        const depth = aRoot.split(sep).filter(Boolean).length - bRoot.split(sep).filter(Boolean).length;
+        return depth || aRoot.localeCompare(bRoot) || a.path.localeCompare(b.path);
+    });
+    return renderCandidates(subject, docs, new Set());
+}

package/dist/core/termrender/termrender.js

@@ -458,7 +458,37 @@ function wrap(text, maxWidth) {
     return out.length > 0 ? out : [''];
 }
 // ── Render surface ───────────────────────────────────────────────────────────
-const _bodyCache = new Map();
+/** Simple bounded LRU cache: evicts the oldest (first) entry when maxEntries is reached.
+ *  Preserves Map's insertion-order invariant so iteration order is LRU order. */
+class BoundedLRUCache {
+    map = new Map();
+    maxEntries;
+    constructor(maxEntries) {
+        this.maxEntries = maxEntries;
+    }
+    get(key) {
+        if (!this.map.has(key))
+            return undefined;
+        const value = this.map.get(key);
+        // Move to end (most recently used) by delete+re-insert.
+        this.map.delete(key);
+        this.map.set(key, value);
+        return value;
+    }
+    set(key, value) {
+        // Remove if exists to update order.
+        if (this.map.has(key)) {
+            this.map.delete(key);
+        }
+        else if (this.map.size >= this.maxEntries) {
+            // Evict oldest (first entry in iteration order).
+            const firstKey = this.map.keys().next().value;
+            this.map.delete(firstKey);
+        }
+        this.map.set(key, value);
+    }
+}
+const _bodyCache = new BoundedLRUCache(20);
 /** Render markdown to terminal lines via the pinned binary; plaintext fallback. */
 export function renderMarkdown(md, width) {
     const key = `${md}\0${width}`;
@@ -618,7 +648,7 @@ function fallbackDocWithMap(md, width) {
     });
     return { lines, rows, spans, blocks };
 }
-const _mapCache = new Map();
+const _mapCache = new BoundedLRUCache(20);
 /** Render markdown with a row→source-line map via the pinned binary
  *  (`doc render --line-map`); plaintext paragraph-block fallback. */
 export function renderMarkdownWithMap(md, width) {

package/dist/core/user-settings.d.ts

@@ -1,10 +1,17 @@
 import type { ScopeConfig } from '../types.js';
+/**
+ * Which settings destination owns a preference row. Every settings-surface row
+ * must name one, so a new preference cannot be added without deciding where a
+ * human finds it.
+ */
+export type UserSettingGroup = 'display' | 'panes' | 'updates';
 export interface UserSettingDefinition<Key extends string = string> {
     key: Key;
     label: string;
     description: string;
     valueConstraint: string;
     applies: string;
+    group: UserSettingGroup;
     order: number;
     format: (config: ScopeConfig) => string;
     cycle: (config: ScopeConfig, delta: number) => void;
@@ -40,6 +47,7 @@ export declare const CONFIG_SETTINGS_COVERAGE: {
                 description: string;
                 valueConstraint: string;
                 applies: string;
+                group: "updates";
                 order: number;
                 format: (config: ScopeConfig) => "notify" | "apply" | "off";
                 cycle: (config: ScopeConfig, delta: number) => void;
@@ -51,6 +59,7 @@ export declare const CONFIG_SETTINGS_COVERAGE: {
                 description: string;
                 valueConstraint: string;
                 applies: string;
+                group: "updates";
                 order: number;
                 format: (config: ScopeConfig) => "notify" | "apply" | "off";
                 cycle: (config: ScopeConfig, delta: number) => void;
@@ -62,6 +71,7 @@ export declare const CONFIG_SETTINGS_COVERAGE: {
                 description: string;
                 valueConstraint: string;
                 applies: string;
+                group: "updates";
                 order: number;
                 format: (config: ScopeConfig) => string;
                 cycle: (config: ScopeConfig, delta: number) => void;
@@ -77,6 +87,7 @@ export declare const CONFIG_SETTINGS_COVERAGE: {
             description: string;
             valueConstraint: string;
             applies: string;
+            group: "panes";
             order: number;
             format: (config: ScopeConfig) => string;
             cycle: (config: ScopeConfig, delta: number) => void;
@@ -91,6 +102,7 @@ export declare const CONFIG_SETTINGS_COVERAGE: {
             description: string;
             valueConstraint: string;
             applies: string;
+            group: "panes";
             order: number;
             format: (config: ScopeConfig) => "on" | "off";
             cycle: (config: ScopeConfig) => void;
@@ -109,6 +121,7 @@ export declare const CONFIG_SETTINGS_COVERAGE: {
             description: string;
             valueConstraint: string;
             applies: string;
+            group: "display";
             order: number;
             format: (config: ScopeConfig) => "on" | "off";
             cycle: (config: ScopeConfig) => void;
@@ -127,6 +140,7 @@ export declare const CONFIG_SETTINGS_COVERAGE: {
             description: string;
             valueConstraint: string;
             applies: string;
+            group: "display";
             order: number;
             format: (config: ScopeConfig) => "on" | "off";
             cycle: (config: ScopeConfig) => void;
@@ -145,6 +159,7 @@ export declare const CONFIG_SETTINGS_COVERAGE: {
             description: string;
             valueConstraint: string;
             applies: string;
+            group: "display";
             order: number;
             format: (config: ScopeConfig) => "on" | "off" | "follow tmux";
             cycle: (config: ScopeConfig, delta: number) => void;
@@ -159,6 +174,7 @@ export declare const CONFIG_SETTINGS_COVERAGE: {
             description: string;
             valueConstraint: string;
             applies: string;
+            group: "display";
             order: number;
             format: (config: ScopeConfig) => string;
             cycle: (config: ScopeConfig, delta: number) => void;
@@ -173,6 +189,7 @@ export declare const CONFIG_SETTINGS_COVERAGE: {
             description: string;
             valueConstraint: string;
             applies: string;
+            group: "display";
             order: number;
             format: (config: ScopeConfig) => "user" | "none" | "agent" | "both";
             cycle: (config: ScopeConfig, delta: number) => void;
@@ -187,6 +204,7 @@ export declare const CONFIG_SETTINGS_COVERAGE: {
             description: string;
             valueConstraint: string;
             applies: string;
+            group: "display";
             order: number;
             format: (config: ScopeConfig) => "on" | "off";
             cycle: (config: ScopeConfig) => void;
@@ -201,6 +219,7 @@ export declare const CONFIG_SETTINGS_COVERAGE: {
             description: string;
             valueConstraint: string;
             applies: string;
+            group: "display";
             order: number;
             format: (config: ScopeConfig) => "on" | "off";
             cycle: (config: ScopeConfig) => void;
@@ -215,6 +234,7 @@ export declare const CONFIG_SETTINGS_COVERAGE: {
             description: string;
             valueConstraint: string;
             applies: string;
+            group: "display";
             order: number;
             format: (config: ScopeConfig) => "on" | "off";
             cycle: (config: ScopeConfig) => void;
@@ -256,6 +276,8 @@ export declare const CONFIG_SETTINGS_COVERAGE: {
 };
 /** The exhaustive top-level key list used by config persistence and help. */
 export declare const SCOPE_CONFIG_KEYS: (keyof ScopeConfig)[];
-/** The single row registry shared by `sys setup` and `sys config set`. */
+/** The single row registry shared by `sys settings` and `sys config set`. */
 export declare const USER_SETTINGS: readonly UserSettingDefinition[];
 export declare function findUserSetting(key: string): UserSettingDefinition | undefined;
+/** The rows one settings destination owns, in registry order. */
+export declare function userSettingsInGroup(group: UserSettingGroup): readonly UserSettingDefinition[];