@crouter/api 0.3.386 → 0.3.388

package/dist/core/keybindings/catalog.d.ts

@@ -0,0 +1,18 @@
+import type { BindingDefinition, SafetyRequirement } from './types.js';
+import type { AttachBindingId, AttachMenuBindingId } from './attach-control.js';
+type TmuxMenuAction = 'open' | 'attach' | 'show' | 'view-settings' | 'provider-options' | 'fold-tools' | 'metadata' | 'promote' | 'demote-mode' | 'resume' | 'fork' | 'demote' | 'make-resident' | 'detach' | 'close-subtree' | 'background-bash' | 'file-review' | 'pin' | 'reload-viewer' | 'recap' | 'context' | 'context-admin' | 'providers' | 'plugins' | 'analytics' | 'graph' | 'focus-manager' | 'copy-id' | 'issues';
+type TmuxMenuEntryAction = Exclude<TmuxMenuAction, 'open' | 'attach'> | `issue.${'idea' | 'bug'}`;
+type GraphAction = 'down' | 'up' | 'first' | 'last' | 'collapse-or-manager' | 'expand-or-child' | 'focus' | 'revive' | 'focus-manager' | 'close-subtree' | 'dismiss';
+type BrowseAction = 'quit' | 'down' | 'up' | 'first' | 'last' | 'expand-or-child' | 'collapse-or-parent' | 'toggle-fold' | 'tab-next' | 'tab-previous' | `tab.${1 | 2 | 3 | 4 | 5}` | 'close-subtree' | 'confirm-close' | 'sort' | 'scope' | 'profile' | 'residents' | 'preview' | 'report' | 'pin' | 'search' | 'revive-now' | 'focus' | 'focus-background' | 'yank-id';
+type ProfileMenuAction = 'up' | 'down' | 'select' | 'accept-default' | 'abort' | `slot.${1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9}` | 'create' | 'search-existing' | 'use-root' | 'set-default' | 'add-directory' | 'unpin' | 'manage';
+type SetupAction = 'cancel' | 'tab-next' | 'tab-previous' | 'open' | 'list-down' | 'list-up' | 'toggle' | 'details' | 'advance' | 'cell-previous' | 'cell-next';
+type SetupKeybindingAction = 'edit' | 'commit-edit' | 'cancel-edit' | 'unbind' | 'reset-row' | 'reset-all' | 'save' | 'discard' | 'page-up' | 'page-down' | 'filter' | 'filter-delete' | 'filter-clear';
+type SetupModelsAction = 'open' | 'commit' | 'cancel' | 'scope-next';
+export type BindingId = `crtr.tmux.menu.${TmuxMenuAction}` | `crtr.tmux.menu.issue.${'idea' | 'bug'}` | AttachMenuBindingId | `crtr.tmux.menu-global.${TmuxMenuEntryAction}` | `crtr.tmux.node.${'next' | 'previous'}` | 'crtr.tmux.inbox.toggle' | `crtr.attach.scroll.${'up' | 'down' | 'page-up' | 'page-down' | 'live'}` | 'crtr.attach.mouse.toggle' | 'crtr.attach.copy.message' | 'crtr.attach.help.toggle' | `crtr.attach.search.${'next' | 'previous' | 'edit' | 'close'}` | AttachBindingId | `crtr.graph.${GraphAction}` | `crtr.graph.confirm.${'accept' | 'cancel'}` | `crtr.inspector.${'force-quit' | 'down' | 'up' | 'section-next' | 'section-prev' | 'page-down' | 'page-up' | 'toggle-detail' | 'cancel-item' | 'open-log' | 'confirm' | 'dismiss' | 'retarget' | 'refresh' | 'quit'}` | `crtr.browse.${BrowseAction}` | `crtr.browse.search.${'cancel' | 'commit' | 'delete' | 'quit'}` | `crtr.profile.menu.${ProfileMenuAction}` | `crtr.profile.search.${'up' | 'down' | 'pick' | 'back' | 'delete' | 'abort'}` | `crtr.setup.${SetupAction}` | `crtr.setup.confirm.${'accept' | 'back'}` | `crtr.setup.keybindings.${SetupKeybindingAction}` | `crtr.setup.models.${SetupModelsAction}`;
+export declare const BINDING_CATALOG: readonly [BindingDefinition<"crtr.tmux.menu.open">, BindingDefinition<"crtr.tmux.menu.attach">, ...(BindingDefinition<BindingId> | BindingDefinition<"crtr.tmux.node.next"> | BindingDefinition<"crtr.tmux.node.previous"> | BindingDefinition<"crtr.tmux.inbox.toggle"> | BindingDefinition<"crtr.attach.scroll.up"> | BindingDefinition<"crtr.attach.scroll.down"> | BindingDefinition<"crtr.attach.scroll.page-up"> | BindingDefinition<"crtr.attach.scroll.page-down"> | BindingDefinition<"crtr.attach.scroll.live"> | BindingDefinition<"crtr.attach.mouse.toggle"> | BindingDefinition<"crtr.attach.copy.message"> | BindingDefinition<"crtr.attach.search.next"> | BindingDefinition<"crtr.attach.search.previous"> | BindingDefinition<"crtr.attach.search.edit"> | BindingDefinition<"crtr.attach.search.close"> | BindingDefinition<"crtr.graph.down"> | BindingDefinition<"crtr.graph.up"> | BindingDefinition<"crtr.graph.first"> | BindingDefinition<"crtr.graph.last"> | BindingDefinition<"crtr.graph.collapse-or-manager"> | BindingDefinition<"crtr.graph.expand-or-child"> | BindingDefinition<"crtr.graph.focus"> | BindingDefinition<"crtr.graph.revive"> | BindingDefinition<"crtr.graph.focus-manager"> | BindingDefinition<"crtr.graph.close-subtree"> | BindingDefinition<"crtr.graph.dismiss"> | BindingDefinition<"crtr.graph.confirm.accept"> | BindingDefinition<"crtr.graph.confirm.cancel"> | BindingDefinition<"crtr.inspector.force-quit"> | BindingDefinition<"crtr.inspector.down"> | BindingDefinition<"crtr.inspector.up"> | BindingDefinition<"crtr.inspector.section-next"> | BindingDefinition<"crtr.inspector.section-prev"> | BindingDefinition<"crtr.inspector.page-down"> | BindingDefinition<"crtr.inspector.page-up"> | BindingDefinition<"crtr.inspector.toggle-detail"> | BindingDefinition<"crtr.inspector.cancel-item"> | BindingDefinition<"crtr.inspector.open-log"> | BindingDefinition<"crtr.inspector.confirm"> | BindingDefinition<"crtr.inspector.dismiss"> | BindingDefinition<"crtr.inspector.retarget"> | BindingDefinition<"crtr.inspector.refresh"> | BindingDefinition<"crtr.inspector.quit"> | BindingDefinition<"crtr.browse.quit"> | BindingDefinition<"crtr.browse.down"> | BindingDefinition<"crtr.browse.up"> | BindingDefinition<"crtr.browse.first"> | BindingDefinition<"crtr.browse.last"> | BindingDefinition<"crtr.browse.expand-or-child"> | BindingDefinition<"crtr.browse.collapse-or-parent"> | BindingDefinition<"crtr.browse.toggle-fold"> | BindingDefinition<"crtr.browse.tab-next"> | BindingDefinition<"crtr.browse.tab-previous"> | BindingDefinition<"crtr.browse.tab.2" | "crtr.browse.tab.5" | "crtr.browse.tab.4" | "crtr.browse.tab.3" | "crtr.browse.tab.1"> | BindingDefinition<"crtr.browse.close-subtree"> | BindingDefinition<"crtr.browse.confirm-close"> | BindingDefinition<"crtr.browse.sort"> | BindingDefinition<"crtr.browse.scope"> | BindingDefinition<"crtr.browse.profile"> | BindingDefinition<"crtr.browse.residents"> | BindingDefinition<"crtr.browse.preview"> | BindingDefinition<"crtr.browse.report"> | BindingDefinition<"crtr.browse.pin"> | BindingDefinition<"crtr.browse.search"> | BindingDefinition<"crtr.browse.revive-now"> | BindingDefinition<"crtr.browse.focus"> | BindingDefinition<"crtr.browse.focus-background"> | BindingDefinition<"crtr.browse.yank-id"> | BindingDefinition<"crtr.browse.search.cancel"> | BindingDefinition<"crtr.browse.search.commit"> | BindingDefinition<"crtr.browse.search.delete"> | BindingDefinition<"crtr.browse.search.quit"> | BindingDefinition<"crtr.profile.menu.up"> | BindingDefinition<"crtr.profile.menu.down"> | BindingDefinition<"crtr.profile.menu.select"> | BindingDefinition<"crtr.profile.menu.accept-default"> | BindingDefinition<"crtr.profile.menu.abort"> | BindingDefinition<"crtr.profile.menu.slot.2" | "crtr.profile.menu.slot.5" | "crtr.profile.menu.slot.4" | "crtr.profile.menu.slot.7" | "crtr.profile.menu.slot.3" | "crtr.profile.menu.slot.6" | "crtr.profile.menu.slot.1" | "crtr.profile.menu.slot.8" | "crtr.profile.menu.slot.9">)[], BindingDefinition<"crtr.profile.menu.create">, BindingDefinition<"crtr.profile.menu.search-existing">, BindingDefinition<"crtr.profile.menu.use-root">, BindingDefinition<"crtr.profile.menu.set-default">, BindingDefinition<"crtr.profile.menu.add-directory">, BindingDefinition<"crtr.profile.menu.unpin">, BindingDefinition<"crtr.profile.menu.manage">, BindingDefinition<"crtr.profile.search.up">, BindingDefinition<"crtr.profile.search.down">, BindingDefinition<"crtr.profile.search.pick">, BindingDefinition<"crtr.profile.search.back">, BindingDefinition<"crtr.profile.search.delete">, BindingDefinition<"crtr.profile.search.abort">, BindingDefinition<"crtr.setup.cancel">, BindingDefinition<"crtr.setup.tab-next">, BindingDefinition<"crtr.setup.tab-previous">, BindingDefinition<"crtr.setup.open">, BindingDefinition<"crtr.setup.list-down">, BindingDefinition<"crtr.setup.list-up">, BindingDefinition<"crtr.setup.toggle">, BindingDefinition<"crtr.setup.details">, BindingDefinition<"crtr.setup.advance">, BindingDefinition<"crtr.setup.confirm.accept">, BindingDefinition<"crtr.setup.confirm.back">, BindingDefinition<"crtr.setup.keybindings.edit">, BindingDefinition<"crtr.setup.keybindings.commit-edit">, BindingDefinition<"crtr.setup.keybindings.cancel-edit">, BindingDefinition<"crtr.setup.keybindings.unbind">, BindingDefinition<"crtr.setup.keybindings.reset-row">, BindingDefinition<"crtr.setup.keybindings.reset-all">, BindingDefinition<"crtr.setup.keybindings.save">, BindingDefinition<"crtr.setup.keybindings.discard">, BindingDefinition<"crtr.setup.keybindings.page-up">, BindingDefinition<"crtr.setup.keybindings.page-down">, BindingDefinition<"crtr.setup.keybindings.filter">, BindingDefinition<"crtr.setup.keybindings.filter-delete">, BindingDefinition<"crtr.setup.keybindings.filter-clear">, BindingDefinition<"crtr.setup.cell-previous">, BindingDefinition<"crtr.setup.cell-next">, BindingDefinition<"crtr.setup.models.open">, BindingDefinition<"crtr.setup.models.scope-next">, BindingDefinition<"crtr.setup.models.commit">, BindingDefinition<"crtr.setup.models.cancel">];
+export declare const BINDING_IDS: ReadonlySet<string>;
+/** True for an action whose direct gesture is handled inside an attach viewer.
+ *  Tmux menu selectors and root shortcuts are chrome, not pane input. */
+export declare function isAttachPaneBinding(definition: BindingDefinition): boolean;
+export declare const SAFETY_REQUIREMENTS: readonly SafetyRequirement[];
+export {};

