@crouton-kit/crouter 0.3.28 → 0.3.30

package/dist/core/runtime/tmux.d.ts

@@ -46,6 +46,12 @@ export interface SplitWindowOpts {
     command: string;
     /** Stack the new pane below instead of beside (default: beside, `-h`). */
     vertical?: boolean;
+    /** Place the new pane BEFORE the target (left for `-h`, above for `-v`) via
+     *  `-b`, instead of after it (default: after — right/below). */
+    before?: boolean;
+    /** Fixed size of the new pane in the split axis' cells (columns for `-h`, rows
+     *  for `-v`) via `-l`. Omit ⇒ tmux's default even split. */
+    size?: number;
 }
 /** Split `targetPane`'s window, opening a NEW pane beside it running `command`,
  *  and return the new pane id (the durable `%id`). The ONLY new-pane-beside verb
@@ -62,6 +68,10 @@ export declare function splitWindow(targetPane: string, opts: SplitWindowOpts):
 export declare function focusWindow(session: string, window: string): boolean;
 /** Close a node's window (drop it from the UI). */
 export declare function closeWindow(window: string): boolean;
+/** Rename a window (`tmux rename-window -t <window> <name>`). Used by the
+ *  root relaunch to re-title the viewer window when its pane is re-pointed at
+ *  the freshly-minted node. Best-effort; false if tmux fails. */
+export declare function renameWindow(window: string, name: string): boolean;
 /** Close a single PANE. Its window closes automatically once this was the last
  *  pane, but sibling panes survive — so co-located nodes (several agents sharing
  *  one window via swap-pane focus) are torn down one at a time instead of all
@@ -97,13 +107,9 @@ export declare function paneLocation(pane: string): {
  *  pane: a live pane echoes its own id, a gone/bogus one yields empty. */
 export declare function paneExists(pane: string): boolean;
 /** Does this pane exist AND have its command still RUNNING (`#{pane_dead}` = 0)?
- *  Distinguishes a pane genuinely hosting a process — a live pi, or a pi still
- *  BOOTING whose pid hasn't been recorded yet — from a remain-on-exit corpse
- *  frozen after exit (`pane_dead` = 1). Node panes run pi as the pane command
- *  (openNodeWindow / respawn-pane), never a shell, so pane-running ⟹ a pi (or
- *  its respawn) occupies it. The probe handFocusToManager's live-swap gates on:
- *  the recorded `pi_pid` is a stale proxy in the just-revived window (the new pi
- *  records its pid only at session_start), but the pane itself never lies. */
+ *  Distinguishes a pane genuinely hosting a live process from a remain-on-exit
+ *  corpse frozen after exit (`pane_dead` = 1). Node viewer panes run `crtr attach`
+ *  as the pane command, so pane-running ⟹ a live viewer occupies it. */
 export declare function paneRunning(pane: string): boolean;
 /** Every live pane id on the server (`list-panes -a`), as a Set for membership
  *  probes. Returns null when tmux is unreachable (no server / transient failure)
@@ -125,21 +131,6 @@ export declare function setPaneOption(pane: string, name: string, value: string)
  *  <name>`): `-v` prints only the value, `-q` suppresses the unknown-option
  *  error so an unset option yields an empty string. undefined if tmux fails. */
 export declare function getPaneOption(pane: string, name: string): string | undefined;
