@crouton-kit/crouter 0.3.3 → 0.3.8

package/dist/core/spawn.js

@@ -1,7 +1,7 @@
 // Tmux pane spawning machinery for crtr job subtree.
 //
 // Kept: spawnAgent (fire-and-forget new pane), spawnAndDetach (detach + kill originating pane),
-//       shellQuote, isInTmux, countPanesInCurrentWindow.
+//       shellQuote, isInTmux, countPanesInCurrentWindow, findWindowWithSpace.
 //
 // Removed: createSession, submitToSession, awaitSession, waitForResult,
 //          sessionDirForId, writeSessionMeta, readSessionMeta — all superseded
@@ -28,6 +28,118 @@ export function countPanesInCurrentWindow() {
         return 0;
     return result.stdout.split('\n').filter((line) => line.trim() !== '').length;
 }
+function listWindowsInCurrentSession() {
+    const result = spawnSync('tmux', ['list-windows', '-F', '#{window_id} #{window_panes} #{window_active}'], { encoding: 'utf8' });
+    if (result.status !== 0)
+        return [];
+    return result.stdout
+        .split('\n')
+        .filter((line) => line.trim() !== '')
+        .map((line) => {
+        const [id, count, active] = line.split(' ');
+        return {
+            windowId: id,
+            paneCount: Number.parseInt(count, 10),
+            isActive: active === '1',
+        };
+    });
+}
+/**
+ * Map of window_id → list of pane TTYs (basename, e.g. `ttys008`) for every
+ * pane in the current tmux session. Used as the bridge between tmux's pane
+ * model and the system process table for foreground-command lookup.
+ *
+ * tmux's `#{pane_current_command}` is unreliable on macOS because the Claude
+ * Code CLI sets `process.title` to its version (e.g. `2.1.143`), which is what
+ * tmux then reports. Going through the TTY + `ps` gives us the real binary
+ * name (`claude`) from the kernel.
+ */
+function paneTtysByWindow() {
+    const result = spawnSync('tmux', ['list-panes', '-s', '-F', '#{window_id} #{pane_tty}'], { encoding: 'utf8' });
+    const out = new Map();
+    if (result.status !== 0)
+        return out;
+    for (const line of result.stdout.split('\n')) {
+        if (line.trim() === '')
+            continue;
+        const idx = line.indexOf(' ');
+        if (idx === -1)
+            continue;
+        const windowId = line.slice(0, idx);
+        const tty = line.slice(idx + 1);
+        const ttyBase = tty.startsWith('/dev/') ? tty.slice(5) : tty;
+        const existing = out.get(windowId);
+        if (existing === undefined) {
+            out.set(windowId, [ttyBase]);
+        }
+        else {
+            existing.push(ttyBase);
+        }
+    }
+    return out;
+}
+/**
+ * Map of tty basename → set of foreground process `comm` names on that tty.
+ * A process is "foreground" if its STAT field includes `+` (member of the
+ * terminal's foreground process group). Built from one `ps -axo ...` call.
+ */
+function foregroundCommsByTty() {
+    const result = spawnSync('ps', ['-axo', 'stat=,comm=,tty='], { encoding: 'utf8' });
+    const out = new Map();
+    if (result.status !== 0)
+        return out;
+    for (const line of result.stdout.split('\n')) {
+        if (line.trim() === '')
+            continue;
+        const m = line.match(/^(\S+)\s+(.+?)\s+(\S+)\s*$/);
+        if (m === null)
+            continue;
+        const [, stat, comm, tty] = m;
+        if (!stat.includes('+'))
+            continue;
+        if (tty === '??' || tty === '?')
+            continue;
+        const existing = out.get(tty);
+        if (existing === undefined) {
+            out.set(tty, new Set([comm.trim()]));
+        }
+        else {
+            existing.add(comm.trim());
+        }
+    }
+    return out;
+}
+/**
+ * Find a window in the current tmux session with fewer than `maxPanesPerWindow`
+ * panes AND where every existing pane has `claude` as a foreground process.
+ * Prefers the active window so the spawned pane is visible to the user;
+ * otherwise falls back to the first other eligible window. Returns the tmux
+ * window id (e.g. `@5`) to pass via `-t`, or null if no window qualifies.
+ *
+ * Windows holding non-agent panes (dashboards, log tails, idle shells, editors,
+ * REPLs, etc.) are skipped so spawning never disrupts those workflows. A pane
+ * qualifies as long as `claude` is among its foreground commands — co-resident
+ * helpers like `caffeinate` don't disqualify it.
+ */
+export function findWindowWithSpace(maxPanesPerWindow) {
+    const windows = listWindowsInCurrentSession();
+    const ttysByWindow = paneTtysByWindow();
+    const fgByTty = foregroundCommsByTty();
+    const isClaudeOnly = (windowId) => {
+        const ttys = ttysByWindow.get(windowId);
+        if (ttys === undefined || ttys.length === 0)
+            return false;
+        return ttys.every((tty) => fgByTty.get(tty)?.has('claude') === true);
+    };
+    const eligible = windows.filter((w) => w.paneCount < maxPanesPerWindow && isClaudeOnly(w.windowId));
+    const active = eligible.find((w) => w.isActive);
+    if (active !== undefined)
+        return active.windowId;
+    const first = eligible[0];
+    if (first === undefined)
+        return null;
+    return first.windowId;
+}
 /**
  * Schedule a kill-pane on the *current* tmux pane after `delaySeconds`, detached
  * so the caller can return normally before the pane dies. No-op outside tmux
@@ -75,9 +187,15 @@ export function spawnAndDetach(opts) {
             message: 'handoff requires tmux (TMUX env var not set)',
         };
     }
-    const inner = opts.command !== undefined
-        ? opts.command
-        : ['claude', '--dangerously-skip-permissions', shellQuote(opts.prompt)].join(' ');
+    const buildClaudeInner = () => {
+        const parts = ['claude'];
+        if (opts.name !== undefined && opts.name !== '') {
+            parts.push('-n', shellQuote(opts.name));
+        }
+        parts.push('--dangerously-skip-permissions', shellQuote(opts.prompt));
+        return parts.join(' ');
+    };
+    const inner = opts.command !== undefined ? opts.command : buildClaudeInner();
     const useFailGuard = opts.failGuard !== false;
     const fullCmd = useFailGuard ? wrapperCmd(inner, opts.jobId) : inner;
     const splitArgs = [];
@@ -117,9 +235,14 @@ export function spawnAndDetach(opts) {
     };
 }
 /**
- * Async sibling spawn. Launches a claude session in a new tmux pane or window
- * (depending on current pane count vs maxPanesPerWindow). Returns immediately
- * with the pane id; the parent stays alive.
+ * Async sibling spawn. Launches a claude session in a tmux pane, progressively
+ * filling existing windows up to `maxPanesPerWindow` before creating a new
+ * window. Returns immediately with the pane id; the parent stays alive.
+ *
+ * Placement order:
+ *   1. Current window, if it has space.
+ *   2. Any other window in the session with space.
+ *   3. New window (every existing window at capacity).
  *
  * If `fork` is set, uses `claude --resume <id> --fork-session`.
  */