package/dist/core/keybindings/catalog.js

@@ -0,0 +1,257 @@
+function binding(id, group, name, description, defaults, inputKind, contexts, safety, pair) {
+    return Object.freeze({
+        id,
+        group,
+        name,
+        description,
+        defaults: Object.freeze([...defaults]),
+        inputKind,
+        contexts: Object.freeze([...contexts]),
+        ...(safety === undefined ? {} : { safety }),
+        ...(pair === undefined ? {} : { pair: Object.freeze({ ...pair }) }),
+    });
+}
+const b = binding;
+function menuEntry(action, name, description, defaults, contexts) {
+    const menuId = `crtr.tmux.menu.${action}`;
+    const globalId = `crtr.tmux.menu-global.${action}`;
+    return [
+        b(menuId, 'Global tmux', name, description, defaults, 'tmux-menu-selector', contexts, undefined, { field: 'menu', pairedId: globalId }),
+        b(globalId, 'Global tmux', name, description, [], 'tmux-global-action', ['tmux.root'], undefined, { field: 'global', pairedId: menuId }),
+    ];
+}
+function attachEntry(menuId, actionId, name, description, 
+// Empty hides the row from the attach submenu while the action stays bindable
+// and reachable by its direct gesture — file review lives on the top-level menu.
+menuDefaults, directDefaults) {
+    return [
+        b(menuId, 'Attach', name, description, menuDefaults, 'tmux-menu-selector', ['tmux.menu.attach'], undefined, { field: 'menu', pairedId: actionId }),
+        b(actionId, 'Attach', name, description, directDefaults, 'host-global', ATTACH_CONTEXTS, undefined, { field: 'direct', pairedId: menuId }),
+    ];
+}
+const ATTACH_CONTEXTS = ['attach', 'graph', 'graph.confirm'];
+const SETUP_CANCEL_CONTEXTS = [
+    'setup.login', 'setup.list', 'setup.input', 'setup.keybindings',
+    'setup.keybindings.edit', 'setup.keybindings.filter', 'setup.models',
+];
+const SETUP_TAB_CONTEXTS = ['setup.login', 'setup.list', 'setup.keybindings', 'setup.models'];
+export const BINDING_CATALOG = Object.freeze([
+    b('crtr.tmux.menu.open', 'Global tmux', 'Open crouter menu', 'Open the crouter action menu.', ['alt+c'], 'host-global', ['tmux.root']),
+    b('crtr.tmux.menu.attach', 'Global tmux', 'Attach actions', 'Open the attach-viewer action submenu.', ['a'], 'tmux-menu-selector', ['tmux.menu']),
+    ...menuEntry('promote', 'Promote to orchestrator', 'Promote the focused node to orchestrator — it holds a roadmap and delegates.', ['o'], ['tmux.menu']),
+    ...menuEntry('demote-mode', 'Demote to base node', 'Demote the focused orchestrator back to a base node — hands-on again in its own window, no roadmap to drive.', ['shift+o'], ['tmux.menu']),
+    ...menuEntry('resume', 'Find node', 'Open the canvas navigator and go to the chosen node.', ['/'], ['tmux.menu']),
+    ...menuEntry('fork', 'Fork node', 'Fork the focused node into an independent idle root.', ['f'], ['tmux.menu']),
+    ...menuEntry('demote', 'Demote to terminal', 'Demote the focused node to terminal — it keeps running, owes a final up the spine, and reaps when done.', ['d'], ['tmux.menu']),
+    ...menuEntry('make-resident', 'Make resident', 'Flip the focused node to resident — interactable, never forced to submit a final, and wakeable while attached or awaiting something live.', ['shift+r'], ['tmux.menu']),
+    ...menuEntry('detach', 'Demote and close viewer', 'Demote the focused node and close its viewer; its broker keeps running off-screen.', ['shift+d'], ['tmux.menu']),
+    ...menuEntry('close-subtree', 'Close subtree', 'Close the focused node and its subtree.', ['x'], ['tmux.menu']),
+    ...menuEntry('background-bash', 'Background running bash', 'Hand the focused node’s running bash command to its background job system.', ['b'], ['tmux.menu']),
+    ...menuEntry('file-review', 'Review a file', 'Open a line-anchored review of a file named in the transcript.', ['v'], ['tmux.menu']),
+    ...menuEntry('pin', 'Pin conversation', 'Pin or unpin this conversation in the canvas navigator.', ['p'], ['tmux.menu']),
+    ...menuEntry('show', 'Inspect node', 'Open the focused node’s inspection menu.', ['i'], ['tmux.menu']),
+    ...menuEntry('view-settings', 'Display settings', 'Open the viewer display-settings menu.', ['z'], ['tmux.menu']),
+    ...menuEntry('fold-tools', 'Fold finished tool calls', 'Fold every finished tool call in the transcript to its single call line.', ['f'], ['tmux.menu.view-settings']),
+    ...menuEntry('metadata', 'Show metadata', 'Show the focused node’s metadata dossier.', ['m'], ['tmux.menu.show']),
+    ...menuEntry('context', 'Browse context', 'Browse the focused node context.', ['c'], ['tmux.menu.show']),
+    ...menuEntry('providers', 'Open settings', 'Open the crouter settings panel.', [','], ['tmux.menu']),
+    // Next to the settings comma: the same page, opened on its provider-options
+    // destination.
+    ...menuEntry('provider-options', 'Provider options', 'Open provider options — how an authenticated provider serves your turns, including Codex fast mode.', ['.'], ['tmux.menu']),
+    // j and k steer the menu cursor, so no selector may claim either.
+    ...menuEntry('plugins', 'Browse plugins', 'Open the crouter plugin browser.', ['l'], ['tmux.menu']),
+    ...menuEntry('analytics', 'Analytics', 'Open the Analytics page: how agents worked in the last 24 hours or 7 days.', ['shift+a'], ['tmux.menu']),
+    // Lowercase c opens the create submenu, so the context surface takes the
+    // shifted form of the word its command tree already uses.
+    ...menuEntry('context-admin', 'Context surface', 'Open the context surface: which documents each event delivers, and the surfaces, gates, and caps that decide it.', ['shift+c'], ['tmux.menu']),
+    ...menuEntry('graph', 'Canvas graph', 'Open the canvas graph.', ['g'], ['tmux.menu']),
+    ...menuEntry('focus-manager', 'Go to manager', 'Focus this node’s manager.', ['h'], ['tmux.menu']),
+    ...menuEntry('copy-id', 'Copy node id', 'Copy the focused node id to the system clipboard.', ['y'], ['tmux.menu']),
+    ...menuEntry('reload-viewer', 'Reload viewer', 'Respawn this pane’s viewer onto the current runtime generation.', ['r'], ['tmux.menu']),
+    ...menuEntry('recap', 'Generate recap', 'Generate the focused node’s Goal and State recap and refresh its generated title.', ['s'], ['tmux.menu']),
+    ...menuEntry('issues', 'Open create menu', 'Open the create submenu.', ['c'], ['tmux.menu']),
+    ...menuEntry('issue.idea', 'Create idea', 'Create an idea issue.', ['i'], ['tmux.menu.issue']),
+    ...menuEntry('issue.bug', 'Create bug', 'Create a bug issue.', ['b'], ['tmux.menu.issue']),
+    b('crtr.tmux.node.next', 'Global tmux', 'Next node', 'Focus the next canvas node.', ['alt+]'], 'host-global', ['tmux.root']),
+    b('crtr.tmux.node.previous', 'Global tmux', 'Previous node', 'Focus the previous canvas node.', ['alt+['], 'host-global', ['tmux.root']),
+    b('crtr.tmux.inbox.toggle', 'Global tmux', 'Toggle inbox', 'Open or close the human inbox in the focused viewer.', ['alt+i'], 'host-global', ['tmux.root']),
+    ...attachEntry('crtr.tmux.menu.attach.detach', 'crtr.attach.detach', 'Detach', 'Detach from the node.', ['d'], ['ctrl+d']),
+    ...attachEntry('crtr.tmux.menu.attach.clear-or-detach', 'crtr.attach.clear-or-detach', 'Clear input (cancel agent on repeat)', 'Clear the input; press again within a second to cancel the running agent turn. Detach lives on its own binding.', ['c'], ['ctrl+c']),
+    ...attachEntry('crtr.tmux.menu.attach.graph.toggle', 'crtr.attach.graph.toggle', 'Toggle graph', 'Open or close the graph overlay.', ['g'], ['alt+g']),
+    ...attachEntry('crtr.tmux.menu.attach.help.toggle', 'crtr.attach.help.toggle', 'Help', 'Open the attach help overlay.', ['?'], ['alt+shift+k']),
+    ...attachEntry('crtr.tmux.menu.attach.inbox.toggle', 'crtr.attach.inbox.toggle', 'Toggle inbox', 'Open or close the human inbox surface in this viewer.', ['i'], []),
+    ...attachEntry('crtr.tmux.menu.attach.inbox-strip', 'crtr.attach.inbox-strip', 'Pending requests', 'Jump to the pending human-request strip at the top of the pane.', ['u'], ['alt+u']),
+    ...attachEntry('crtr.tmux.menu.attach.model-ladder.next', 'crtr.attach.model-ladder.next', 'Next model', 'Move to the next model ladder rung.', [']'], ['alt+m']),
+    ...attachEntry('crtr.tmux.menu.attach.model-ladder.previous', 'crtr.attach.model-ladder.previous', 'Previous model', 'Move to the previous model ladder rung.', ['['], ['alt+shift+m']),
+    ...attachEntry('crtr.tmux.menu.attach.command.inspect', 'crtr.attach.command.inspect', 'Inspect loaded command', 'Open the loaded slash command’s expanded prompt.', ['h'], ['alt+shift+h']),
+    ...attachEntry('crtr.tmux.menu.attach.file-review', 'crtr.attach.file-review', 'Review a file', 'Open a line-anchored review of a file named in the transcript.', [], ['alt+shift+r']),
+    ...attachEntry('crtr.tmux.menu.attach.profile-files', 'crtr.attach.profile-files', 'Search profile files', 'Fuzzy-match path segments across the node family’s working directories, their context directories (files), profile projects and the profile’s own directory; Ctrl+Y copies a selected path.', ['f'], ['ctrl+f']),
+    ...attachEntry('crtr.tmux.menu.attach.search', 'crtr.attach.search', 'Search transcript', 'Search the transcript as it is currently displayed — folded tool output is not searched until it is unfolded.', ['/'], ['alt+/']),
+    ...attachEntry('crtr.tmux.menu.attach.whip', 'crtr.attach.whip', 'Whip agent', 'Interrupt the agent and send a playful command.', ['w'], []),
+    b('crtr.attach.scroll.up', 'Attach', 'Scroll up', 'Scroll the transcript one line up.', ['shift+up'], 'terminal', ATTACH_CONTEXTS),
+    b('crtr.attach.scroll.down', 'Attach', 'Scroll down', 'Scroll the transcript one line down.', ['shift+down'], 'terminal', ATTACH_CONTEXTS),
+    b('crtr.attach.scroll.page-up', 'Attach', 'Scroll page up', 'Scroll the transcript one page up.', ['pageup'], 'terminal', ATTACH_CONTEXTS),
+    b('crtr.attach.scroll.page-down', 'Attach', 'Scroll page down', 'Scroll the transcript one page down.', ['pagedown'], 'terminal', ATTACH_CONTEXTS),
+    b('crtr.attach.scroll.live', 'Attach', 'Return to live', 'Return the transcript to the live bottom.', ['shift+end'], 'terminal', ATTACH_CONTEXTS),
+    b('crtr.attach.mouse.toggle', 'Attach', 'Toggle mouse wheel scrolling', 'Toggle mouse wheel scrolling on or off.', ['alt+shift+o'], 'terminal', ATTACH_CONTEXTS),
+    b('crtr.attach.copy.message', 'Attach', 'Copy visible message', 'Copy the newest message visible in the transcript viewport.', ['alt+shift+y'], 'terminal', ATTACH_CONTEXTS),
+    b('crtr.attach.search.next', 'Attach', 'Next match', 'Move to the next transcript search match.', ['n'], 'terminal', ['attach.search']),
+    b('crtr.attach.search.previous', 'Attach', 'Previous match', 'Move to the previous transcript search match.', ['shift+n'], 'terminal', ['attach.search']),
+    b('crtr.attach.search.edit', 'Attach', 'Edit query', 'Return to editing the transcript search query.', ['/'], 'terminal', ['attach.search']),
+    b('crtr.attach.search.close', 'Attach', 'Close search', 'Leave transcript search and clear its highlights.', ['escape'], 'terminal', ['attach.search'], 'dismiss-modal'),
+    b('crtr.graph.down', 'GRAPH', 'Move down', 'Move to the next graph row.', ['j', 'down'], 'terminal', ['graph']),
+    b('crtr.graph.up', 'GRAPH', 'Move up', 'Move to the previous graph row.', ['k', 'up'], 'terminal', ['graph']),
+    b('crtr.graph.first', 'GRAPH', 'First row', 'Move to the first graph row.', ['g'], 'terminal', ['graph']),
+    b('crtr.graph.last', 'GRAPH', 'Last row', 'Move to the last graph row.', ['shift+g'], 'terminal', ['graph']),
+    b('crtr.graph.collapse-or-manager', 'GRAPH', 'Collapse or manager', 'Collapse a node or move to its manager.', ['h', 'left'], 'terminal', ['graph']),
+    b('crtr.graph.expand-or-child', 'GRAPH', 'Expand or child', 'Expand a node or move to its child.', ['l', 'right'], 'terminal', ['graph']),
+    b('crtr.graph.focus', 'GRAPH', 'Focus node', 'Focus the selected node.', ['enter'], 'terminal', ['graph']),
+    b('crtr.graph.revive', 'GRAPH', 'Revive node', 'Revive and open the selected dormant node.', ['r'], 'terminal', ['graph']),
+    b('crtr.graph.focus-manager', 'GRAPH', 'Focus manager', 'Focus the selected node manager.', ['m'], 'terminal', ['graph']),
+    b('crtr.graph.close-subtree', 'GRAPH', 'Close subtree', 'Ask to close the selected subtree.', ['x'], 'terminal', ['graph']),
+    b('crtr.graph.dismiss', 'GRAPH', 'Dismiss graph', 'Close the graph overlay.', ['escape'], 'terminal', ['graph'], 'dismiss-modal'),
+    b('crtr.graph.confirm.accept', 'GRAPH', 'Confirm close', 'Confirm closing the selected subtree.', ['y'], 'terminal', ['graph.confirm']),
+    b('crtr.graph.confirm.cancel', 'GRAPH', 'Cancel close', 'Cancel closing the selected subtree.', ['n', 'escape'], 'terminal', ['graph.confirm'], 'dismiss-modal'),
+    b('crtr.inspector.force-quit', 'Inspector', 'Force quit Inspector', 'Immediately leave the Inspector.', ['ctrl+c'], 'host-global', ['inspector'], 'leave-screen'),
+    b('crtr.inspector.down', 'Inspector', 'Move down', 'Move the Inspector selection or scroll cursor down.', ['j', 'down'], 'terminal', ['inspector']),
+    b('crtr.inspector.up', 'Inspector', 'Move up', 'Move the Inspector selection or scroll cursor up.', ['k', 'up'], 'terminal', ['inspector']),
+    b('crtr.inspector.section-next', 'Inspector', 'Next section', 'Move to the next Inspector section.', ['tab'], 'terminal', ['inspector']),
+    b('crtr.inspector.section-prev', 'Inspector', 'Previous section', 'Move to the previous Inspector section.', ['shift+tab'], 'terminal', ['inspector']),
+    b('crtr.inspector.page-down', 'Inspector', 'Page down', 'Scroll the Inspector detail body down.', ['ctrl+d', 'pagedown'], 'terminal', ['inspector']),
+    b('crtr.inspector.page-up', 'Inspector', 'Page up', 'Scroll the Inspector detail body up.', ['ctrl+u', 'pageup'], 'terminal', ['inspector']),
+    b('crtr.inspector.toggle-detail', 'Inspector', 'Toggle item detail', 'Expand or collapse the selected cron or background job.', ['enter'], 'terminal', ['inspector']),
+    b('crtr.inspector.cancel-item', 'Inspector', 'Cancel selected item', 'Arm cancellation for the selected cron, or stopping for the selected background job.', ['x'], 'terminal', ['inspector']),
+    b('crtr.inspector.open-log', 'Inspector', 'Open job log', 'Follow the selected background job’s log in a new tmux window.', ['o'], 'terminal', ['inspector']),
+    b('crtr.inspector.confirm', 'Inspector', 'Confirm action', 'Confirm the armed Inspector action.', ['y'], 'terminal', ['inspector']),
+    b('crtr.inspector.dismiss', 'Inspector', 'Dismiss action', 'Dismiss an Inspector confirmation or banner.', ['escape'], 'terminal', ['inspector'], 'dismiss-modal'),
+    b('crtr.inspector.retarget', 'Inspector', 'Retarget', 'Inspect the selected cron anchor or creator node.', ['t'], 'terminal', ['inspector']),
+    b('crtr.inspector.refresh', 'Inspector', 'Refresh', 'Refresh the Inspector now.', ['g', 'r'], 'terminal', ['inspector']),
+    b('crtr.inspector.quit', 'Inspector', 'Quit', 'Leave the Inspector.', ['q'], 'terminal', ['inspector'], 'leave-screen'),
+    ...browseBindings(),
+    ...profileBindings(),
+    ...setupBindings(),
+]);
+function browseBindings() {
+    const nav = 'browse';
+    return [
+        b('crtr.browse.quit', 'Browse and pickers', 'Quit browse', 'Leave canvas browse.', ['q', 'escape', 'ctrl+c'], 'terminal', [nav], 'leave-screen'),
+        b('crtr.browse.down', 'Browse and pickers', 'Move down', 'Move to the next row.', ['j', 'down'], 'terminal', [nav]),
+        b('crtr.browse.up', 'Browse and pickers', 'Move up', 'Move to the previous row.', ['k', 'up'], 'terminal', [nav]),
+        b('crtr.browse.first', 'Browse and pickers', 'First row', 'Move to the first row.', ['g'], 'terminal', [nav]),
+        b('crtr.browse.last', 'Browse and pickers', 'Last row', 'Move to the last row.', ['shift+g'], 'terminal', [nav]),
+        b('crtr.browse.expand-or-child', 'Browse and pickers', 'Expand or child', 'Expand a row or move to its child.', ['l', 'right'], 'terminal', [nav]),
+        b('crtr.browse.collapse-or-parent', 'Browse and pickers', 'Collapse or parent', 'Collapse a row or move to its parent.', ['h', 'left'], 'terminal', [nav]),
+        b('crtr.browse.toggle-fold', 'Browse and pickers', 'Toggle fold', 'Toggle the selected fold.', ['space'], 'terminal', [nav]),
+        b('crtr.browse.tab-next', 'Browse and pickers', 'Next tab', 'Select the next browse tab.', ['tab', ']'], 'terminal', [nav]),
+        b('crtr.browse.tab-previous', 'Browse and pickers', 'Previous tab', 'Select the previous browse tab.', ['shift+tab', '['], 'terminal', [nav]),
+        ...[1, 2, 3, 4, 5].map((slot) => b(`crtr.browse.tab.${slot}`, 'Browse and pickers', `Tab ${slot}`, `Select browse tab ${slot}.`, [`${slot}`], 'terminal', [nav])),
+        b('crtr.browse.close-subtree', 'Browse and pickers', 'Close subtree', 'Ask to close the selected subtree.', ['x'], 'terminal', [nav]),
+        b('crtr.browse.confirm-close', 'Browse and pickers', 'Confirm close', 'Confirm closing the selected subtree.', ['y'], 'terminal', ['browse.confirm']),
+        b('crtr.browse.sort', 'Browse and pickers', 'Change sort', 'Change the browse sort.', ['s'], 'terminal', [nav]),
+        b('crtr.browse.scope', 'Browse and pickers', 'Change scope', 'Toggle the browse cwd scope.', ['c'], 'terminal', [nav]),
+        b('crtr.browse.profile', 'Browse and pickers', 'Toggle profile', 'Toggle the browse profile scope.', ['shift+p'], 'terminal', [nav]),
+        b('crtr.browse.residents', 'Browse and pickers', 'Toggle residents', 'Toggle resident display.', ['r'], 'terminal', [nav]),
+        b('crtr.browse.preview', 'Browse and pickers', 'Toggle preview', 'Toggle the preview panel.', ['v'], 'terminal', [nav]),
+        b('crtr.browse.report', 'Browse and pickers', 'Toggle report', 'Swap the preview panel between the conversation and the node\'s newest report.', ['shift+v'], 'terminal', [nav]),
+        b('crtr.browse.pin', 'Browse and pickers', 'Pin node', 'Star or unstar the selected node.', ['p'], 'terminal', [nav]),
+        b('crtr.browse.search', 'Browse and pickers', 'Search', 'Open browse search.', ['/'], 'terminal', [nav]),
+        b('crtr.browse.revive-now', 'Browse and pickers', 'Revive now', 'Revive the selected node now.', ['shift+k'], 'terminal', [nav]),
+        b('crtr.browse.focus', 'Browse and pickers', 'Focus node', 'Focus the selected node.', ['enter', 'o'], 'terminal', [nav]),
+        b('crtr.browse.focus-background', 'Browse and pickers', 'Focus node (keep browsing)', 'Focus the selected node without leaving the navigator.', ['shift+o'], 'terminal', [nav]),
+        b('crtr.browse.yank-id', 'Browse and pickers', 'Yank node id', 'Copy the selected node id to the system clipboard.', ['y'], 'terminal', [nav]),
+        b('crtr.browse.search.cancel', 'Browse and pickers', 'Cancel search', 'Cancel browse search.', ['escape'], 'terminal', ['browse.search'], 'dismiss-modal'),
+        b('crtr.browse.search.commit', 'Browse and pickers', 'Commit search', 'Apply browse search.', ['enter'], 'terminal', ['browse.search']),
+        b('crtr.browse.search.delete', 'Browse and pickers', 'Delete search text', 'Delete the previous search character.', ['backspace'], 'terminal', ['browse.search']),
+        b('crtr.browse.search.quit', 'Browse and pickers', 'Quit browse', 'Leave canvas browse from search.', ['ctrl+c'], 'terminal', ['browse.search'], 'leave-screen'),
+    ];
+}
+function profileBindings() {
+    const menu = 'profile.menu';
+    const search = 'profile.search';
+    return [
+        b('crtr.profile.menu.up', 'Profiles', 'Move up', 'Move to the previous profile.', ['k', 'up'], 'terminal', [menu]),
+        b('crtr.profile.menu.down', 'Profiles', 'Move down', 'Move to the next profile.', ['j', 'down'], 'terminal', [menu]),
+        b('crtr.profile.menu.select', 'Profiles', 'Select profile', 'Select the highlighted profile.', ['enter'], 'terminal', [menu]),
+        b('crtr.profile.menu.accept-default', 'Profiles', 'Accept default', 'Accept the default profile.', ['escape'], 'terminal', [menu], 'leave-screen'),
+        b('crtr.profile.menu.abort', 'Profiles', 'Abort', 'Leave profile selection.', ['ctrl+c'], 'terminal', [menu], 'leave-screen'),
+        ...[1, 2, 3, 4, 5, 6, 7, 8, 9].map((slot) => b(`crtr.profile.menu.slot.${slot}`, 'Profiles', `Profile slot ${slot}`, `Select profile slot ${slot}.`, [`${slot}`], 'terminal', [menu])),
+        b('crtr.profile.menu.create', 'Profiles', 'Create profile', 'Create a profile.', ['c'], 'terminal', [menu]),
+        b('crtr.profile.menu.search-existing', 'Profiles', 'Search profiles', 'Search existing profiles.', ['s'], 'terminal', [menu]),
+        b('crtr.profile.menu.use-root', 'Profiles', 'Use root profile', 'Use the root profile.', ['r'], 'terminal', [menu]),
+        b('crtr.profile.menu.set-default', 'Profiles', 'Set default', 'Set the selected profile as default.', ['d'], 'terminal', [menu]),
+        b('crtr.profile.menu.add-directory', 'Profiles', 'Add directory', 'Add a directory to the profile.', ['a'], 'terminal', [menu]),
+        b('crtr.profile.menu.unpin', 'Profiles', 'Unpin directory', 'Unpin the selected directory.', ['u'], 'terminal', [menu]),
+        b('crtr.profile.menu.manage', 'Profiles', 'Manage profiles', 'Open the profiles settings page in a popup.', ['v'], 'terminal', [menu]),
+        b('crtr.profile.search.up', 'Profiles', 'Move up', 'Move to the previous search result.', ['up', 'ctrl+p'], 'terminal', [search]),
+        b('crtr.profile.search.down', 'Profiles', 'Move down', 'Move to the next search result.', ['down', 'ctrl+n'], 'terminal', [search]),
+        b('crtr.profile.search.pick', 'Profiles', 'Pick profile', 'Pick the highlighted profile.', ['enter'], 'terminal', [search]),
+        b('crtr.profile.search.back', 'Profiles', 'Back', 'Return to profile selection.', ['escape'], 'terminal', [search], 'leave-screen'),
+        b('crtr.profile.search.delete', 'Profiles', 'Delete filter text', 'Delete the previous filter character.', ['backspace'], 'terminal', [search]),
+        b('crtr.profile.search.abort', 'Profiles', 'Abort', 'Leave profile search.', ['ctrl+c'], 'terminal', [search], 'leave-screen'),
+    ];
+}
+function setupBindings() {
+    return [
+        b('crtr.setup.cancel', 'Setup', 'Cancel setup', 'Leave the setup wizard.', ['q', 'ctrl+c', 'ctrl+d'], 'terminal', SETUP_CANCEL_CONTEXTS, 'leave-screen'),
+        b('crtr.setup.tab-next', 'Setup', 'Next tab', 'Select the next setup tab.', ['tab', 'right'], 'terminal', SETUP_TAB_CONTEXTS),
+        b('crtr.setup.tab-previous', 'Setup', 'Previous tab', 'Select the previous setup tab.', ['shift+tab', 'left'], 'terminal', SETUP_TAB_CONTEXTS),
+        b('crtr.setup.open', 'Setup', 'Open', 'Open the selected setup item.', ['enter'], 'terminal', ['setup.login']),
+        b('crtr.setup.list-down', 'Setup', 'Move down', 'Move to the next setup item.', ['j', 'down'], 'terminal', ['setup.list', 'setup.models', 'setup.models.dimension-picker', 'setup.models.route-form']),
+        b('crtr.setup.list-up', 'Setup', 'Move up', 'Move to the previous setup item.', ['k', 'up'], 'terminal', ['setup.list', 'setup.models', 'setup.models.dimension-picker', 'setup.models.route-form']),
+        b('crtr.setup.toggle', 'Setup', 'Toggle', 'Toggle the selected setup item.', ['space'], 'terminal', ['setup.list', 'setup.keybindings']),
+        b('crtr.setup.details', 'Setup', 'Show details', 'Show details for the selected item.', ['?'], 'terminal', ['setup.list']),
+        b('crtr.setup.advance', 'Setup', 'Advance', 'Advance the setup flow.', ['enter'], 'terminal', ['setup.list']),
+        b('crtr.setup.confirm.accept', 'Setup', 'Confirm', 'Accept the setup confirmation.', ['y', 'enter'], 'terminal', ['setup.confirm', 'setup.models.confirm']),
+        b('crtr.setup.confirm.back', 'Setup', 'Go back', 'Cancel the setup confirmation.', ['n', 'escape', 'q'], 'terminal', ['setup.confirm', 'setup.models.confirm'], 'dismiss-modal'),
+        b('crtr.setup.keybindings.edit', 'Setup', 'Edit binding', 'Edit the selected binding.', ['enter'], 'terminal', ['setup.keybindings']),
+        b('crtr.setup.keybindings.commit-edit', 'Setup', 'Commit edit', 'Commit the active binding edit.', ['enter'], 'terminal', ['setup.keybindings.edit']),
+        b('crtr.setup.keybindings.cancel-edit', 'Setup', 'Cancel edit', 'Cancel the active binding edit.', ['escape'], 'terminal', ['setup.keybindings.edit'], 'dismiss-modal'),
+        b('crtr.setup.keybindings.unbind', 'Setup', 'Unbind', 'Disable the selected binding.', ['delete'], 'terminal', ['setup.keybindings']),
+        b('crtr.setup.keybindings.reset-row', 'Setup', 'Reset binding', 'Reset the selected binding.', ['r'], 'terminal', ['setup.keybindings']),
+        b('crtr.setup.keybindings.reset-all', 'Setup', 'Reset all bindings', 'Reset all bindings to defaults.', ['shift+r'], 'terminal', ['setup.keybindings']),
+        b('crtr.setup.keybindings.save', 'Setup', 'Save bindings', 'Save keybinding changes.', ['s'], 'terminal', ['setup.keybindings'], 'save-keybindings'),
+        b('crtr.setup.keybindings.discard', 'Setup', 'Discard changes', 'Discard keybinding changes.', ['escape'], 'terminal', ['setup.keybindings'], 'leave-screen'),
+        b('crtr.setup.keybindings.page-up', 'Setup', 'Page up', 'Move up one keybinding page.', ['pageup'], 'terminal', ['setup.keybindings', 'setup.keybindings.edit']),
+        b('crtr.setup.keybindings.page-down', 'Setup', 'Page down', 'Move down one keybinding page.', ['pagedown'], 'terminal', ['setup.keybindings', 'setup.keybindings.edit']),
+        b('crtr.setup.keybindings.filter', 'Setup', 'Filter bindings', 'Open the keybinding filter.', ['/'], 'terminal', ['setup.keybindings']),
+        b('crtr.setup.keybindings.filter-delete', 'Setup', 'Delete filter text', 'Delete the previous filter character.', ['backspace'], 'terminal', ['setup.keybindings.filter']),
+        b('crtr.setup.keybindings.filter-clear', 'Setup', 'Clear filter', 'Clear the keybinding filter.', ['escape'], 'terminal', ['setup.keybindings.filter'], 'dismiss-modal'),
+        b('crtr.setup.cell-previous', 'Setup', 'Previous field', 'Select the previous field or setup table cell.', ['h'], 'terminal', ['setup.models', 'setup.keybindings']),
+        b('crtr.setup.cell-next', 'Setup', 'Next field', 'Select the next field or setup table cell.', ['l'], 'terminal', ['setup.models', 'setup.keybindings']),
+        b('crtr.setup.models.open', 'Setup', 'Edit model', 'Edit the selected model cell or route field.', ['enter'], 'terminal', ['setup.models', 'setup.models.route-form']),
+        b('crtr.setup.models.scope-next', 'Setup', 'Next model config scope', 'Edit the next applicable user, profile, or project config.', ['s'], 'terminal', ['setup.models']),
+        b('crtr.setup.models.commit', 'Setup', 'Commit pick', 'Commit the provider, strength, model, or thinking-level pick.', ['enter'], 'terminal', ['setup.models.picker', 'setup.models.dimension-picker']),
+        b('crtr.setup.models.cancel', 'Setup', 'Cancel pick', 'Cancel the model picker or route form.', ['escape'], 'terminal', ['setup.models.picker', 'setup.models.dimension-picker', 'setup.models.route-form'], 'dismiss-modal'),
+    ];
+}
+export const BINDING_IDS = new Set(BINDING_CATALOG.map((definition) => definition.id));
+/** True for an action whose direct gesture is handled inside an attach viewer.
+ *  Tmux menu selectors and root shortcuts are chrome, not pane input. */
+export function isAttachPaneBinding(definition) {
+    return definition.contexts.includes('attach')
+        && (definition.inputKind === 'terminal' || definition.inputKind === 'host-global');
+}
+export const SAFETY_REQUIREMENTS = Object.freeze([
+    { context: 'graph', capability: 'dismiss-modal' },
+    { context: 'graph.confirm', capability: 'dismiss-modal' },
+    { context: 'inspector', capability: 'leave-screen' },
+    { context: 'inspector', capability: 'dismiss-modal' },
+    { context: 'attach.search', capability: 'dismiss-modal' },
+    { context: 'browse', capability: 'leave-screen' },
+    { context: 'browse.search', capability: 'dismiss-modal' },
+    { context: 'profile.menu', capability: 'leave-screen' },
+    { context: 'profile.search', capability: 'leave-screen' },
+    { context: 'setup.login', capability: 'leave-screen' },
+    { context: 'setup.list', capability: 'leave-screen' },
+    { context: 'setup.input', capability: 'leave-screen' },
+    { context: 'setup.confirm', capability: 'dismiss-modal' },
+    { context: 'setup.keybindings', capability: 'leave-screen' },
+    { context: 'setup.keybindings', capability: 'save-keybindings' },
+    { context: 'setup.keybindings.edit', capability: 'dismiss-modal' },
+    { context: 'setup.keybindings.filter', capability: 'dismiss-modal' },
+    { context: 'setup.models', capability: 'leave-screen' },
+    { context: 'setup.models.picker', capability: 'dismiss-modal' },
+    { context: 'setup.models.dimension-picker', capability: 'dismiss-modal' },
+    { context: 'setup.models.route-form', capability: 'dismiss-modal' },
+    { context: 'setup.models.confirm', capability: 'dismiss-modal' },
+]);

