@crouton-kit/crouter 0.3.82 → 0.3.84

package/dist/commands/human/shared.d.ts

@@ -1,79 +1,39 @@
-import { type DetachResult } from '../../core/spawn.js';
+import type { CompletionHandler } from '@crouton-kit/humanloop';
 export declare const DECK_SCHEMA_HINT: string;
+/**
+ * Crouter's private per-interaction record. Reduced to the delivery essentials:
+ * the mode `_deliver` dispatches on and the bridge node id it delivers back to.
+ * Humanloop owns every public request/result/output path (deck.json,
+ * response.json, review.json); crouter never records pane ids or output paths.
+ */
 export interface RunRecord {
     mode: 'ask' | 'notify' | 'review';
     job_id?: string;
-    file?: string;
-    output?: string;
-    /** tmux pane id of the detached TUI, recorded so `human cancel` can kill it. */
-    pane_id?: string;
-    /** tmux pane id of a review's live termrender render pane, so cancel/finish can clear it. */
-    render_pane_id?: string;
 }
 export declare function resolveMaxPanes(): number;
-export declare function pickPlacement(targetPane?: string): 'split-h' | 'new-window';
-/**
- * The tmux pane the humanloop TUI should open BESIDE so a PERSON actually sees
- * it. A prompt raised by a canvas node must NOT land in the backstage `crtr`
- * session (the holding ground for un-watched node panes) — it lands in the
- * session the user is watching that node's graph in:
- *   1. node prompt (CRTR_NODE_ID set) → the HIGHEST FOCUSED node of its graph
- *      (`graphSurfaceTarget`, the focused node closest to the graph root): split
- *      beside it, in the session/window the user already has it open in.
- *   2. nothing in the graph on screen (or a dead focus pane), or a bare-shell
- *      prompt → the user's currently-attached pane (`attachedClientPane`).
- *   3. neither resolvable → undefined (tmux falls back to the caller pane).
- * The TUI lands in the right place but NEVER switches the user's session/window
- * (no switch-client / select-window; new-window opens `-d`). They see it when
- * they look at the node they are already watching.
- */
-export declare function resolveHumanTarget(): string | undefined;
-/**
- * Open the detached humanloop `_run` pane for an interaction dir, ROUTED to the
- * session the user is watching (`resolveHumanTarget`). The single spawn path
- * behind ask/review (`spawnHumanJob`) and notify. `detached: true` keeps
- * the user's view put — the prompt lands beside the watched node without
- * jumping their session/window. `jobId`, when given, is injected as CRTR_JOB_ID.
- */
-export declare function detachHumanTui(idir: string, cwd: string, jobId?: string): DetachResult;
-export declare function runCmd(dir: string): string;
-export declare function followUpResult(_jobId: string): string;
-export declare function followUpDrain(_jobId: string): string;
 /**
- * Road sign for a spawned `human review`. It is a non-blocking kickoff, so the
- * text steers the caller to stop rather than wait, verify, or re-present: the
- * pane is already live and tracks the file, and the comments arrive via the
- * inbox/wake when the human submits.
- */
-export declare function followUpReview(_jobId: string): string;
-/**
- * Spawn the detached `_run` pane that drives the humanloop TUI for this node.
- * Returns whether the pane spawned and the follow_up road sign. Degrades to the
- * inbox-drain follow_up when not in tmux / spawn fails — kickoffs are
- * intentionally non-fatal off-tmux.
+ * The direct-exec completion handler humanloop runs when a crouter ticket
+ * resolves, fed the completion event on stdin. The argv is absolute and
+ * PATH/cwd-independent — never a `crtr` shell string — and, critically, must
+ * actually EXECUTE in both crouter contexts:
+ *
+ * - Built (`dist/cli.js` present): `node <abs>/dist/cli.js human _deliver`.
+ * - Dev/tsx (only `src/cli.ts` on disk): plain `node` cannot run the `.ts`
+ *   entry — its mandatory `.js`-extension ESM imports have no `.js` sibling on
+ *   disk, so Node's type-stripping fails at the first relative import. So we
+ *   register tsx's ESM loader first (`node --import <abs tsx/esm> src/cli.ts …`),
+ *   with the tsx entry resolved to an absolute file URL so the handler stays
+ *   cwd-independent when humanloop invokes it. tsx is necessarily present here
+ *   because crouter itself is running under it.
  *
- * Completion routing needs no bookkeeping here: the human node was created
- * under the asking node as its parent (spawnNode auto-subscribes the parent),
- * so the `pushFinal` the `_run` worker emits — for ask AND review —
- * fans the answer straight into the asking node's inbox. The pane id is recorded
- * on run.json (not returned) so `human cancel` can later kill the TUI.
+ * Throws loudly when neither entry exists rather than registering an argv that
+ * humanloop would retry forever.
  */