@@ -131,17 +254,21 @@ export function spawnAgent(opts) {
         };
     }
     const claudeParts = ['claude'];
+    if (opts.name !== undefined && opts.name !== '') {
+        claudeParts.push('-n', shellQuote(opts.name));
+    }
     if (opts.fork !== undefined) {
         claudeParts.push('--resume', opts.fork.sessionId, '--fork-session');
     }
     claudeParts.push('--dangerously-skip-permissions', shellQuote(opts.prompt));
     const claudeCmd = claudeParts.join(' ');
     const fullCmd = wrapperCmd(claudeCmd, opts.jobId);
-    const useNewWindow = countPanesInCurrentWindow() >= opts.maxPanesPerWindow;
-    const placement = useNewWindow ? 'new-window' : 'split-window';
+    const targetWindow = findWindowWithSpace(opts.maxPanesPerWindow);
+    const placement = targetWindow === null ? 'new-window' : 'split-window';
     const tmuxArgs = [placement];
-    if (!useNewWindow)
-        tmuxArgs.push('-h');
+    if (placement === 'split-window') {
+        tmuxArgs.push('-h', '-t', targetWindow);
+    }
     tmuxArgs.push('-P', '-F', '#{pane_id}', '-c', opts.cwd, '-e', `CRTR_JOB_ID=${opts.jobId}`, fullCmd);
     const split = spawnSync('tmux', tmuxArgs, { encoding: 'utf8' });
     if (split.status !== 0) {
@@ -150,6 +277,12 @@ export function spawnAgent(opts) {
         return { status: 'spawn-failed', message: msg };
     }
     const paneId = split.stdout.trim();
+    // Re-balance the target window's panes evenly so the new pane doesn't end up
+    // half the size of its siblings. -t <pane_id> resolves to the window it lives
+    // in for both placements (split + new-window).
+    spawnSync('tmux', ['select-layout', '-t', paneId, 'even-horizontal'], {
+        encoding: 'utf8',
+    });
     return {
         status: 'spawned',
         paneId,

package/dist/prompts/agent.d.ts

@@ -2,9 +2,9 @@
  * First user message for a spec → plan handoff.
  *
  * Thin prompt: the worker discovers the full planning workflow by running
- * `crtr flow plan new -h`, then saves the plan via `crtr flow plan new`. This avoids
- * embedding the planPrompt() blob here and keeps the prompt in sync with the
- * live CLI without any coupling.
+ * `crtr agent plan new -h`, then saves the plan via `crtr agent plan new`. This
+ * avoids embedding the planPrompt() blob here and keeps the prompt in sync
+ * with the live CLI without any coupling.
  */
 export declare function planHandoffPrompt(specPath: string, jobId: string): string;
 /**

package/dist/prompts/agent.js

@@ -3,30 +3,30 @@ import { planReviewPrompt, specReviewPrompt } from './review.js';
  * First user message for a spec → plan handoff.
  *
  * Thin prompt: the worker discovers the full planning workflow by running
- * `crtr flow plan new -h`, then saves the plan via `crtr flow plan new`. This avoids
- * embedding the planPrompt() blob here and keeps the prompt in sync with the
- * live CLI without any coupling.
+ * `crtr agent plan new -h`, then saves the plan via `crtr agent plan new`. This
+ * avoids embedding the planPrompt() blob here and keeps the prompt in sync
+ * with the live CLI without any coupling.
  */
 export function planHandoffPrompt(specPath, jobId) {
     return `You were launched in a new tmux pane to turn an approved spec into a plan.
 
 **Spec:** ${specPath}
 
-1. Run \`crtr flow plan new -h\` to load the planning workflow and output schema.
+1. Run \`crtr agent plan new -h\` to load the planning workflow and output schema.
 2. Read the spec end-to-end.
-3. Follow the workflow from step 1 and save the plan by passing the plan markdown to \`crtr flow plan new\` on stdin.
-4. When done, submit your result:
+3. Follow the workflow from step 1 and save the plan by passing the plan markdown to \`crtr agent plan new\` on stdin.
+4. When done, submit a short markdown report on stdin:
 
 \`\`\`bash
-echo '{"status":"done","plan_saved":true}' > /tmp/crtr-result-${jobId}.json
-crtr job submit ${jobId} --context-file /tmp/crtr-result-${jobId}.json
+crtr job submit ${jobId} <<'MD'
+Plan saved at <path>. <one-line summary of the plan's shape>.
+MD
 \`\`\`
 
-If you cannot complete the plan, still submit:
+If you cannot complete the plan, submit a failure with a reason:
 
 \`\`\`bash
-echo '{"status":"failed","reason":"<why>"}' > /tmp/crtr-result-${jobId}.json
-crtr job submit ${jobId} --context-file /tmp/crtr-result-${jobId}.json
+crtr job submit ${jobId} --status failed --reason "<why>"
 \`\`\`
 
 Begin now.`;
@@ -111,17 +111,19 @@ would be slower.
 
 ## Phase 6: Report and submit
 
-When all tasks complete and verification passes, submit your result:
+When all tasks complete and verification passes, submit a markdown report on stdin:
 
 \`\`\`bash
-echo '{"status":"done","summary":"<one-line summary of files touched>"}' > /tmp/crtr-result-${jobId}.json
-crtr job submit ${jobId} --context-file /tmp/crtr-result-${jobId}.json
+crtr job submit ${jobId} <<'MD'
+**Summary:** <one-line summary of files touched>
+
+<optional further notes — verification output, surprises, callouts>
+MD
 \`\`\`
 
-If implementation fails, still submit:
+If implementation fails, submit a failure with a reason:
 \`\`\`bash
-echo '{"status":"failed","reason":"<why>"}' > /tmp/crtr-result-${jobId}.json
-crtr job submit ${jobId} --context-file /tmp/crtr-result-${jobId}.json
+crtr job submit ${jobId} --status failed --reason "<why>"
 \`\`\`
 
 ## Guardrails (apply to you AND your subagents)
@@ -144,7 +146,7 @@ export function reviewerHandoffPrompt(artifactPath, artifactKind, specPath, jobI
     const reviewBody = artifactKind === 'spec'
         ? specReviewPrompt(artifactPath)
         : planReviewPrompt(artifactPath, specPath);
-    const patched = reviewBody.replace('__CRTR_SUBMIT_INSTRUCTION__', `the submit command injected below. The \`--kill-pane\` flag closes this reviewer pane after submission — keep it, do not drop it.\n\n\`\`\`bash\ncat > /tmp/crtr-result-${jobId}.json <<'JSON'\n{"status":"done","review":"<your full review markdown>"}\nJSON\ncrtr job submit ${jobId} --context-file /tmp/crtr-result-${jobId}.json --kill-pane\n\`\`\``);
+    const patched = reviewBody.replace('__CRTR_SUBMIT_INSTRUCTION__', `the submit command injected below. Pipe your full review markdown on stdin. The \`--kill-pane\` flag closes this reviewer pane after submission — keep it, do not drop it.\n\n\`\`\`bash\ncrtr job submit ${jobId} --kill-pane <<'MD'\n<your full review markdown — the same Status/Issues/Recommendations block you composed above>\nMD\n\`\`\`\n\nIf the artifact is too malformed to review, submit a failure instead:\n\n\`\`\`bash\ncrtr job submit ${jobId} --status failed --reason "<why>" --kill-pane\n\`\`\``);
     return `${patched}
 
 After calling \`crtr job submit\`, your turn ends and the pane closes itself. Do NOT chat or summarize after submission.`;

package/dist/prompts/debug.js

@@ -19,18 +19,25 @@ Rules — follow exactly:
 
 Submit exactly one of the following via \`crtr job submit\`, then your turn ends — do not chat:
 
-Reproduced:
+Reproduced (markdown body on stdin):
 \`\`\`bash
-cat > /tmp/crtr-result-${jobId}.json <<'JSON'
-{"status":"done","reproduces":true,"test_path":"<path>","test_command":"<exact cmd>","failure_output":"<pasted failing output>"}
-JSON
-crtr job submit ${jobId} --context-file /tmp/crtr-result-${jobId}.json
+crtr job submit ${jobId} <<'MD'
+**Reproduces:** yes
+
+**Test path:** <path>
+
+**Test command:** \`<exact cmd>\`
+
+**Failure output:**
+\`\`\`
+<pasted failing output>
+\`\`\`
+MD
 \`\`\`
 
 Gave up (no faithful repro achievable):
 \`\`\`bash
-echo '{"status":"failed","reproduces":false,"reason":"<why a faithful repro was not achievable>"}' > /tmp/crtr-result-${jobId}.json
-crtr job submit ${jobId} --context-file /tmp/crtr-result-${jobId}.json
+crtr job submit ${jobId} --status failed --reason "<why a faithful repro was not achievable>"
 \`\`\`
 
 Begin now.`;

package/dist/prompts/skill.js

@@ -111,7 +111,7 @@ are for large, complicated, or unintuitive systems only.
 ## 2. Scope + name
 
 - **Scope**: \`project\` by default. \`user\` only if cross-repo.
-- **Name**: kebab-case. Confirm no collision: \`crtr skill read where <name>\` (returns \`.path\`, \`.scope\`, \`.plugin\`).
+- **Name**: kebab-case. Confirm no collision: \`crtr skill read <name> --no-body\` (returns \`.path\`, \`.scope\`, \`.plugin\`).
 
 ## 3. Parallel exploration
 
@@ -178,7 +178,7 @@ Non-obvious coupling. Looks-broken-but-isn't. Past footguns.
 \`\`\`
 
 **No \`## Related\` for within-plugin siblings** — the CLI auto-appends a
-\`## Neighbors\` section on \`crtr skill read show <name>\`. Add a manual \`## Related\`
+\`## Neighbors\` section on \`crtr skill read <name>\`. Add a manual \`## Related\`
 only for cross-plugin or distant refs.
 
 **Density rules:**
@@ -195,8 +195,8 @@ only for cross-plugin or distant refs.
 Output is JSON; \`.content\` has the body, \`.path\` has the location:
 
 \`\`\`
-crtr skill read where <name>
-crtr skill read show <name>
+crtr skill read <name> --no-body
+crtr skill read <name>
 crtr skill find search "<keyword>"    # confirm description triggers discovery
 \`\`\`
 
@@ -246,7 +246,7 @@ PR over many small ones for refactors here, because review churn dominates"*
 
 - **Scope**: \`user\` for cross-project methodology. \`project\` for repo-specific.
 - **Name**: kebab-case, verb-or-noun-phrase. Not "guide-to-X".
-- Check \`crtr skill read where <name>\` (returns \`.path\`, \`.scope\`, \`.plugin\`).
+- Check \`crtr skill read <name> --no-body\` (returns \`.path\`, \`.scope\`, \`.plugin\`).
 
 ## 3. Scaffold
 
@@ -297,7 +297,7 @@ to read the whole thing for value, you've buried the judgment.
 \`\`\`
 
 **No \`## Related\` for within-plugin siblings** — the CLI auto-appends a
-\`## Neighbors\` section on \`crtr skill read show <name>\`. Add a manual \`## Related\`
+\`## Neighbors\` section on \`crtr skill read <name>\`. Add a manual \`## Related\`
 only for cross-plugin or distant refs.
 
 ## 6. Progressive disclosure
@@ -319,8 +319,8 @@ loads supporting files only when needed.
 Output is JSON; \`.content\` has the body, \`.path\` has the location:
 
 \`\`\`
-crtr skill read where <name>
-crtr skill read show <name>
+crtr skill read <name> --no-body
+crtr skill read <name>
 crtr skill find search "<keyword>"
 \`\`\`
 
@@ -410,8 +410,8 @@ Or invent your own. Stay tight — no padding.
 Output is JSON; \`.content\` has the body, \`.path\` has the location:
 
 \`\`\`
-crtr skill read where <name>
-crtr skill read show <name>
+crtr skill read <name> --no-body
+crtr skill read <name>
 crtr skill find search "<keyword>"
 \`\`\`
 
@@ -464,7 +464,7 @@ field/flag/code values** — pull verbatim from source.
 
 - **Scope**: \`user\` for cross-project facts. \`project\` for repo-specific.
 - **Name**: noun-phrase. \`http-status-codes\` not \`learn-http-status\`.
-- Check \`crtr skill read where <name>\` (returns \`.path\`, \`.scope\`, \`.plugin\`).
+- Check \`crtr skill read <name> --no-body\` (returns \`.path\`, \`.scope\`, \`.plugin\`).
 
 ## 3. Scaffold
 
@@ -525,8 +525,8 @@ SKILL.md links to siblings (\`see [full-table.md](full-table.md)\`).
 Output is JSON; \`.content\` has the body, \`.path\` has the location:
 
 \`\`\`
-crtr skill read where <name>
-crtr skill read show <name>
+crtr skill read <name> --no-body
+crtr skill read <name>
 crtr skill find search "<keyword>"
 \`\`\`
 
@@ -577,7 +577,7 @@ push to \\\`main\\\`, wait for green CI, click promote"* is a runbook step.
 
 - **Scope**: \`project\` for repo-specific procedures. \`user\` for cross-project.
 - **Name**: verb-phrase. \`deploy-to-prod\` not \`production-deployment-guide\`.
-- Check \`crtr skill read where <name>\` (returns \`.path\`, \`.scope\`, \`.plugin\`).
+- Check \`crtr skill read <name> --no-body\` (returns \`.path\`, \`.scope\`, \`.plugin\`).
 
 ## 3. Scaffold
 
@@ -632,8 +632,8 @@ crtr skill author scaffold <name> --type runbook --scope <user|project> --descri
 Output is JSON; \`.content\` has the body, \`.path\` has the location:
 
 \`\`\`
-crtr skill read where <name>
-crtr skill read show <name>
+crtr skill read <name> --no-body
+crtr skill read <name>
 crtr skill find search "<keyword>"
 \`\`\`
 

package/dist/types.d.ts

@@ -8,7 +8,7 @@ export declare const ExitCode: {
     readonly NETWORK: 5;
 };
 export type ExitCodeValue = (typeof ExitCode)[keyof typeof ExitCode];
-export declare const SCHEMA_VERSION = 1;
+export declare const SCHEMA_VERSION = 2;
 export interface OwnerRef {
     name?: string;
     email?: string;

package/dist/types.js

@@ -6,7 +6,7 @@ export const ExitCode = {
     AMBIGUOUS: 4,
     NETWORK: 5,
 };
-export const SCHEMA_VERSION = 1;
+export const SCHEMA_VERSION = 2;
 export const SKILL_TYPES = ['playbook', 'primer', 'reference', 'runbook', 'freeform'];
 export function isSkillType(v) {
     return typeof v === 'string' && SKILL_TYPES.includes(v);
@@ -36,7 +36,7 @@ export function defaultScopeConfig() {
     };
 }
 export function skillConfigKey(plugin, name) {
-    return `${plugin}:${name}`;
+    return `${plugin}/${name}`;
 }
 export function defaultScopeState() {
     return { marketplaces: {}, plugins: {} };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/crouter",
-  "version": "0.3.3",
+  "version": "0.3.8",
   "description": "crtr — fast access to skills, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",
@@ -35,7 +35,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@crouton-kit/humanloop": "^0.3.8",
+    "@crouton-kit/humanloop": "^0.3.11",
     "commander": "^13.0.0"
   },
   "devDependencies": {

package/dist/commands/flow.js

@@ -1,24 +0,0 @@
-// `crtr flow` umbrella — groups the spec → plan → debug development process.
-// registerSpec/registerPlan are unchanged (each still defineBranch{name}); they
-// nest under `flow` here instead of registering at root. registerDebug is a
-// leaf — `crtr flow debug` spawns directly and `-h` prints FLOW_DEBUG_GUIDE.
-import { defineBranch } from '../core/command.js';
-import { registerSpec } from './spec.js';
-import { registerPlan } from './plan.js';
-import { registerDebug } from './debug.js';
-export function registerFlow() {
-    return defineBranch({
-        name: 'flow',
-        help: {
-            name: 'flow',
-            summary: 'the spec → plan → debug development process',
-            model: 'spec captures requirements; plan decomposes them; debug root-causes failures reproduce-first.',
-            children: [
-                { name: 'spec', desc: 'create, read, list specifications', useWhen: 'capturing requirements before planning' },
-                { name: 'plan', desc: 'create, read, list plans', useWhen: 'shaping or inspecting work' },
-                { name: 'debug', desc: 'reproduce-first root-cause workflow', useWhen: 'a bug, test failure, or unexpected behavior needs root-causing' },
-            ],
-        },
-        children: [registerSpec(), registerPlan(), registerDebug()],
-    });
-}