@crouton-kit/crouter 0.1.4 → 0.1.6

package/dist/core/bootstrap.js

@@ -1,6 +1,8 @@
+import { writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { userScopeRoot } from './scope.js';
-import { ensureDir, pathExists, removePath, nowIso } from './fs-utils.js';
+import { ensureDir, pathExists, readText, removePath, nowIso } from './fs-utils.js';
 import { readConfig, readState, updateConfig, updateState, ensureScopeInitialized } from './config.js';
 import { clone } from './git.js';
 import { readMarketplaceManifest } from './manifest.js';
@@ -20,6 +22,83 @@ function shouldSkipForArgv(argv) {
         return true;
     return SKIP_SUBCOMMANDS.has(sub);
 }
+const BOOT_SKILL_NAME = 'crtr-skills';
+const BOOT_SKILL_MARKER = '<!-- crtr-boot-skill v1 -->';
+function bootSkillBody() {
+    return `---
+name: crtr-skills
+description: Capture, list, search, and load skills via the crtr CLI. Use when the user wants to remember something, save knowledge, build a context primer, or recall a previously saved skill. Triggers: "save", "remember", "build context for", "what skills do we have", "skill for X".
+argument-hint: [topic or verb]
+---
+
+${BOOT_SKILL_MARKER}
+
+# /crtr:skills — the skill router
+
+\`crtr\` is the source of truth for skills on this machine. Every skill the
+agent should know about is discoverable via \`crtr skill\`. This file is a
+thin router; the CLI is the index.
+
+## What the user is asking for
+
+- **Capture new knowledge** ("save this", "remember", "build context for X",
+  "make a skill that…"): run \`crtr skill create $ARGUMENTS\` and follow the
+  walkthrough it prints. It picks a template (primer/preference/runbook/
+  glossary/decision/freeform) and walks you through scoping, researching,
+  and scaffolding.
+- **Find a relevant skill** ("what do we have on X"): run
+  \`crtr skill search "$ARGUMENTS"\` and load the best hit with
+  \`crtr skill show <name>\`.
+- **Load a known skill by name**: run \`crtr skill show <name>\`.
+- **List everything**: run \`crtr skill list\`.
+- **Anything else skill-related**: run \`crtr skill\` (no args) — it prints
+  the full skill workflow guide. Follow it.
+
+\`$ARGUMENTS\` is the user's request as a string. Use it to seed the topic for
+\`create\` or the query for \`search\`. If it's empty, ask the user what they
+want before running anything.
+
+## Output rules
+
+The CLI's stdout is the prompt. Read it, then act on it. Don't paraphrase the
+guidance back at the user — just do the work it describes.
+
+If \`crtr\` isn't on PATH, tell the user and stop. This skill assumes
+\`@crouton-kit/crouter\` is installed globally.
+`;
+}
+export function ensureBootSkill(argv) {
+    try {
+        if (process.env.CRTR_NO_BOOT_SKILL === '1')
+            return;
+        if (shouldSkipForArgv(argv))
+            return;
+        const claudeSkillsRoot = join(homedir(), '.claude', 'skills');
+        // Only install if the user actually uses Claude Code (the dir exists or is
+        // creatable). We won't create ~/.claude itself; that's not our directory.
+        if (!pathExists(join(homedir(), '.claude')))
+            return;
+        const skillDir = join(claudeSkillsRoot, BOOT_SKILL_NAME);
+        const skillFile = join(skillDir, 'SKILL.md');
+        if (pathExists(skillFile)) {
+            // Idempotent: only rewrite if it's still our marker version.
+            const existing = readText(skillFile);
+            if (!existing.includes(BOOT_SKILL_MARKER))
+                return;
+            // Same marker — check if body needs update, otherwise skip.
+            if (existing === bootSkillBody())
+                return;
+        }
+        ensureDir(skillDir);
+        writeFileSync(skillFile, bootSkillBody(), 'utf8');
+    }
+    catch (e) {
+        if (process.env.CRTR_DEBUG === '1') {
+            const msg = e instanceof Error ? e.message : String(e);
+            process.stderr.write(`crtr: boot-skill error: ${msg}\n`);
+        }
+    }
+}
 export function ensureOfficialMarketplace(argv) {
     try {
         if (process.env.CRTR_NO_BOOTSTRAP === '1')

package/dist/core/config.js

@@ -81,7 +81,11 @@ function mergeConfig(partial) {
         content: normalizeMode(au?.content, defaults.auto_update.content),
         interval_hours,
     };
-    return { schema_version, marketplaces, plugins, skills, auto_update };
+    const rawMaxPanes = partial.max_panes_per_window;
+    const max_panes_per_window = typeof rawMaxPanes === 'number' && Number.isFinite(rawMaxPanes) && rawMaxPanes >= 1
+        ? Math.floor(rawMaxPanes)
+        : defaults.max_panes_per_window;
+    return { schema_version, marketplaces, plugins, skills, auto_update, max_panes_per_window };
 }
 export function updateConfig(scope, mutate) {
     const cfg = readConfig(scope);

package/dist/core/resolver.d.ts

@@ -11,6 +11,7 @@ export declare function effectiveSkillEnabled(pluginName: string, skillName: str
     disabledIn?: Scope;
 };
 export declare function listSkillsInPlugin(plugin: InstalledPlugin, cfgs?: ScopeConfigs): Skill[];
+export declare function listScopeRootSkills(scope: Scope, cfgs?: ScopeConfigs): Skill[];
 export declare function listAllSkills(scopeFilter?: Scope): Skill[];
 export interface SkillResolutionOpts {
     scope?: Scope;

package/dist/core/resolver.js

@@ -1,11 +1,11 @@
 import { join, relative, sep, dirname } from 'node:path';
-import { SKILL_ENTRY_FILE, SKILLS_DIR, skillConfigKey, } from '../types.js';
+import { SCOPE_SKILL_PLUGIN, SKILL_ENTRY_FILE, SKILLS_DIR, skillConfigKey, } from '../types.js';
 import { readConfig } from './config.js';
 import { listDirs, pathExists, readText, walkFiles, } from './fs-utils.js';
 import { readMarketplaceManifest, readPluginManifest } from './manifest.js';
 import { parseFrontmatter } from './frontmatter.js';
 import { ambiguous, notFound } from './errors.js';
-import { marketplacesDir, pluginsDir, projectScopeRoot, userScopeRoot } from './scope.js';
+import { marketplacesDir, pluginsDir, projectScopeRoot, scopeSkillsDir, userScopeRoot, } from './scope.js';
 export function listInstalledPlugins(scope) {
     const dir = pluginsDir(scope);
     if (!dir || !pathExists(dir))
@@ -99,20 +99,80 @@ export function listSkillsInPlugin(plugin, cfgs) {
     }
     return skills.sort((a, b) => a.name.localeCompare(b.name));
 }
+export function listScopeRootSkills(scope, cfgs) {
+    const skillsRoot = scopeSkillsDir(scope);
+    if (!skillsRoot || !pathExists(skillsRoot))
+        return [];
+    const configs = cfgs === undefined ? loadScopeConfigs() : cfgs;
+    const skills = [];
+    const skillFiles = walkFiles(skillsRoot, (n) => n === SKILL_ENTRY_FILE);
+    for (const file of skillFiles) {
+        const rel = relative(skillsRoot, dirname(file));
+        const name = rel.split(sep).join('/');
+        if (!name)
+            continue;
+        const source = readText(file);
+        const { data } = parseFrontmatter(source);
+        const { enabled, disabledIn } = effectiveSkillEnabled(SCOPE_SKILL_PLUGIN, name, configs);
+        skills.push({
+            name,
+            plugin: SCOPE_SKILL_PLUGIN,
+            scope,
+            path: file,
+            pluginRoot: skillsRoot,
+            frontmatter: data === null ? { name } : data,
+            enabled,
+            disabledIn,
+        });
+    }
+    return skills.sort((a, b) => a.name.localeCompare(b.name));
+}
 export function listAllSkills(scopeFilter) {
     const plugins = scopeFilter ? listInstalledPlugins(scopeFilter) : listAllPlugins();
     const cfgs = loadScopeConfigs();
-    return plugins
-        .filter((p) => p.enabled)
-        .flatMap((p) => listSkillsInPlugin(p, cfgs));
+    const scopes = scopeFilter
+        ? [scopeFilter]
+        : [projectScopeRoot() ? 'project' : null, 'user'].filter(Boolean);
+    return [
+        ...scopes.flatMap((s) => listScopeRootSkills(s, cfgs)),
+        ...plugins.filter((p) => p.enabled).flatMap((p) => listSkillsInPlugin(p, cfgs)),
+    ];
 }
 export function resolveSkill(rawName, opts = {}) {
     const { plugin: pluginQualifier, name } = parseSkillQualifier(rawName);
     const plugins = opts.scope ? listInstalledPlugins(opts.scope) : listAllPlugins();
     const enabledPlugins = plugins.filter((p) => p.enabled);
     const cfgs = loadScopeConfigs();
-    const ordered = orderPluginsByResolution(enabledPlugins);
     const matches = [];
+    // Scope-root skills first — they're the user's own captured knowledge.
+    if (!opts.pluginFilter &&
+        (pluginQualifier === undefined || pluginQualifier === SCOPE_SKILL_PLUGIN)) {
+        const scopes = opts.scope
+            ? [opts.scope]
+            : [projectScopeRoot() ? 'project' : null, 'user'].filter(Boolean);
+        for (const s of scopes) {
+            const skillsRoot = scopeSkillsDir(s);
+            if (!skillsRoot)
+                continue;
+            const skillPath = join(skillsRoot, ...name.split('/'), SKILL_ENTRY_FILE);
+            if (!pathExists(skillPath))
+                continue;
+            const source = readText(skillPath);
+            const { data } = parseFrontmatter(source);
+            const { enabled, disabledIn } = effectiveSkillEnabled(SCOPE_SKILL_PLUGIN, name, cfgs);
+            matches.push({
+                name,
+                plugin: SCOPE_SKILL_PLUGIN,
+                scope: s,
+                path: skillPath,
+                pluginRoot: skillsRoot,
+                frontmatter: data === null ? { name } : data,
+                enabled,
+                disabledIn,
+            });
+        }
+    }
+    const ordered = orderPluginsByResolution(enabledPlugins);
     for (const plugin of ordered) {
         if (pluginQualifier && plugin.name !== pluginQualifier)
             continue;

package/dist/core/scope.d.ts

@@ -7,6 +7,7 @@ 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;
 export declare function resolveScopeArg(scopeArg: string | undefined): Scope | 'all';
 export declare function listScopes(scopeArg: string | undefined): Scope[];
 export declare function resetScopeCache(): void;

package/dist/core/scope.js

@@ -63,6 +63,10 @@ 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;
+}
 export function resolveScopeArg(scopeArg) {
     if (scopeArg === undefined)
         return 'all';

package/dist/core/spawn.d.ts

@@ -0,0 +1,95 @@
+export interface SidePaneOptions {
+    /** Full first user message — task + checklist + submit instructions all in one. */
+    prompt: string;
+    cwd: string;
+    timeoutMs: number;
+}
+export declare const DEFAULT_PANE_OPTS: {
+    timeoutMs: number;
+};
+export type SidePaneStatus = 'submitted' | 'timeout' | 'pane-closed' | 'spawn-failed';
+export interface SidePaneResult {
+    status: SidePaneStatus;
+    content: string;
+    paneId?: string;
+    sessionDir: string;
+}
+export declare function createSession(): {
+    id: string;
+    dir: string;
+};
+export declare function submitToSession(sessionDir: string, content: string): void;
+export interface DetachOptions {
+    /** Full first user message for the new claude session. No custom system prompt. */
+    prompt: string;
+    cwd: string;
+    /** Where to open the new pane. */
+    placement: 'split-h' | 'split-v' | 'new-window';
+    /** Seconds to wait before killing the originating pane so the caller can finish. */
+    killAfterSeconds: number;
+}
+export interface DetachResult {
+    status: 'spawned' | 'spawn-failed' | 'not-in-tmux';
+    paneId?: string;
+    message: string;
+}
+/**
+ * Fire-and-forget: launch an interactive `claude` in a new pane (or window),
+ * then schedule the originating pane to be killed after `killAfterSeconds`.
+ *
+ * No custom system prompt — the task is delivered as the first user message
+ * so the user can `/clear` to fall back to a normal default Claude session.
+ *
+ * Returns as soon as the new pane is up; does NOT wait for claude to finish.
+ */
+export declare function spawnAndDetach(opts: DetachOptions): DetachResult;
+/**
+ * Spawn a side-pane `claude` reviewer. Blocks until the reviewer calls
+ * `crtr agent submit <content>`, the 10-min budget elapses, or the pane is closed.
+ *
+ * No custom system prompt — the task is delivered as the first user message
+ * so the reviewer is a normal Claude session running a single task.
+ */
+export declare function spawnSidePaneReview(opts: SidePaneOptions): Promise<SidePaneResult>;
+export interface SpawnAgentOptions {
+    /** First user message for the new claude session. */
+    prompt: string;
+    cwd: string;
+    /** If set, resume this Claude Code session with --fork-session (new session id). */
+    fork?: {
+        sessionId: string;
+    };
+    /** Max panes per tmux window before overflowing to a new window. */
+    maxPanesPerWindow: number;
+}
+export interface SpawnAgentResult {
+    status: 'spawned' | 'spawn-failed' | 'not-in-tmux';
+    /** crtr session UUID — pass to `crtr agent await` to receive the result. */
+    sessionId?: string;
+    /** tmux pane id of the spawned pane. */
+    paneId?: string;
+    /** How the pane was placed. */
+    placement?: 'split-window' | 'new-window';
+    message: string;
+}
+export declare function sessionDirForId(sessionId: string): string;
+export declare function countPanesInCurrentWindow(): number;
+/**
+ * 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 crtr session id; the parent stays alive.
+ *
+ * If `fork` is set, uses `claude --resume <id> --fork-session` so the child
+ * gets a fresh session id and does not contend with the parent's JSONL.
+ */
+export declare function spawnAgent(opts: SpawnAgentOptions): SpawnAgentResult;
+export interface AwaitOptions {
+    timeoutMs: number;
+    /** Kill the child pane after content is received. Default true. */
+    killPane: boolean;
+}
+/**
+ * Block until the agent identified by `sessionId` calls `crtr agent submit`.
+ * Returns content + status. Cleans up the session dir on completion.
+ */
+export declare function awaitSession(sessionId: string, opts: AwaitOptions): Promise<SidePaneResult>;

package/dist/core/spawn.js

@@ -0,0 +1,309 @@
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, watch, readFileSync, existsSync, writeFileSync, renameSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { general, notFound } from './errors.js';
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+const PANE_POLL_MS = 2000;
+export const DEFAULT_PANE_OPTS = {
+    timeoutMs: DEFAULT_TIMEOUT_MS,
+};
+function isInTmux() {
+    return Boolean(process.env.TMUX);
+}
+function sessionRoot() {
+    const root = join(tmpdir(), 'crtr-sessions');
+    mkdirSync(root, { recursive: true });
+    return root;
+}
+export function createSession() {
+    const id = randomUUID();
+    const dir = join(sessionRoot(), id);
+    mkdirSync(dir, { recursive: true });
+    return { id, dir };
+}
+export function submitToSession(sessionDir, content) {
+    const tmp = join(sessionDir, '.content.tmp');
+    const final = join(sessionDir, 'content');
+    writeFileSync(tmp, content, 'utf8');
+    renameSync(tmp, final);
+}
+function paneAlive(paneId) {
+    const result = spawnSync('tmux', ['list-panes', '-a', '-F', '#{pane_id}'], {
+        encoding: 'utf8',
+    });
+    if (result.status !== 0)
+        return false;
+    return result.stdout.split('\n').some((line) => line.trim() === paneId);
+}
+function killPane(paneId) {
+    spawnSync('tmux', ['kill-pane', '-t', paneId], { stdio: 'ignore' });
+}
+function shellQuote(s) {
+    return `'${s.replace(/'/g, "'\\''")}'`;
+}
+/**
+ * Fire-and-forget: launch an interactive `claude` in a new pane (or window),
+ * then schedule the originating pane to be killed after `killAfterSeconds`.
+ *
+ * No custom system prompt — the task is delivered as the first user message
+ * so the user can `/clear` to fall back to a normal default Claude session.
+ *
+ * Returns as soon as the new pane is up; does NOT wait for claude to finish.
+ */
+export function spawnAndDetach(opts) {
+    if (!isInTmux()) {
+        return {
+            status: 'not-in-tmux',
+            message: 'handoff requires tmux (TMUX env var not set)',
+        };
+    }
+    const claudeCmd = [
+        'claude',
+        '--dangerously-skip-permissions',
+        shellQuote(opts.prompt),
+    ].join(' ');
+    const splitArgs = [];
+    if (opts.placement === 'new-window') {
+        splitArgs.push('new-window');
+    }
+    else {
+        splitArgs.push('split-window');
+        splitArgs.push(opts.placement === 'split-h' ? '-h' : '-v');
+    }
+    splitArgs.push('-P', '-F', '#{pane_id}');
+    splitArgs.push('-c', opts.cwd);
+    splitArgs.push(claudeCmd);
+    const split = spawnSync('tmux', splitArgs, { encoding: 'utf8' });
+    if (split.status !== 0) {
+        const stderrText = split.stderr.trim();
+        const msg = stderrText === '' ? 'tmux split-window/new-window failed' : stderrText;
+        return { status: 'spawn-failed', message: msg };
+    }
+    const paneId = split.stdout.trim();
+    // Schedule self-kill of the originating pane. We detach this so it survives
+    // crtr's exit.
+    const currentPane = process.env.TMUX_PANE;
+    if (currentPane !== undefined && currentPane !== '' && opts.killAfterSeconds > 0) {
+        const killCmd = `sleep ${opts.killAfterSeconds}; tmux kill-pane -t ${currentPane}`;
+        spawnSync('sh', ['-c', `nohup sh -c ${shellQuote(killCmd)} </dev/null >/dev/null 2>&1 &`], {
+            stdio: 'ignore',
+        });
+    }
+    return {
+        status: 'spawned',
+        paneId,
+        message: `handed off to pane ${paneId}; this pane will close in ${opts.killAfterSeconds}s`,
+    };
+}
+/**
+ * Spawn a side-pane `claude` reviewer. Blocks until the reviewer calls
+ * `crtr agent submit <content>`, the 10-min budget elapses, or the pane is closed.
+ *
+ * No custom system prompt — the task is delivered as the first user message
+ * so the reviewer is a normal Claude session running a single task.
+ */
+export async function spawnSidePaneReview(opts) {
+    if (!isInTmux()) {
+        throw general('side-pane review requires tmux (TMUX env var not set)');
+    }
+    const session = createSession();
+    const timeoutMs = opts.timeoutMs;
+    const cwd = opts.cwd;
+    const claudeCmd = [
+        'claude',
+        '-p',
+        '--dangerously-skip-permissions',
+        shellQuote(opts.prompt),
+    ].join(' ');
+    // After claude exits, sleep briefly so the watcher can confirm submission.
+    // The watcher kills the pane anyway once content arrives.
+    const fullCmd = `cd ${shellQuote(cwd)} && ${claudeCmd}; sleep 2`;
+    const splitArgs = [
+        'split-window',
+        '-h',
+        '-P',
+        '-F',
+        '#{pane_id}',
+        '-e',
+        `CRTR_SESSION=${session.id}`,
+        '-e',
+        `CRTR_PIPE=${session.dir}`,
+        fullCmd,
+    ];
+    const split = spawnSync('tmux', splitArgs, { encoding: 'utf8' });
+    if (split.status !== 0) {
+        rmSync(session.dir, { recursive: true, force: true });
+        const stderrText = split.stderr.trim();
+        const msg = stderrText === '' ? 'tmux split-window failed' : stderrText;
+        return {
+            status: 'spawn-failed',
+            content: msg,
+            sessionDir: session.dir,
+        };
+    }
+    const paneId = split.stdout.trim();
+    const contentPath = join(session.dir, 'content');
+    const result = await waitForResult(session.dir, contentPath, paneId, timeoutMs);
+    if (paneAlive(paneId))
+        killPane(paneId);
+    try {
+        rmSync(session.dir, { recursive: true, force: true });
+    }
+    catch {
+        /* noop */
+    }
+    return { ...result, paneId, sessionDir: session.dir };
+}
+function metaPath(sessionDir) {
+    return join(sessionDir, 'meta.json');
+}
+function writeSessionMeta(sessionDir, meta) {
+    writeFileSync(metaPath(sessionDir), JSON.stringify(meta), 'utf8');
+}
+function readSessionMeta(sessionDir) {
+    const p = metaPath(sessionDir);
+    if (!existsSync(p))
+        return undefined;
+    try {
+        return JSON.parse(readFileSync(p, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function sessionDirForId(sessionId) {
+    return join(sessionRoot(), sessionId);
+}
+export function countPanesInCurrentWindow() {
+    // -t '' targets the current window of the current session.
+    const result = spawnSync('tmux', ['list-panes', '-F', '#{pane_id}'], {
+        encoding: 'utf8',
+    });
+    if (result.status !== 0)
+        return 0;
+    return result.stdout.split('\n').filter((line) => line.trim() !== '').length;
+}
+/**
+ * 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 crtr session id; the parent stays alive.
+ *
+ * If `fork` is set, uses `claude --resume <id> --fork-session` so the child
+ * gets a fresh session id and does not contend with the parent's JSONL.
+ */
+export function spawnAgent(opts) {
+    if (!isInTmux()) {
+        return {
+            status: 'not-in-tmux',
+            message: 'crtr agent requires tmux (TMUX env var not set)',
+        };
+    }
+    const session = createSession();
+    const claudeParts = ['claude'];
+    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 useNewWindow = countPanesInCurrentWindow() >= opts.maxPanesPerWindow;
+    const placement = useNewWindow ? 'new-window' : 'split-window';
+    const tmuxArgs = [placement];
+    if (!useNewWindow)
+        tmuxArgs.push('-h');
+    tmuxArgs.push('-P', '-F', '#{pane_id}', '-c', opts.cwd, '-e', `CRTR_SESSION=${session.id}`, '-e', `CRTR_PIPE=${session.dir}`, claudeCmd);
+    const split = spawnSync('tmux', tmuxArgs, { encoding: 'utf8' });
+    if (split.status !== 0) {
+        rmSync(session.dir, { recursive: true, force: true });
+        const stderrText = split.stderr.trim();
+        const msg = stderrText === '' ? `tmux ${placement} failed` : stderrText;
+        return { status: 'spawn-failed', message: msg };
+    }
+    const paneId = split.stdout.trim();
+    writeSessionMeta(session.dir, {
+        paneId,
+        createdAt: Date.now(),
+        kind: opts.fork !== undefined ? 'fork' : 'new',
+    });
+    return {
+        status: 'spawned',
+        sessionId: session.id,
+        paneId,
+        placement,
+        message: `agent ${session.id} spawned in pane ${paneId} (${placement})`,
+    };
+}
+/**
+ * Block until the agent identified by `sessionId` calls `crtr agent submit`.
+ * Returns content + status. Cleans up the session dir on completion.
+ */
+export async function awaitSession(sessionId, opts) {
+    const sessionDir = sessionDirForId(sessionId);
+    if (!existsSync(sessionDir)) {
+        throw notFound(`agent session not found: ${sessionId} (looked at ${sessionDir})`);
+    }
+    const meta = readSessionMeta(sessionDir);
+    let paneId;
+    if (meta !== undefined && meta.paneId !== '') {
+        paneId = meta.paneId;
+    }
+    const contentPath = join(sessionDir, 'content');
+    const result = await waitForResult(sessionDir, contentPath, paneId, opts.timeoutMs);
+    if (opts.killPane && paneId !== undefined && paneAlive(paneId))
+        killPane(paneId);
+    try {
+        rmSync(sessionDir, { recursive: true, force: true });
+    }
+    catch {
+        /* noop */
+    }
+    return { ...result, paneId, sessionDir };
+}
+function waitForResult(sessionDir, contentPath, paneId, timeoutMs) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (status, content) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeoutTimer);
+            if (paneTimer !== undefined)
+                clearInterval(paneTimer);
+            try {
+                watcher.close();
+            }
+            catch {
+                /* noop */
+            }
+            resolve({ status, content });
+        };
+        const watcher = watch(sessionDir, (_event, name) => {
+            if (name === 'content' && existsSync(contentPath)) {
+                const content = readFileSync(contentPath, 'utf8');
+                finish('submitted', content);
+            }
+        });
+        if (existsSync(contentPath)) {
+            finish('submitted', readFileSync(contentPath, 'utf8'));
+            return;
+        }
+        const timeoutTimer = setTimeout(() => {
+            finish('timeout', '');
+        }, timeoutMs);
+        let paneTimer;
+        if (paneId !== undefined) {
+            const watchedPaneId = paneId;
+            paneTimer = setInterval(() => {
+                if (!paneAlive(watchedPaneId)) {
+                    if (existsSync(contentPath)) {
+                        finish('submitted', readFileSync(contentPath, 'utf8'));
+                    }
+                    else {
+                        finish('pane-closed', '');
+                    }
+                }
+            }, PANE_POLL_MS);
+        }
+    });
+}

package/dist/prompts/agent.d.ts

@@ -0,0 +1,13 @@
+/**
+ * First user message for a spec → plan handoff.
+ * Bundles the full planning workflow with the spec to plan.
+ */
+export declare function planHandoffPrompt(specPath: string, plansDir: string): string;
+/**
+ * First user message for a plan → implementation handoff.
+ */
+export declare function implementHandoffPrompt(planPath: string): string;
+/**
+ * First user message for a handoff to code review of the working tree.
+ */
+export declare function reviewHandoffPrompt(): string;