package/dist/core/keybindings/types.d.ts

@@ -0,0 +1,42 @@
+export type BindingInputKind = 'terminal' | 'tmux-sequence' | 'tmux-menu-selector' | 'tmux-global-action' | 'host-global';
+export interface BindingPair {
+    readonly field: 'menu' | 'global' | 'direct';
+    readonly pairedId: string;
+}
+export type BindingSafetyCapability = 'dismiss-modal' | 'leave-screen' | 'save-keybindings';
+export interface BindingDefinition<Id extends string = string> {
+    readonly id: Id;
+    readonly group: string;
+    readonly name: string;
+    readonly description: string;
+    readonly defaults: readonly string[];
+    readonly inputKind: BindingInputKind;
+    readonly contexts: readonly string[];
+    readonly safety?: BindingSafetyCapability;
+    readonly pair?: BindingPair;
+}
+export interface EffectiveBinding<Id extends string = string> {
+    readonly definition: BindingDefinition<Id>;
+    readonly gestures: readonly string[];
+    readonly source: 'default' | 'user';
+}
+export type KeybindingDiagnosticCode = 'invalid-keybindings' | 'unknown-binding' | 'invalid-override' | 'collision' | 'unreachable';
+export interface KeybindingDiagnostic {
+    readonly severity: 'error';
+    readonly code: KeybindingDiagnosticCode;
+    readonly bindingId?: string;
+    readonly relatedBindingIds?: readonly string[];
+    readonly offendingValue: unknown;
+    readonly message: string;
+}
+export interface SafetyRequirement {
+    readonly context: string;
+    readonly capability: BindingSafetyCapability;
+}
+export interface BindingResolution<Id extends string = string> {
+    readonly bindings: ReadonlyMap<Id, EffectiveBinding<Id>>;
+    readonly diagnostics: readonly KeybindingDiagnostic[];
+    get(id: Id): EffectiveBinding<Id>;
+    gestures(id: Id): readonly string[];
+}
+export type SparseKeybindingOverrides<Id extends string = string> = Partial<Record<Id, string[]>>;