-/** Relocate a pane into another session as its own window WITHOUT killing the
- *  process in it — `break-pane -d` moves the pane out of its current window (the
- *  pi keeps generating) into a fresh window in `session`; `-d` leaves the caller's
- *  client where it is rather than following the pane to the background, and `-a`
- *  allocates the next free window index (same dodge as openNodeWindow). The
- *  "detach to background" driver behind `node lifecycle --detach`. Best-effort;
- *  false if tmux refuses (e.g. the pane is gone). The caller reconciles presence
- *  so the canvas follows the move. */
-export declare function breakPaneToSession(pane: string, session: string): boolean;
-/** Swap `targetPane` into `callerPane`'s layout slot, IN PLACE. `-d` keeps the
- *  caller's window active, so the target's pane appears where the caller is
- *  rather than navigating the client off to the target's window. The caller's
- *  old pane lives on in the target's former window — the move is reversible
- *  (focusing back swaps it in again). Best-effort; never throws. */
-export declare function swapPaneInPlace(targetPane: string, callerPane: string): boolean;
 export interface RespawnPaneOpts {
     /** Target pane id (e.g. `%3`) — the pane to re-exec in place. */
     pane: string;
@@ -148,21 +139,11 @@ export interface RespawnPaneOpts {
     /** The full command to run in the pane (already a shell string). */
     command: string;
 }
-/** Re-exec a command in an EXISTING pane, in place — DETACHED. Spawned in its own
- *  process group (unref'd) so the request reaches the tmux server even though
- *  `-k` tears down the caller's own pi mid-flight. Used when a node respawns ITS
- *  OWN pane (refresh-yield): the dispatch can't be awaited because it kills the
- *  awaiter. Returns true once the request was dispatched. */
-export declare function respawnPaneDetached(opts: RespawnPaneOpts): boolean;
 /** Re-exec a command in an EXISTING pane, in place — SYNCHRONOUS. Runs the
  *  `respawn-pane` to completion and reports the real exit status. Used when the
  *  caller is NOT the pane being respawned (e.g. the daemon resuming a frozen
  *  focus pane), so it can confirm the respawn landed. Returns true on success. */
 export declare function respawnPaneSync(opts: RespawnPaneOpts): boolean;
-/** @deprecated Use respawnPaneDetached. Retained so existing refresh-yield
- *  callers stay green while the placement layer migrates onto the explicit
- *  sync/detached split. */
-export declare function respawnPane(opts: RespawnPaneOpts): boolean;
 /** Turn a pi argv array into a single shell command string.
  *
  *  The binary defaults to `CRTR_PI_BINARY` when that env var is set, else the
@@ -192,31 +173,13 @@ export declare function selectWindow(session: string, window: string): boolean;
  *  `tmux switch-client -t <session>`. Best-effort; never throws. The caller is
  *  responsible for following up with selectWindow to land on the right window. */
 export declare function switchClient(session: string): boolean;
-/** Move a source pane into a destination window (`tmux join-pane`). The source
- *  pane's running process (e.g. a child's live pi) is preserved; its now-empty
- *  source window auto-closes. Best-effort; false if tmux fails. */
-export declare function joinPane(srcPane: string, dstWindow: string): boolean;
-/** Apply a named tmux layout to a window (`tmux select-layout`). Use
- *  `main-vertical` for one wide pane on the left + the rest stacked right.
- *  Best-effort; never throws. */
-export declare function selectLayout(window: string, layout: string): boolean;
-/** Set a tmux window option (`tmux set-window-option`). Used to size the main
- *  pane (`main-pane-width`) before a main-vertical layout. Best-effort. */
-export declare function setWindowOption(window: string, name: string, value: string): boolean;
-/** Toggle `remain-on-exit` on a window (§1.5 F3). `on` keeps a focus pane on
- *  screen after its pi exits — the viewport survives (F1), the final transcript
- *  is preserved, and `respawn-pane -k` can resurrect the node into the SAME pane
- *  id. NOTE (§1.5/§2.5, spike-confirmed): a dead/frozen pane is reaped only by
- *  `kill-pane`/`respawn-pane`, NEVER by toggling this off — the toggle does not
- *  reap an already-dead pane. Best-effort; never throws. */
-export declare function setRemainOnExit(window: string, on: boolean): boolean;
 /** Type a literal (e.g. a `/graph` slash command) into a pane and press Enter
  *  (`tmux send-keys -t <pane> '<text>' Enter`). Requires the pane's editor be
  *  empty, same limitation as the menu's `/promote` item. Best-effort. */
 export declare function sendKeysEnter(pane: string, text: string): boolean;
 /** Bind Alt+C to the crouter action menu. Best-effort; false if tmux fails.
- *  The built-in items (promote/demote/detach/close/browse) are static; the canvas-nav
- *  chords (graph/manager/expand/report-N + any custom prefixBind) are appended
+ *  The built-in items (promote/resume/demote/detach/close) are static; the canvas-nav
+ *  chords (default g→graph, m→manager + any custom prefixBind) are appended
  *  from `canvasNav.prefixBinds`, each routed through `crtr canvas chord` (or, for
  *  the `__graph__` sentinel, a `send-keys '/graph'`) so the menu stays static
  *  while behaviour is config-driven. */

package/dist/core/runtime/tmux.js

@@ -7,9 +7,9 @@
 // UI unless you switch to it. Bring one forefront with select-window (within a
 // root) or switch-client + select-window (across roots). done/dead nodes close
 // their window; reviving opens a fresh one.
-import { spawn, spawnSync } from 'node:child_process';
+import { spawnSync } from 'node:child_process';
 import { readConfig } from '../config.js';
-import { nodeSession } from './nodes.js';
+import { surfaceTmuxStyleArgs } from './surface-bg.js';
 // ---------------------------------------------------------------------------
 // Shell quoting + tmux invocation
 // ---------------------------------------------------------------------------
@@ -115,6 +115,8 @@ export function splitWindow(targetPane, opts) {
         'split-window',
         '-d',
         ...(opts.vertical === true ? [] : ['-h']),
+        ...(opts.before === true ? ['-b'] : []),
+        ...(opts.size !== undefined ? ['-l', String(opts.size)] : []),
         '-P',
         '-F',
         '#{pane_id}',
@@ -141,6 +143,12 @@ export function focusWindow(session, window) {
 export function closeWindow(window) {
     return tmux(['kill-window', '-t', window]).ok;
 }
+/** Rename a window (`tmux rename-window -t <window> <name>`). Used by the
+ *  root relaunch to re-title the viewer window when its pane is re-pointed at
+ *  the freshly-minted node. Best-effort; false if tmux fails. */
+export function renameWindow(window, name) {
+    return tmux(['rename-window', '-t', window, name]).ok;
+}
 /** Close a single PANE. Its window closes automatically once this was the last
  *  pane, but sibling panes survive — so co-located nodes (several agents sharing
  *  one window via swap-pane focus) are torn down one at a time instead of all
@@ -192,13 +200,9 @@ export function paneExists(pane) {
     return r.ok && r.stdout === pane;
 }
 /** Does this pane exist AND have its command still RUNNING (`#{pane_dead}` = 0)?
- *  Distinguishes a pane genuinely hosting a process — a live pi, or a pi still
- *  BOOTING whose pid hasn't been recorded yet — from a remain-on-exit corpse
- *  frozen after exit (`pane_dead` = 1). Node panes run pi as the pane command
- *  (openNodeWindow / respawn-pane), never a shell, so pane-running ⟹ a pi (or
- *  its respawn) occupies it. The probe handFocusToManager's live-swap gates on:
- *  the recorded `pi_pid` is a stale proxy in the just-revived window (the new pi
- *  records its pid only at session_start), but the pane itself never lies. */
+ *  Distinguishes a pane genuinely hosting a live process from a remain-on-exit
+ *  corpse frozen after exit (`pane_dead` = 1). Node viewer panes run `crtr attach`
+ *  as the pane command, so pane-running ⟹ a live viewer occupies it. */
 export function paneRunning(pane) {
     const r = tmux(['display-message', '-p', '-t', pane, '#{pane_id}\t#{pane_dead}']);
     return r.ok && r.stdout === `${pane}\t0`;
@@ -236,27 +240,6 @@ export function getPaneOption(pane, name) {
     const r = tmux(['show-options', '-p', '-t', pane, '-q', '-v', name]);
     return r.ok ? r.stdout : undefined;
 }
-/** Relocate a pane into another session as its own window WITHOUT killing the
- *  process in it — `break-pane -d` moves the pane out of its current window (the
- *  pi keeps generating) into a fresh window in `session`; `-d` leaves the caller's
- *  client where it is rather than following the pane to the background, and `-a`
- *  allocates the next free window index (same dodge as openNodeWindow). The
- *  "detach to background" driver behind `node lifecycle --detach`. Best-effort;
- *  false if tmux refuses (e.g. the pane is gone). The caller reconciles presence
- *  so the canvas follows the move. */
-export function breakPaneToSession(pane, session) {
-    return tmux(['break-pane', '-d', '-a', '-s', pane, '-t', `${session}:`]).ok;
-}
-/** Swap `targetPane` into `callerPane`'s layout slot, IN PLACE. `-d` keeps the
- *  caller's window active, so the target's pane appears where the caller is
- *  rather than navigating the client off to the target's window. The caller's
- *  old pane lives on in the target's former window — the move is reversible
- *  (focusing back swaps it in again). Best-effort; never throws. */
-export function swapPaneInPlace(targetPane, callerPane) {
-    if (targetPane === callerPane)
-        return true;
-    return tmux(['swap-pane', '-d', '-s', targetPane, '-t', callerPane]).ok;
-}
 /** The `respawn-pane -k` argv for `opts`. `-k` kills the pane's current process
  *  (e.g. a yielding pi) and re-execs `command` in the SAME pane, preserving its
  *  `%id` (§1.5 F3: a frozen focus pane resumes in place, no new window). The
@@ -274,24 +257,6 @@ function respawnPaneArgs(opts) {
         opts.command,
     ];
 }
-/** Re-exec a command in an EXISTING pane, in place — DETACHED. Spawned in its own
- *  process group (unref'd) so the request reaches the tmux server even though
- *  `-k` tears down the caller's own pi mid-flight. Used when a node respawns ITS
- *  OWN pane (refresh-yield): the dispatch can't be awaited because it kills the
- *  awaiter. Returns true once the request was dispatched. */
-export function respawnPaneDetached(opts) {
-    try {
-        const child = spawn('tmux', respawnPaneArgs(opts), {
-            detached: true,
-            stdio: 'ignore',
-        });
-        child.unref();
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 /** Re-exec a command in an EXISTING pane, in place — SYNCHRONOUS. Runs the
  *  `respawn-pane` to completion and reports the real exit status. Used when the
  *  caller is NOT the pane being respawned (e.g. the daemon resuming a frozen
@@ -299,12 +264,6 @@ export function respawnPaneDetached(opts) {
 export function respawnPaneSync(opts) {
     return tmux(respawnPaneArgs(opts)).ok;
 }
-/** @deprecated Use respawnPaneDetached. Retained so existing refresh-yield
- *  callers stay green while the placement layer migrates onto the explicit
- *  sync/detached split. */
-export function respawnPane(opts) {
-    return respawnPaneDetached(opts);
-}
 // ---------------------------------------------------------------------------
 // pi command assembly
 // ---------------------------------------------------------------------------
@@ -359,34 +318,8 @@ export function switchClient(session) {
     return tmux(['switch-client', '-t', session]).ok;
 }
 // ---------------------------------------------------------------------------
-// Multi-pane layout (used by `canvas tmux-spread`)
+// send-keys (chrome — used by the prefix menu + nav bindings)
 // ---------------------------------------------------------------------------
-/** Move a source pane into a destination window (`tmux join-pane`). The source
- *  pane's running process (e.g. a child's live pi) is preserved; its now-empty
- *  source window auto-closes. Best-effort; false if tmux fails. */
-export function joinPane(srcPane, dstWindow) {
-    return tmux(['join-pane', '-s', srcPane, '-t', dstWindow]).ok;
-}
-/** Apply a named tmux layout to a window (`tmux select-layout`). Use
- *  `main-vertical` for one wide pane on the left + the rest stacked right.
- *  Best-effort; never throws. */
-export function selectLayout(window, layout) {
-    return tmux(['select-layout', '-t', window, layout]).ok;
-}
-/** Set a tmux window option (`tmux set-window-option`). Used to size the main
- *  pane (`main-pane-width`) before a main-vertical layout. Best-effort. */
-export function setWindowOption(window, name, value) {
-    return tmux(['set-window-option', '-t', window, name, value]).ok;
-}
-/** Toggle `remain-on-exit` on a window (§1.5 F3). `on` keeps a focus pane on
- *  screen after its pi exits — the viewport survives (F1), the final transcript
- *  is preserved, and `respawn-pane -k` can resurrect the node into the SAME pane
- *  id. NOTE (§1.5/§2.5, spike-confirmed): a dead/frozen pane is reaped only by
- *  `kill-pane`/`respawn-pane`, NEVER by toggling this off — the toggle does not
- *  reap an already-dead pane. Best-effort; never throws. */
-export function setRemainOnExit(window, on) {
-    return tmux(['set-window-option', '-t', window, 'remain-on-exit', on ? 'on' : 'off']).ok;
-}
 /** Type a literal (e.g. a `/graph` slash command) into a pane and press Enter
  *  (`tmux send-keys -t <pane> '<text>' Enter`). Requires the pane's editor be
  *  empty, same limitation as the menu's `/promote` item. Best-effort. */
@@ -401,15 +334,14 @@ export function sendKeysEnter(pane, text) {
 // ---------------------------------------------------------------------------
 /** Reserved mnemonic keys owned by the built-in menu items below — a custom
  *  `prefixBind` may not claim these (the built-in item wins). */
-const RESERVED_MENU_KEYS = new Set(['o', 'r', 'd', 'D', 'x', 'b']);
+const RESERVED_MENU_KEYS = new Set(['o', 'r', 'd', 'D', 'x']);
 /** Bind Alt+C to the crouter action menu. Best-effort; false if tmux fails.
- *  The built-in items (promote/demote/detach/close/browse) are static; the canvas-nav
- *  chords (graph/manager/expand/report-N + any custom prefixBind) are appended
+ *  The built-in items (promote/resume/demote/detach/close) are static; the canvas-nav
+ *  chords (default g→graph, m→manager + any custom prefixBind) are appended
  *  from `canvasNav.prefixBinds`, each routed through `crtr canvas chord` (or, for
  *  the `__graph__` sentinel, a `send-keys '/graph'`) so the menu stays static
  *  while behaviour is config-driven. */
 export function installMenuBinding() {
-    const sess = nodeSession();
     const title = ' crtr ';
     const items = [
         // Promote types `/promote` into the agent's pane rather than shelling out:
@@ -423,17 +355,15 @@ export function installMenuBinding() {
         // `d` runs `node demote`: flip the agent to TERMINAL in place — no finalize,
         // no kill — it keeps running where it is, and because it is now terminal it
         // is forced to push a final up the spine when it finishes. `D` runs `node
-        // demote --detach`, which ALSO detaches it to the background `crtr` session
-        // (frees the pane; the pi keeps generating). Neither ends it.
+        // demote --detach`, which ALSO closes the agent's viewer pane (frees the
+        // pane; the detached broker keeps generating). Neither ends it.
         { name: 'demote to terminal', key: 'd', cmd: `run-shell "crtr node demote --pane '#{pane_id}' >/dev/null 2>&1"` },
         { name: 'detach to background', key: 'D', cmd: `run-shell "crtr node demote --pane '#{pane_id}' --detach >/dev/null 2>&1"` },
         // Close cascades down the subscribes_to spine (kills the subtree's windows,
         // marks them canceled); revivable. Output discarded — the keypress just acts.
         { name: 'close agent + subtree', key: 'x', cmd: `run-shell "crtr node close --pane '#{pane_id}' >/dev/null 2>&1"` },
-        // Re-keyed g→b so `g` is free for the canvas-nav GRAPH toggle (below).
-        { name: 'browse background agents', key: 'b', cmd: `switch-client -t ${sess}` },
     ];
-    // Canvas-nav chords from config (default: g→graph, m→manager, e→expand). The
+    // Canvas-nav chords from config (default: g→graph, m→manager). The
     // `__graph__` sentinel toggles the in-pi GRAPH modal via send-keys; every
     // other bind shells the chord dispatcher, which resolves the pane's node and
     // interpolates the bind at popup time. Keys colliding with the built-ins are
@@ -452,15 +382,16 @@ export function installMenuBinding() {
             : `run-shell "crtr canvas chord --pane '#{pane_id}' --key ${key} >/dev/null 2>&1"`;
         items.push({ name, key, cmd });
     }
-    // Focus report N: nine generated chord items (1..9), each resolved by the
-    // dispatcher to subscriptionsOf(self)[N-1] at popup time.
-    for (let n = 1; n <= 9; n++) {
-        items.push({
-            name: `focus report ${n}`,
-            key: `${n}`,
-            cmd: `run-shell "crtr canvas chord --pane '#{pane_id}' --key ${n} >/dev/null 2>&1"`,
-        });
-    }
+    // Dismiss hint. A tmux display-menu always closes on its native cancel keys
+    // (Escape / q / C-c), encoding-independent. We do NOT try to catch a re-pressed
+    // Alt+C: under `extended-keys on` (common, and what pi negotiates) the second
+    // Alt+C reaches the overlay as a CSI-u key (`\033[99;3u`) that tmux's menu does
+    // NOT match against an `M-c` mnemonic item, so a "close menu" row keyed M-c
+    // never fires and the menu just sits open (verified in tmux 3.6b: legacy Esc+c
+    // closes, CSI-u does not). Instead, a disabled (`-` prefix → dim, unselectable)
+    // last row tells the user the close keys that always work. Placed last so it
+    // reads as chrome below the actions.
+    items.push({ name: '-esc / q to close', key: '', cmd: '' });
     // tmux's -x sets the menu's LEFT edge. To sit the box INSIDE the pane's
     // top-right corner, shift x left by the box width (longest line + tmux chrome:
     // borders + padding + the right-aligned mnemonic-key column) via format math.
@@ -472,6 +403,11 @@ export function installMenuBinding() {
     const args = [
         'bind-key', '-n', 'M-c', 'display-menu',
         '-T', `#[align=centre]${title}`,
+        // Frame the menu on the theme's distinct-surface background so it doesn't
+        // blend into the pane behind it (CTO ruling). Empty in the front door (theme
+        // not loaded there); the attach viewer re-installs this with the style once
+        // it has themed — see attach-cmd.ts.
+        ...surfaceTmuxStyleArgs(),
         '-x', `#{e|-:#{pane_right},${boxW + nudgeX}}`,
         '-y', `#{e|+:#{pane_top},${nudgeY}}`,
     ];

package/dist/core/scope.d.ts

@@ -9,7 +9,6 @@ export declare function requireScopeRoot(scope: Scope): string;
 export declare function ensureProjectScopeRoot(startDir?: string): string;
 export declare function pluginsDir(scope: Scope): string | null;
 export declare function marketplacesDir(scope: Scope): string | null;
-export declare function scopeSkillsDir(scope: Scope): string | null;
 /** Where substrate memory documents live per scope. Builtin memory is the
  *  special case — its own package dir (builtinMemoryRoot), since the builtin
  *  scope has no scopeRoot — mirroring viewsDir's builtin handling. User and
@@ -20,7 +19,7 @@ export declare function scopeMemoryDir(scope: Scope): string | null;
 export declare function pluginMemoryDir(plugin: InstalledPlugin): string;
 /** Where view definition dirs live per scope. Builtin views sit directly under
  *  builtinViewsRoot() (no `views/` segment — they ARE the builtin views dir),
- *  matching the loader's `<root>/<name>/view.mjs` resolution. */
+ *  matching the loader's `<root>/<name>/core.mjs` resolution. */
 export declare function viewsDir(scope: Scope): string | null;
 export declare function resolveScopeArg(scopeArg: string | undefined): Scope | 'all';
 export declare function listScopes(scopeArg: string | undefined): Scope[];

package/dist/core/scope.js

@@ -87,10 +87,6 @@ export function marketplacesDir(scope) {
     const root = scopeRoot(scope);
     return root ? join(root, 'marketplaces') : null;
 }
-export function scopeSkillsDir(scope) {
-    const root = scopeRoot(scope);
-    return root ? join(root, 'skills') : null;
-}
 /** Where substrate memory documents live per scope. Builtin memory is the
  *  special case — its own package dir (builtinMemoryRoot), since the builtin
  *  scope has no scopeRoot — mirroring viewsDir's builtin handling. User and
@@ -108,7 +104,7 @@ export function pluginMemoryDir(plugin) {
 }
 /** Where view definition dirs live per scope. Builtin views sit directly under
  *  builtinViewsRoot() (no `views/` segment — they ARE the builtin views dir),
- *  matching the loader's `<root>/<name>/view.mjs` resolution. */
+ *  matching the loader's `<root>/<name>/core.mjs` resolution. */
 export function viewsDir(scope) {
     if (scope === 'builtin')
         return builtinViewsRoot();

package/dist/core/skill-sync/__tests__/dry-run-wrote-count.test.d.ts

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

package/dist/core/skill-sync/__tests__/dry-run-wrote-count.test.js

@@ -0,0 +1,57 @@
+// Regression test for the `--dry-run` `wrote` count (found by P8 integration).
+//
+// Bug: under `--dry-run`, reconcilePair returned `wrote: counts.writes` — the
+// WOULD-BE endpoint write total — even though nothing is written to disk. That
+// contradicts the `sys sync -h` contract ("wrote … 0 under --dry-run") and the
+// rendered "DRY RUN (nothing written)" header, which together promise 0. The
+// fix makes `wrote` reflect ACTUAL writes (0 under dry-run) while still using
+// the would-be counts internally to decide synced-vs-noop.
+//
+// This test FAILS on the pre-fix code (wrote === number of files that WOULD be
+// written, e.g. 2 for a one-sided bootstrap) and PASSES on the current code.
+//
+// Run: node --import tsx/esm --test src/core/skill-sync/__tests__/dry-run-wrote-count.test.ts
+import { test, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync, existsSync } from 'node:fs';
+import { tmpdir, homedir } from 'node:os';
+import { join } from 'node:path';
+import { reconcilePair } from '../engine.js';
+import { DEFAULT_PROFILE } from '../profile.js';
+// The engine resolves user-scope endpoints + the snapshot store off homedir(),
+// which reads $HOME at call time — so isolating $HOME isolates everything.
+let home;
+let prevHome;
+const PAIR = {
+    id: 'dryrun-regression',
+    crtr: { scope: 'user', name: 'dr' },
+    claude: { scope: 'user', name: 'dr' },
+};
+before(() => {
+    prevHome = process.env.HOME;
+    home = mkdtempSync(join(tmpdir(), 'crtr-sync-dryrun-'));
+    process.env.HOME = home;
+    // One-sided bootstrap: only the crtr side exists. A real sync here would
+    // materialize the Claude side + write the snapshot (2 endpoint files written).
+    const crtrDir = join(home, '.crouter', 'memory', 'dr');
+    mkdirSync(crtrDir, { recursive: true });
+    writeFileSync(join(crtrDir, 'SKILL.md'), '---\nkind: knowledge\nwhen-and-why-to-read: "When the regression applies, this doc should be read."\n---\n# DR\nbody\n', 'utf8');
+});
+after(() => {
+    if (prevHome === undefined)
+        delete process.env.HOME;
+    else
+        process.env.HOME = prevHome;
+    rmSync(home, { recursive: true, force: true });
+    assert.equal(homedir(), prevHome ?? homedir()); // sanity: $HOME restored
+});
+test('--dry-run reports wrote === 0 and writes nothing to disk', () => {
+    const res = reconcilePair(PAIR, DEFAULT_PROFILE, { dryRun: true });
+    // Status still reflects that a real run WOULD sync this pair...
+    assert.equal(res.status, 'synced', 'dry-run should still classify the pending change as synced');
+    // ...but the `wrote` count is ACTUAL writes — zero under --dry-run.
+    assert.equal(res.wrote, 0, 'dry-run must report wrote === 0 (contract: 0 under --dry-run)');
+    // And nothing was actually written: no Claude bundle, no snapshot.
+    assert.ok(!existsSync(join(home, '.claude', 'skills', 'dr', 'SKILL.md')), 'dry-run must not materialize the Claude endpoint');
+    assert.ok(!existsSync(join(home, '.crouter', 'skill-sync', 'snapshots', PAIR.id)), 'dry-run must not write the snapshot base');
+});

package/dist/core/skill-sync/builtins.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Built-in export registry for the skill-sync subsystem.
+ *
+ * These are the crtr-*generated* host artifacts — the `crtr-skills` boot skill
+ * and any CLI slash-commands. Unlike the user-authored bidirectional manifest
+ * pairs (engine.ts), an export pair has a single source of truth (code), so it
+ * is one-way: render → marker-guarded write (see export.ts). The generators
+ * (`bootSkillBody`, `renderSlashTemplate`) and their version markers were moved
+ * here verbatim from bootstrap.ts when skill-sync became the sole host writer —
+ * marker strings are byte-identical so already-deployed artifacts roll forward.
+ */
+import type { RootDef } from '../command.js';
+/** A host runtime crtr exports generated artifacts into. */
+export type Host = 'claude' | 'pi';
+/** One destination for an export artifact. Only targets whose host root exists
+ *  are written — crtr never creates `~/.claude` or `~/.pi` itself (export.ts). */
+export interface HostTarget {
+    host: Host;
+    /** The leaf dir the artifact is written into (never the host root). */
+    dir: () => string;
+    /** `bundle` → `<dir>/<name>/SKILL.md` ; `file` → `<dir>/<name>.md`. */
+    layout: 'bundle' | 'file';
+}
+/** One crtr-generated export artifact and every host it reaches. */
+export interface ExportPair {
+    /** Stable id for logging, e.g. `@boot/crtr-skills` or `@cmd/<name>`. */
+    id: string;
+    /** On-disk artifact name (bundle dir name or file stem). */
+    name: string;
+    /** Marker prefix identifying a crtr-owned file (the clobber guard). */
+    markerPrefix: string;
+    /** Full file content incl. frontmatter + version marker. */
+    render: () => string;
+    /** Every host destination. Targets with an absent host root are skipped. */
+    targets: HostTarget[];
+}
+export declare const BOOT_SKILL_MARKER_PREFIX = "<!-- crtr-boot-skill v";
+export declare const SLASH_CMD_MARKER_PREFIX = "<!-- crtr-mode-cmd v";
+/** The crtr-generated export artifacts for this command tree: the boot skill
+ *  (both hosts, bundle layout) plus one pair per opted-in slash command (both
+ *  hosts, file layout). */
+export declare function builtinExportPairs(root: RootDef): ExportPair[];

package/dist/core/skill-sync/builtins.js

@@ -0,0 +1,112 @@
+/**
+ * Built-in export registry for the skill-sync subsystem.
+ *
+ * These are the crtr-*generated* host artifacts — the `crtr-skills` boot skill
+ * and any CLI slash-commands. Unlike the user-authored bidirectional manifest
+ * pairs (engine.ts), an export pair has a single source of truth (code), so it
+ * is one-way: render → marker-guarded write (see export.ts). The generators
+ * (`bootSkillBody`, `renderSlashTemplate`) and their version markers were moved
+ * here verbatim from bootstrap.ts when skill-sync became the sole host writer —
+ * marker strings are byte-identical so already-deployed artifacts roll forward.
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { collectSlashSpecs } from '../command.js';
+// ── Boot skill ───────────────────────────────────────────────────────────────
+const BOOT_SKILL_NAME = 'crtr-skills';
+const BOOT_SKILL_MARKER = '<!-- crtr-boot-skill v2 -->';
+export const BOOT_SKILL_MARKER_PREFIX = '<!-- crtr-boot-skill v';
+function bootSkillBody() {
+    return `---
+name: crtr-skills
+description: 'Author, list, search, and load crtr memory documents (knowledge, preferences) via the crtr CLI. These are durable agent memory — markdown future LLM sessions load on demand. Use when the user wants to remember/save knowledge, build a context primer, or recall a previously saved doc. Triggers: "save", "remember", "build context for", "what skills do we have", "skill for X".'
+argument-hint: [topic or verb]
+---
+
+${BOOT_SKILL_MARKER}
+
+# /crtr-skills — crtr memory router
+
+crtr memory documents = durable agent memory (kind: knowledge or preference).
+Written for **future LLM sessions**, not the user. \`crtr memory\` is the
+surface — author, discover, and load them.
+
+## Route by intent
+
+- **Capture** ("save", "remember", "build context for", "make a skill"):
+  \`crtr memory write <name> --kind <knowledge|preference>\` with the
+  body piped on stdin — e.g.
+  \`crtr memory write $ARGUMENTS --kind knowledge <<'EOF' … EOF\`. Run
+  \`crtr memory write -h\` for the full frontmatter schema
+  (--when-and-why-to-read, --short-form, --scope, visibility rungs), then
+  \`crtr memory lint\` to validate what you wrote.
+- **Find** ("what do we have on X"): \`crtr memory find "$ARGUMENTS"\` →
+  \`crtr memory read <name>\` on the best hit (add --body/--grep to search
+  bodies).
+- **Load by name**: \`crtr memory read <name>\`.
+- **List all**: \`crtr memory list\`.
+
+If \`$ARGUMENTS\` is empty, ask the user what they want before running.
+
+## Rules
+
+- CLI stdout is the prompt — act on it, don't paraphrase to the user.
+- Append \`-h\` at any leaf (\`crtr memory write -h\`) for its full schema
+  before authoring.
+- If \`crtr\` is not on PATH, tell the user and stop.
+`;
+}
+// ── Slash commands ───────────────────────────────────────────────────────────
+const SLASH_CMD_MARKER = '<!-- crtr-mode-cmd v1 -->';
+export const SLASH_CMD_MARKER_PREFIX = '<!-- crtr-mode-cmd v';
+/** Render a SlashSpec to a full template file (frontmatter + marker + body). */
+function renderSlashTemplate(spec) {
+    const hint = spec.argumentHint !== undefined
+        ? `argument-hint: ${JSON.stringify(spec.argumentHint)}\n`
+        : '';
+    return `---\ndescription: ${spec.description}\n${hint}---\n\n${SLASH_CMD_MARKER}\n\n${spec.body}\n`;
+}
+// ── Host roots ───────────────────────────────────────────────────────────────
+function claudeSkillsRoot() {
+    return join(homedir(), '.claude', 'skills');
+}
+function piSkillsRoot() {
+    return join(homedir(), '.pi', 'agent', 'skills');
+}
+function claudeCommandsRoot() {
+    return join(homedir(), '.claude', 'commands');
+}
+function piPromptsRoot() {
+    return join(homedir(), '.pi', 'agent', 'prompts');
+}
+// ── Registry ─────────────────────────────────────────────────────────────────
+/** The crtr-generated export artifacts for this command tree: the boot skill
+ *  (both hosts, bundle layout) plus one pair per opted-in slash command (both
+ *  hosts, file layout). */
+export function builtinExportPairs(root) {
+    const pairs = [
+        {
+            id: '@boot/crtr-skills',
+            name: BOOT_SKILL_NAME,
+            markerPrefix: BOOT_SKILL_MARKER_PREFIX,
+            render: bootSkillBody,
+            targets: [
+                { host: 'claude', dir: claudeSkillsRoot, layout: 'bundle' },
+                { host: 'pi', dir: piSkillsRoot, layout: 'bundle' },
+            ],
+        },
+    ];
+    for (const spec of collectSlashSpecs(root)) {
+        pairs.push({
+            id: `@cmd/${spec.name}`,
+            name: spec.name,
+            markerPrefix: SLASH_CMD_MARKER_PREFIX,
+            render: () => renderSlashTemplate(spec),
+            targets: [
+                { host: 'claude', dir: claudeCommandsRoot, layout: 'file' },
+                { host: 'pi', dir: piPromptsRoot, layout: 'file' },
+            ],
+        });
+    }
+    return pairs;
+}

package/dist/core/skill-sync/claude-plugins.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Claude-plugin endpoint resolution for skill-sync.
+ *
+ * The `claude-plugin` endpoint scope addresses a skill IN PLACE at the path
+ * where Claude actually installs the owning plugin — `<installPath>/skills/<name>`
+ * — instead of forcing a copy under `~/.claude/skills/`. The install path is read
+ * from Claude's OWN registry (`~/.claude/plugins/installed_plugins.json`), keyed
+ * by the marketplace-qualified plugin key (`<plugin>@<marketplace>`), gated on the
+ * enable state in `~/.claude/settings.json` → `enabledPlugins`.
+ *
+ * This is Claude's registry, deliberately NOT crtr's plugin registry
+ * (`resolver.ts` / `findPluginByName`): the two are independent installs.
+ *
+ * Strictness (no lenient fallback): a key that is unknown, disabled, or whose
+ * recorded install path is missing on disk is a HARD error naming it.
+ */
+/**
+ * Resolve a Claude plugin's on-disk install path from its marketplace-qualified
+ * key (`<plugin>@<marketplace>`, e.g. `devcore@crouton-kit`). Throws naming the
+ * key when it is not installed, not enabled, or has no install path present on
+ * disk.
+ */
+export declare function resolveClaudePluginInstallPath(key: string): string;