-export declare function spawnHumanJob(jobId: string, idir: string, cwd: string): {
-    spawned: boolean;
-    follow_up: string;
-};
+export declare function crouterDeliverHandler(): CompletionHandler;
 /**
- * Best-effort kill of a humanloop worker pane. SAFETY-CRITICAL: a malformed or
- * empty `-t` target makes tmux fall back to the CALLER's current pane, so a bad
- * paneId could kill the agent's own pi pane (and, if it is the last pane, the
- * whole session). This refuses to kill anything that is not provably the worker:
- *
- *   1. paneId must be a real tmux pane id (`%<n>`) — never an empty/odd string.
- *   2. The pane's start command must contain `verify` (the interaction dir, which
- *      humanloop bakes into the worker's `CRTR_HUMAN_DIR=... crtr human _run`
- *      launch). A shell (`zsh -l`) or the agent's pi never matches, so we can
- *      only ever kill the exact worker we spawned for this job.
- *
- * Returns true only when a matching pane was found and killed. Never throws.
+ * Register the per-cwd interaction root with humanloop as owner `crouter`,
+ * attaching the `_deliver` completion handler. Idempotent for owner `crouter`
+ * (refreshes the handler), and creates/canonicalizes the root. Returns the
+ * canonical root path humanloop submissions must be rooted at.
  */
-export declare function killPane(paneId: string, verify: string): boolean;
+export declare function registerCrouterRoot(cwd: string): string;

package/dist/commands/human/shared.js

@@ -1,9 +1,10 @@
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { existsSync } from 'node:fs';
 import { readConfig } from '../../core/config.js';
-import { spawnSync } from 'node:child_process';
-import { join } from 'node:path';
-import { atomicWriteJson, readJson } from '@crouton-kit/humanloop';
-import { countPanesInWindow, spawnAndDetach, shellQuote, attachedClientPane, paneAlive, } from '../../core/spawn.js';
-import { graphSurfaceTarget } from '../../core/runtime/placement.js';
+import { interactionsRoot } from '../../core/artifact.js';
+import { registerInboxRoot } from '@crouton-kit/humanloop';
 export const DECK_SCHEMA_HINT = 'Deck must match the humanloop deck schema: {title?, ' +
     'source?:{sessionName?,askedBy?,blockedSince?}, interactions:[{id, ' +
     'title (short ≤~4-word topic — the thing being decided, not the decision), ' +
@@ -16,127 +17,43 @@ export const DECK_SCHEMA_HINT = 'Deck must match the humanloop deck schema: {tit
 export function resolveMaxPanes() {
     return readConfig('user').max_panes_per_window;
 }