package/dist/core/keybindings/types.js

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

package/dist/core/layout.d.ts

@@ -0,0 +1,26 @@
+export declare const LAYOUT_VERSION = "1";
+/** CRTR_HOME names the volume root, not the canvas records directory. */
+export declare function layoutRoot(): string;
+export declare function runtimeRoot(): string;
+export declare function userRoot(): string;
+export declare function appsRoot(): string;
+export declare function secretsDir(): string;
+export declare function profileSpace(app: string, id: string): {
+    memory: string;
+    env: string;
+    home: string;
+};
+export declare function socketDir(): string;
+export declare function layoutVersionFile(): string;
+export declare function userFilesRoot(): string;
+export declare function appSpace(app: string): {
+    root: string;
+    memory: string;
+    conversations: string;
+    nodes: string;
+    files: string;
+    home: string;
+};
+/** A missing version on an occupied volume is never initialized by daemon startup. */
+export declare function layoutNeedsMigration(): boolean;
+export declare function initializeEmptyLayout(): void;

package/dist/core/layout.js

@@ -0,0 +1,94 @@
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { homedir, userInfo } from 'node:os';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
+import { envHomeOverride } from '../shared/env.js';
+import { readConfig } from './config.js';
+export const LAYOUT_VERSION = '1';
+/** CRTR_HOME names the volume root, not the canvas records directory. */
+export function layoutRoot() {
+    const root = resolve(envHomeOverride() || (process.platform === 'linux' ? '/' : join(homedir(), '.crouter')));
+    if (runningUnderNodeTest() && root === accountLayoutRoot()) {
+        throw new Error(`refusing to use the account's real crouter root ${root} from a node --test process; point CRTR_HOME (not only HOME) at a temporary directory`);
+    }
+    return root;
+}
+/** `node --test` marks each isolated test child with NODE_TEST_CONTEXT and runs
+ *  `--test-isolation=none` files with `--test` in execArgv. Production crtr
+ *  processes carry neither. */
+function runningUnderNodeTest() {
+    return process.env['NODE_TEST_CONTEXT'] !== undefined || process.execArgv.includes('--test');
+}
+/** The real account's `~/.crouter`, resolved from the passwd entry so a test
+ *  that relocates HOME still names the root it must not touch. A node's shell
+ *  inherits CRTR_HOME pointing here, so relocating HOME alone leaves every
+ *  scoped-state write aimed at the person's live settings. */
+let accountLayoutRootCache;
+function accountLayoutRoot() {
+    if (accountLayoutRootCache === undefined) {
+        try {
+            accountLayoutRootCache = resolve(userInfo().homedir, '.crouter');
+        }
+        catch {
+            accountLayoutRootCache = null;
+        }
+    }
+    return accountLayoutRootCache;
+}
+export function runtimeRoot() { return join(layoutRoot(), 'runtime'); }
+export function userRoot() { return join(layoutRoot(), 'user'); }
+export function appsRoot() { return join(layoutRoot(), 'apps'); }
+export function secretsDir() { return join(runtimeRoot(), 'secrets'); }
+export function profileSpace(app, id) {
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*-[0-9a-f]{8}$/.test(id))
+        throw new Error(`invalid profile id: ${id}`);
+    const space = appSpace(app);
+    return {
+        memory: join(space.memory, 'profiles', id),
+        env: join(secretsDir(), 'env', basename(space.root), id),
+        home: space.home,
+    };
+}
+export function socketDir() { return process.platform === 'linux' ? '/run/crtr' : runtimeRoot(); }
+export function layoutVersionFile() { return join(runtimeRoot(), 'layout'); }
+export function userFilesRoot() {
+    const path = readConfig('user').paths?.user_files ?? (process.platform === 'linux' ? join(userRoot(), 'files') : dirname(layoutRoot()));
+    if (!isAbsolute(path))
+        throw new Error('paths.user_files must be absolute');
+    return resolve(path);
+}
+export function appSpace(app) {
+    const id = app.startsWith('app:') ? app.slice(4) : app;
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(id) || id === '.' || id === '..')
+        throw new Error(`invalid app id: ${app}`);
+    const root = join(appsRoot(), id);
+    return { root, memory: join(root, 'memory'), conversations: join(root, 'conversations'), nodes: join(root, 'nodes'), files: join(root, 'files'), home: join(root, 'home') };
+}
+/** A missing version on an occupied volume is never initialized by daemon startup. */
+export function layoutNeedsMigration() {
+    if (process.env['CRTR_LAYOUT_REFUSE'] === '1')
+        return true;
+    if (existsSync(layoutVersionFile())) {
+        if (readFileSync(layoutVersionFile(), 'utf8').trim() !== LAYOUT_VERSION)
+            throw new Error('unsupported runtime layout version');
+        return false;
+    }
+    const root = layoutRoot();
+    const volume = process.platform === 'linux' && root === '/' && existsSync('/volume') ? '/volume' : root;
+    if (existsSync(join(volume, 'canvas')) || existsSync(join(volume, 'canvas.db')))
+        return true;
+    // A moved canvas.db without a layout version is an unfinished offline
+    // migration. Node records move before the DB, so the old or moved DB always
+    // accompanies them; entrypoint-created directories are a fresh volume.
+    return existsSync(join(runtimeRoot(), 'canvas.db'));
+}
+export function initializeEmptyLayout() {
+    if (layoutNeedsMigration())
+        throw new Error('layout_migration_required');
+    for (const dir of [runtimeRoot(), userRoot(), appsRoot(), secretsDir()])
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    mkdirSync(socketDir(), { recursive: true, mode: 0o755 });
+    if (process.platform === 'linux' && (statSync(socketDir()).mode & 0o777) !== 0o755)
+        throw new Error('launcher socket directory must be mode 0755');
+    if (!existsSync(layoutVersionFile()))
+        writeFileSync(layoutVersionFile(), `${LAYOUT_VERSION}\n`, { flag: 'wx', mode: 0o600 });
+}

package/dist/core/locked-file.d.ts

@@ -0,0 +1,27 @@
+export type LockResult<T> = {
+    result: T;
+    next?: string;
+};
+/** Throws if this lock was compromised (stolen/expired) since acquisition. Callers that write
+ *  from INSIDE the critical section must call it immediately before that write, because the
+ *  post-`fn` check cannot un-write a file the callback already replaced. */
+export type LockHeldGuard = () => void;
+export type LockedFilePublish = (next: string) => void;
+export interface LockedFileBackend {
+    withLockAsync<T>(fn: (current: string | undefined, assertLockHeld: LockHeldGuard, publish: LockedFilePublish) => Promise<LockResult<T>>): Promise<T>;
+    /** The current whole-file contents, or undefined when the file does not exist yet.
+     *  Lock-free: every writer replaces the file by atomic rename. */
+    readUnlocked(): string | undefined;
+}
+/** A 0600 JSON file guarded by a cross-process `proper-lockfile` lock on its own path. */
+export declare class LockedJsonFile implements LockedFileBackend {
+    private readonly path;
+    private readonly durable;
+    private readonly initialContent;
+    constructor(path: string, durable?: boolean, initialContent?: string);
+    readUnlocked(): string | undefined;
+    private ensureFile;
+    /** Acquire the lock without blocking the event loop, keeping every read-modify-write
+     *  callback on the same asynchronous path. */
+    withLockAsync<T>(fn: (current: string | undefined, assertLockHeld: LockHeldGuard, publish: LockedFilePublish) => Promise<LockResult<T>>): Promise<T>;
+}