-export function pickPlacement(targetPane) {
-    return countPanesInWindow(targetPane) >= resolveMaxPanes() ? 'new-window' : 'split-h';
-}
-/**
- * The tmux pane the humanloop TUI should open BESIDE so a PERSON actually sees
- * it. A prompt raised by a canvas node must NOT land in the backstage `crtr`
- * session (the holding ground for un-watched node panes) — it lands in the
- * session the user is watching that node's graph in:
- *   1. node prompt (CRTR_NODE_ID set) → the HIGHEST FOCUSED node of its graph
- *      (`graphSurfaceTarget`, the focused node closest to the graph root): split
- *      beside it, in the session/window the user already has it open in.
- *   2. nothing in the graph on screen (or a dead focus pane), or a bare-shell
- *      prompt → the user's currently-attached pane (`attachedClientPane`).
- *   3. neither resolvable → undefined (tmux falls back to the caller pane).
- * The TUI lands in the right place but NEVER switches the user's session/window
- * (no switch-client / select-window; new-window opens `-d`). They see it when
- * they look at the node they are already watching.
- */
-export function resolveHumanTarget() {
-    const nodeId = process.env['CRTR_NODE_ID'];
-    if (nodeId !== undefined && nodeId !== '') {
-        const f = graphSurfaceTarget(nodeId);
-        if (f !== null && f.pane !== null && paneAlive(f.pane))
-            return f.pane;
-    }
-    return attachedClientPane() ?? undefined;
-}
 /**
- * Open the detached humanloop `_run` pane for an interaction dir, ROUTED to the
- * session the user is watching (`resolveHumanTarget`). The single spawn path
- * behind ask/review (`spawnHumanJob`) and notify. `detached: true` keeps
- * the user's view put — the prompt lands beside the watched node without
- * jumping their session/window. `jobId`, when given, is injected as CRTR_JOB_ID.
- */
-export function detachHumanTui(idir, cwd, jobId) {
-    const targetPane = resolveHumanTarget();
-    return spawnAndDetach({
-        command: runCmd(idir),
-        cwd,
-        ...(jobId !== undefined ? { jobId } : {}),
-        placement: pickPlacement(targetPane),
-        killAfterSeconds: 0,
-        detached: true,
-        ...(targetPane !== undefined ? { targetPane } : {}),
-    });
-}
-export function runCmd(dir) {
-    return `CRTR_HUMAN_DIR=${shellQuote(dir)} crtr human _run`;
-}
-export function followUpResult(_jobId) {
-    return "The human's answer is delivered to your inbox when they respond — no need to poll.";
-}
-export function followUpDrain(_jobId) {
-    return ('Not in tmux: a human must drain it — run `crtr human inbox` (or re-run ' +
-        'inside tmux). The answer then arrives in your inbox.');
-}
-/**
- * Road sign for a spawned `human review`. It is a non-blocking kickoff, so the
- * text steers the caller to stop rather than wait, verify, or re-present: the
- * pane is already live and tracks the file, and the comments arrive via the
- * inbox/wake when the human submits.
- */
-export function followUpReview(_jobId) {
-    return ("The document is live on the human's screen for anchored, line-by-line " +
-        'review. The pane tracks the file — edit the .md in place and it re-renders ' +
-        'on save, so never cancel and re-present just to show a change. Do not poll, ' +
-        'verify it opened, or background this call; end your turn. The human reviews ' +
-        'on their own time, and their comments (with any line edits) arrive in your ' +
-        'inbox and wake you when they submit.');
-}
-/**
- * Spawn the detached `_run` pane that drives the humanloop TUI for this node.
- * Returns whether the pane spawned and the follow_up road sign. Degrades to the
- * inbox-drain follow_up when not in tmux / spawn fails — kickoffs are
- * intentionally non-fatal off-tmux.
+ * The direct-exec completion handler humanloop runs when a crouter ticket
+ * resolves, fed the completion event on stdin. The argv is absolute and
+ * PATH/cwd-independent — never a `crtr` shell string — and, critically, must
+ * actually EXECUTE in both crouter contexts:
+ *
+ * - Built (`dist/cli.js` present): `node <abs>/dist/cli.js human _deliver`.
+ * - Dev/tsx (only `src/cli.ts` on disk): plain `node` cannot run the `.ts`
+ *   entry — its mandatory `.js`-extension ESM imports have no `.js` sibling on
+ *   disk, so Node's type-stripping fails at the first relative import. So we
+ *   register tsx's ESM loader first (`node --import <abs tsx/esm> src/cli.ts …`),
+ *   with the tsx entry resolved to an absolute file URL so the handler stays
+ *   cwd-independent when humanloop invokes it. tsx is necessarily present here
+ *   because crouter itself is running under it.
  *
- * Completion routing needs no bookkeeping here: the human node was created
- * under the asking node as its parent (spawnNode auto-subscribes the parent),
- * so the `pushFinal` the `_run` worker emits — for ask AND review —
- * fans the answer straight into the asking node's inbox. The pane id is recorded
- * on run.json (not returned) so `human cancel` can later kill the TUI.
+ * Throws loudly when neither entry exists rather than registering an argv that
+ * humanloop would retry forever.
  */
-export function spawnHumanJob(jobId, idir, cwd) {
-    const spawn = detachHumanTui(idir, cwd, jobId);
-    if (spawn.status !== 'spawned') {
-        return { spawned: false, follow_up: followUpDrain(jobId) };
+export function crouterDeliverHandler() {
+    const here = dirname(fileURLToPath(import.meta.url)); // dist/commands/human | src/commands/human
+    const distEntry = join(here, '..', '..', 'cli.js');
+    if (existsSync(distEntry)) {
+        return { command: process.execPath, args: [distEntry, 'human', '_deliver'] };
     }
-    // Record the pane id on run.json so `human cancel` can later kill the TUI.
-    // run.json was already written by the caller; merge the pane id in place.
-    if (spawn.paneId !== undefined) {
-        const rcPath = join(idir, 'run.json');
-        const rc = readJson(rcPath);
-        if (rc !== null)
-            atomicWriteJson(rcPath, { ...rc, pane_id: spawn.paneId });
+    const tsEntry = join(here, '..', '..', 'cli.ts');
+    if (existsSync(tsEntry)) {
+        const tsxLoader = pathToFileURL(createRequire(import.meta.url).resolve('tsx/esm')).href;
+        return { command: process.execPath, args: ['--import', tsxLoader, tsEntry, 'human', '_deliver'] };
     }
-    return { spawned: true, follow_up: followUpResult(jobId) };
+    throw new Error(`crouter completion handler: no runnable CLI entry near ${here} (neither cli.js nor cli.ts exists)`);
 }
 /**
- * Best-effort kill of a humanloop worker pane. SAFETY-CRITICAL: a malformed or
- * empty `-t` target makes tmux fall back to the CALLER's current pane, so a bad
- * paneId could kill the agent's own pi pane (and, if it is the last pane, the
- * whole session). This refuses to kill anything that is not provably the worker:
- *
- *   1. paneId must be a real tmux pane id (`%<n>`) — never an empty/odd string.
- *   2. The pane's start command must contain `verify` (the interaction dir, which
- *      humanloop bakes into the worker's `CRTR_HUMAN_DIR=... crtr human _run`
- *      launch). A shell (`zsh -l`) or the agent's pi never matches, so we can
- *      only ever kill the exact worker we spawned for this job.
- *
- * Returns true only when a matching pane was found and killed. Never throws.
+ * Register the per-cwd interaction root with humanloop as owner `crouter`,
+ * attaching the `_deliver` completion handler. Idempotent for owner `crouter`
+ * (refreshes the handler), and creates/canonicalizes the root. Returns the
+ * canonical root path humanloop submissions must be rooted at.
  */
-export function killPane(paneId, verify) {
-    if (!/^%\d+$/.test(paneId))
-        return false;
-    const probe = spawnSync('tmux', ['display-message', '-p', '-t', paneId, '#{pane_start_command}'], {
-        encoding: 'utf8',
-    });
-    // Pane is gone (status !== 0) → nothing to kill. Pane exists but its launch
-    // command doesn't carry our interaction dir → it is NOT our worker; refuse.
-    if (probe.status !== 0 || !probe.stdout.includes(verify))
-        return false;
-    const r = spawnSync('tmux', ['kill-pane', '-t', paneId], { encoding: 'utf8' });
-    return r.status === 0;
+export function registerCrouterRoot(cwd) {
+    return registerInboxRoot({ root: interactionsRoot(cwd), owner: 'crouter', handler: crouterDeliverHandler() }).root;
 }

package/dist/commands/human.js

@@ -1,31 +1,30 @@
-// `crtr human` subtree — in-process humanloop bridge.
+// `crtr human` subtree — humanloop producer + completion bridge.
 //
-// Kickoff leaves (ask/review) create a kind:'human' node under the
-// asking node, write deck.json/run.json into the per-cwd interaction dir, spawn
-// a detached `crtr human _run` pane, and return immediately. The human's answer
-// is pushed as the node's final report, which fans out to the asking node's
-// inbox — no polling surface. notify/show create no node. _run runs the blocking
-// humanloop call at the pane TTY and pushes the result itself.
-//
-// TTY safety: kickoff/TUI leaves are argv-only, so the spawned pane's TTY stays
-// free for humanloop's raw-mode input. Control params travel via CRTR_HUMAN_DIR
-// (set inline in the spawned command) + run.json, never stdin. The noninteractive
-// resolve leaf is the only stdin-taking child and does not spawn a TUI pane.
+// Kickoff leaves (ask/review) create a terminal kind:'human' bridge node under
+// the asking node, register the per-cwd interaction root with humanloop (owner
+// 'crouter', `_deliver` handler), submit the deck/review, and return at once —
+// nothing opens on screen. When the human answers from humanloop's inbox popup
+// (the inbox-toggle keybinding, or `hl inbox open`), humanloop invokes the
+// registered `_deliver` handler, which pushFinals
+// the answer as the bridge node's final report, fanning it into the asking
+// node's inbox. notify enqueues a durable deck with no node; show is passive
+// display. Humanloop owns the queue UI, claims, and atomic finalization.
 import { defineBranch } from '../core/command.js';
 import { humanAsk, humanReview, humanNotify, humanShow } from './human/prompts.js';
-import { humanInbox, humanList, humanDeck, humanResolve, humanCancel, humanRun } from './human/queue.js';
+import { humanList, humanDeck, humanResolve, humanCancel, humanDeliver } from './human/queue.js';
+import { inboxOpenInstruction } from '../core/keybindings/index.js';
 export function registerHuman() {
     return defineBranch({
         name: 'human',
         rootEntry: {
             concept: 'human-in-the-loop decisions, document review, and live display',
-            desc: 'ask, review, notify, show, cancel, inbox, list',
+            desc: 'ask, review, notify, show, cancel, list',
             useWhen: 'you have a question for the user, want their feedback, or are presenting them with options or a choice — always reach for human instead of guessing or assuming, or laying a choice out as prose, when a person can decide; and whenever the user wants to review a spec, plan, or requirements document, this is the command for anchored line-by-line comments.'
         },
         help: {
             name: 'human',
             summary: 'human-in-the-loop decisions, document review, and live display',
-            model: "Every body and displayed file is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see `termrender doc -h` for the directive set before authoring one. ask and review are kickoffs: they create a kind:'human' node under you and return instantly, never blocking — the human's response is pushed to your inbox when they answer, so keep working (or just end your turn) and you'll be woken with it. ask covers everything from a yes/no sign-off gate (two options) to an open-ended judgment call; review puts a .md live on the human's screen for anchored comments and tracks the file, so edit in place rather than canceling and re-presenting. notify and show create no node.",
+            model: `Every body and displayed file is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see \`termrender doc -h\` for the directive set before authoring one. ask and review are kickoffs: they create a kind:'human' bridge node under you and return instantly, never blocking. Nothing opens on screen — the ticket is queued in the humanloop inbox; the human opens it — ${inboxOpenInstruction()} — on their own time, and their response is pushed to your inbox when they answer, so keep working (or just end your turn) and you'll be woken with it. ask covers everything from a yes/no sign-off gate (two options) to an open-ended judgment call; review queues a .md for anchored comments and the inbox previews the live file, so edit in place rather than canceling and re-presenting. notify enqueues a durable acknowledgement with no node; show is passive live display.`,
         },
         children: [
             humanAsk,
@@ -33,11 +32,10 @@ export function registerHuman() {
             humanNotify,
             humanShow,
             humanCancel,
-            humanInbox,
             humanList,
             humanDeck,
             humanResolve,
-            humanRun,
+            humanDeliver,
         ],
     });
 }

package/dist/commands/node.js

@@ -15,6 +15,7 @@ import { writeYieldMessage, readGoal } from '../core/runtime/kickoff.js';
 import { reviveNode } from '../core/runtime/revive.js';
 import { parseOutputSchemaValue, writeOutputSchema } from '../core/runtime/structured-output.js';
 import { newNodeId } from '../core/runtime/nodes.js';
+import { inboxPopupHint } from '../core/keybindings/index.js';
 import { readRoadmap, hasRoadmap, seedRoadmap } from '../core/runtime/roadmap.js';
 import { parseWhen, parseCadence, cadenceDisplay } from '../core/wake.js';
 import { nodeSnapshotLeaf } from './node-snapshot.js';
@@ -617,6 +618,7 @@ const nodeFocus = defineLeaf({
         params: [
             { kind: 'positional', name: 'node', required: true, constraint: 'Node id to focus.' },
             { kind: 'flag', name: 'new-pane', type: 'bool', required: false, constraint: 'Always open a NEW viewer SIDE-BY-SIDE with your current pane instead of moving/reusing the node\'s existing viewer. Two agents on screen at once (F4).' },
+            { kind: 'flag', name: 'in-place', type: 'bool', required: false, constraint: 'Re-exec the --pane pane ONTO this node, REPLACING whatever viewer it showed (a swap in place, not a split beside). Backs the attach viewer\'s subagent scroll+swap (↓ into the reports roster, Enter dives into the child right in your pane). MUST be driven from OUTSIDE that pane\'s process tree (e.g. `tmux run-shell`) — respawn-pane -k kills whatever runs in it. Mutually exclusive with --new-pane.' },
             { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane id to focus beside (default: caller TMUX_PANE). Used by the canvas browser popup to focus back into the originating pane.' },
         ],
         output: [
@@ -626,7 +628,7 @@ const nodeFocus = defineLeaf({
             { name: 'in_place', type: 'boolean', required: true, constraint: 'True when an existing viewer was navigated to (no new pane); false when a fresh viewer pane was opened or moved beside you.' },
         ],
         outputKind: 'object',
-        effects: ['Ensures the node\'s broker engine is alive (revives it if dormant) and opens/moves its one viewer pane (a surface attach view) beside the caller, or navigates to it if a live viewer already sits in the caller\'s session.', 'With --new-pane: always splits a fresh viewer beside the caller (two agents on screen) instead of reusing the existing viewer.'],
+        effects: ['Ensures the node\'s broker engine is alive (revives it if dormant) and opens/moves its one viewer pane (a surface attach view) beside the caller, or navigates to it if a live viewer already sits in the caller\'s session.', 'With --new-pane: always splits a fresh viewer beside the caller (two agents on screen) instead of reusing the existing viewer.', 'With --in-place: re-execs the --pane pane onto the node, replacing its current viewer (a swap in place) rather than opening beside; the replaced node\'s broker keeps running headless.'],
     },
     run: async (input) => {
         const id = input['node'];
@@ -641,7 +643,7 @@ const nodeFocus = defineLeaf({
             throw new InputError({
                 error: 'not_focusable',
                 message: `node ${id} is a human-ask (kind:human), not a conversation — it has no pi session to focus.`,
-                next: `The pending question is already on the human's screen; see it with \`crtr human list\` / \`crtr human inbox\`, or retract it with \`crtr human cancel ${id}\`.`,
+                next: `The pending question is queued for the human (${inboxPopupHint()} opens the inbox popup); see it with \`crtr human list\`, or retract it with \`crtr human cancel ${id}\`.`,
             });
         }
         // Placement owns the whole act: ensure the target's broker engine is alive
@@ -651,6 +653,7 @@ const nodeFocus = defineLeaf({
         const res = await placementFocus(id, {
             pane: input['pane'],
             newPane: input['newPane'] === true,
+            inPlace: input['inPlace'] === true,
             revive: (nid) => reviveNode(nid, { resume: true }),
         });
         return { focused: res.focused, session: res.session, revived: res.revived, in_place: res.inPlace };

package/dist/commands/surface.js

@@ -7,7 +7,7 @@ import { defineBranch } from '../core/command.js';
 import { registerView } from './view.js';
 import { registerWorkspace } from './workspace.js';
 import { registerWeb } from '../clients/web/web-cmd.js';
-import { registerAttach } from '../clients/attach/attach-cmd.js';
+import { registerAttach } from '../clients/attach/attach-def.js';
 import { tmuxSpreadLeaf } from './surface-tmux-spread.js';
 function namespaceForSurface(node) {
     node.help.name = `surface ${node.help.name}`;

package/dist/commands/sys/__tests__/setup-core.test.js

@@ -55,7 +55,7 @@ test('setup keybinding draft keeps the last valid cell value on syntax, collisio
     assert.deepEqual(draft.overrides(), {});
     const collision = draft.edit('crtr.attach.graph.toggle', 'alt+m');
     assert.equal(collision.ok, false);
-    assert.match(collision.diagnostics[0].message, /crtr\.mode\.cycle/);
+    assert.match(collision.diagnostics[0].message, /crtr\.attach\.model-ladder\.next/);
     assert.deepEqual(draft.overrides(), {});
     const unsafe = draft.unbind('crtr.setup.keybindings.save');
     assert.equal(unsafe.ok, false);

package/dist/commands/sys/__tests__/setup-front-door.test.js

@@ -0,0 +1,85 @@
+// Run with: node --import tsx/esm --test src/commands/sys/__tests__/setup-front-door.test.ts
+//
+// M1 — `crtr sys setup` front-door reconciliation. Setup registers known nodes'
+// interaction roots to owner 'crouter' so a resolved humanloop ticket can call
+// back into the asking node (best-effort). The inbox-toggle tmux key is a
+// crouter keybinding installed by `installTmuxBindings()`, not reconciled here.
+// The humanloop registry is isolated with a temp XDG_STATE_HOME (see
+// human-deliver.test.ts); the canvas is isolated with a temp CRTR_HOME + HOME.
+import { test, before, beforeEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { listInboxRoots } from '@crouton-kit/humanloop';
+import { spawnNode } from '../../../core/runtime/nodes.js';
+import { closeDb } from '../../../core/canvas/index.js';
+import { reconcileInboxFrontDoor } from '../setup-core.js';
+import { sysSetupLeaf } from '../setup.js';
+let home;
+let stateHome;
+let priorHome;
+before(() => {
+    priorHome = process.env['HOME'];
+});
+beforeEach(() => {
+    closeDb();
+    home = mkdtempSync(join(tmpdir(), 'crtr-setup-home-'));
+    stateHome = mkdtempSync(join(tmpdir(), 'crtr-setup-state-'));
+    process.env['CRTR_HOME'] = home;
+    process.env['HOME'] = home;
+    process.env['XDG_STATE_HOME'] = stateHome;
+    delete process.env['CRTR_NODE_ID'];
+});
+after(() => {
+    closeDb();
+    if (priorHome !== undefined)
+        process.env['HOME'] = priorHome;
+    else
+        delete process.env['HOME'];
+    delete process.env['CRTR_HOME'];
+    delete process.env['XDG_STATE_HOME'];
+});
+test('reconcile registers each known node cwd as an owner-crouter interaction root', () => {
+    // Two nodes sharing one cwd + one on another cwd → two distinct roots.
+    const otherCwd = mkdtempSync(join(tmpdir(), 'crtr-setup-cwd-'));
+    spawnNode({ kind: 'general', parent: null, cwd: home, name: 'a' });
+    spawnNode({ kind: 'general', parent: null, cwd: home, name: 'b' });
+    spawnNode({ kind: 'general', parent: null, cwd: otherCwd, name: 'c' });
+    const { interactionRootsRegistered } = reconcileInboxFrontDoor();
+    // Deduped by cwd: two cwds → two registrations.
+    assert.equal(interactionRootsRegistered, 2, 'one registration per distinct node cwd');
+    const crouterRoots = listInboxRoots().filter((r) => r.owner === 'crouter');
+    assert.ok(crouterRoots.length >= 2, 'both interaction roots landed in the humanloop registry as owner crouter');
+});
+test('invoking `crtr sys setup` (non-TTY leaf run) reconciles the front door', async () => {
+    // Exercise the real control flow — sysSetupLeaf.run() → runSetup() →
+    // reconcileInboxFrontDoor — not the helper directly. With no TTY the leaf
+    // prints static instructions and returns, but reconciliation must still have
+    // happened on the way through.
+    spawnNode({ kind: 'general', parent: null, cwd: home, name: 'a' });
+    const originalIsTTY = process.stdout.isTTY;
+    const originalWrite = process.stdout.write.bind(process.stdout);
+    // Force the non-TTY (instructions-print) branch and swallow its output.
+    Object.defineProperty(process.stdout, 'isTTY', { value: false, configurable: true });
+    process.stdout.write = () => true;
+    try {
+        await sysSetupLeaf.run({});
+    }
+    finally {
+        process.stdout.write = originalWrite;
+        Object.defineProperty(process.stdout, 'isTTY', { value: originalIsTTY, configurable: true });
+    }
+    const homeReal = realpathSync(home);
+    const crouterRoots = listInboxRoots().filter((r) => r.owner === 'crouter');
+    // registerCrouterRoot maps the node cwd to its workspace interactions dir
+    // under that cwd, so the registered root is rooted at the node's home.
+    assert.ok(crouterRoots.some((r) => r.root.startsWith(homeReal)), 'the leaf invocation registered the node cwd as an owner-crouter interaction root');
+});
+test('reconcile is idempotent for owner crouter — re-running does not error and keeps the roots', () => {
+    spawnNode({ kind: 'general', parent: null, cwd: home, name: 'a' });
+    reconcileInboxFrontDoor();
+    const { interactionRootsRegistered } = reconcileInboxFrontDoor();
+    assert.equal(interactionRootsRegistered, 1);
+    assert.ok(listInboxRoots().some((r) => r.owner === 'crouter'));
+});

package/dist/commands/sys/setup-core.d.ts

@@ -51,6 +51,7 @@ export interface SetupExecutionSummary {
     exaKeyPath: string;
     composioKeyWritten: boolean;
     composioKeyPath: string;
+    interactionRootsRegistered: number;
 }
 export interface SetupInitialState {
     manifest: SetupPackageManifestEntry[];
@@ -122,6 +123,14 @@ export declare function buildSetupStaticInstructions(opts: {
 export declare function renderSetupStaticInstructions(state: Pick<SetupInitialState, 'manifest' | 'installedPackageIds' | 'systemTools' | 'exaKeyPath' | 'composioKeyPath'>): string;
 export declare function writeExaKey(exaKeyPath: string, exaKey: string): Promise<void>;
 export declare function writeComposioKey(composioKeyPath: string, composioKey: string): Promise<void>;
+/** Register each known node's interaction root to owner `crouter` so a resolved
+ *  ticket can call back into `human _deliver`. Best-effort: setup must never
+ *  fail because the canvas is unreadable. The inbox-toggle tmux key is NOT
+ *  reconciled here — it is a crouter keybinding installed by `installTmuxBindings()`
+ *  alongside every other binding. */
+export declare function reconcileInboxFrontDoor(): {
+    interactionRootsRegistered: number;
+};
 export declare function summarizeSetupExecution(result: {
     installedPackages: string[];
     skippedPackages: string[];
@@ -131,6 +140,7 @@ export declare function summarizeSetupExecution(result: {
     exaKeyPath: string;
     composioKeyWritten: boolean;
     composioKeyPath: string;
+    interactionRootsRegistered: number;
 }): SetupExecutionSummary;
 export declare function formatSetupExecutionSummary(summary: SetupExecutionSummary): string;
 export declare function executeSetupSubmission(submission: SetupSubmission): Promise<SetupExecutionSummary>;

package/dist/commands/sys/setup-core.js

@@ -4,10 +4,12 @@ import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename, dirname, join, resolve } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
-import { BINDING_CATALOG, normalizeGesture, resolveKeybindings, } from '../../core/keybindings/index.js';
+import { BINDING_CATALOG, normalizeGesture, inboxShortcut, resolveKeybindings, } from '../../core/keybindings/index.js';
 import { builtinPiPackageDir } from '../../core/scope.js';
 import { readJsonIfExists } from '../../core/fs-utils.js';
 import { resolveBundledPiCliPath } from '../../core/runtime/pi-cli.js';
+import { listNodes } from '../../core/canvas/index.js';
+import { registerCrouterRoot } from '../human/shared.js';
 function isKeybindingsObject(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
@@ -422,6 +424,8 @@ export function renderSetupStaticInstructions(state) {
         '',
         instructions.exaLine,
         instructions.composioLine,
+        '',
+        `Inbox popup: the inbox-toggle key (${inboxShortcut() ?? 'disabled'}) is a crouter keybinding — view or rebind it in the \`crtr sys setup\` keybindings tab; it is installed on the same tmux server as every other crouter binding. \`crtr sys setup\` also registers known nodes' interaction roots (best-effort).`,
         instructions.footer,
     ].join('\n') + '\n';
 }
@@ -447,6 +451,33 @@ export async function writeComposioKey(composioKeyPath, composioKey) {
     await writeFile(composioKeyPath, `${composioKey}\n`, 'utf8');
     await chmod(composioKeyPath, 0o600).catch(() => undefined);
 }
+/** Register each known node's interaction root to owner `crouter` so a resolved
+ *  ticket can call back into `human _deliver`. Best-effort: setup must never
+ *  fail because the canvas is unreadable. The inbox-toggle tmux key is NOT
+ *  reconciled here — it is a crouter keybinding installed by `installTmuxBindings()`
+ *  alongside every other binding. */
+export function reconcileInboxFrontDoor() {
+    let interactionRootsRegistered = 0;
+    try {
+        const seen = new Set();
+        for (const node of listNodes()) {
+            if (seen.has(node.cwd))
+                continue;
+            seen.add(node.cwd);
+            try {
+                registerCrouterRoot(node.cwd);
+                interactionRootsRegistered += 1;
+            }
+            catch {
+                /* skip a cwd humanloop can't canonicalize/create */
+            }
+        }
+    }
+    catch {
+        /* best-effort: canvas unavailable */
+    }
+    return { interactionRootsRegistered };
+}
 export function summarizeSetupExecution(result) {
     return {
         installed: [...result.installedPackages, ...result.installedSystemDeps],
@@ -455,6 +486,7 @@ export function summarizeSetupExecution(result) {
         exaKeyPath: result.exaKeyPath,
         composioKeyWritten: result.composioKeyWritten,
         composioKeyPath: result.composioKeyPath,
+        interactionRootsRegistered: result.interactionRootsRegistered,
     };
 }
 export function formatSetupExecutionSummary(summary) {
@@ -464,6 +496,7 @@ export function formatSetupExecutionSummary(summary) {
         summary.skipped.length > 0 ? `skipped: ${summary.skipped.join(', ')}` : 'skipped: none',
         summary.exaKeyWritten ? `exa key written: ${summary.exaKeyPath}` : 'exa key written: no',
         summary.composioKeyWritten ? `composio key written: ${summary.composioKeyPath}` : 'composio key written: no',
+        `interaction roots registered: ${summary.interactionRootsRegistered}`,
     ].join('\n') + '\n';
 }
 export async function executeSetupSubmission(submission) {
@@ -499,6 +532,10 @@ export async function executeSetupSubmission(submission) {
     if (composioKeyWritten) {
         await writeComposioKey(submission.composioKeyPath, submission.composioKey);
     }
+    // Front-door reconciliation: register known nodes' interaction roots for
+    // `human _deliver` callback. Best-effort. The inbox-toggle key is a crouter
+    // keybinding installed by `installTmuxBindings()`, not reconciled here.
+    const { interactionRootsRegistered } = reconcileInboxFrontDoor();
     return summarizeSetupExecution({
         installedPackages,
         skippedPackages,
@@ -508,5 +545,6 @@ export async function executeSetupSubmission(submission) {
         exaKeyPath: submission.exaKeyPath,
         composioKeyWritten,
         composioKeyPath: submission.composioKeyPath,
+        interactionRootsRegistered,
     });
 }