@crouton-kit/crouter 0.3.3 → 0.3.8

package/dist/core/jobs.js

@@ -6,7 +6,9 @@
 // Layout: ${XDG_STATE_HOME or ~/.local/state}/crtr/jobs/<job_id>/
 //   meta.json    — written atomically on create; updated atomically on terminal transition.
 //   log.jsonl    — append-only event log.
-//   result.json  — written atomically; its APPEARANCE is the only completion signal.
+//   result.md    — agent submissions (markdown body + YAML frontmatter). Written atomically.
+//   result.json  — programmatic submissions (structured object). Written atomically.
+// Either result file's APPEARANCE is the completion signal. Exactly one is written per job.
 import { existsSync, mkdirSync, appendFileSync, readFileSync, writeFileSync, renameSync, readdirSync, statSync, } from 'node:fs';
 import { watch } from 'node:fs';
 import { spawnSync } from 'node:child_process';
@@ -31,9 +33,22 @@ function metaPath(jobId) {
 function logPath(jobId) {
     return join(jobDir(jobId), 'log.jsonl');
 }
-function resultPath(jobId) {
+function resultJsonPath(jobId) {
     return join(jobDir(jobId), 'result.json');
 }
+function resultMdPath(jobId) {
+    return join(jobDir(jobId), 'result.md');
+}
+/** Path of whichever result file currently exists, or null if neither does. */
+function existingResultPath(jobId) {
+    const md = resultMdPath(jobId);
+    if (existsSync(md))
+        return md;
+    const js = resultJsonPath(jobId);
+    if (existsSync(js))
+        return js;
+    return null;
+}
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
@@ -129,9 +144,9 @@ export function appendEvent(jobId, event) {
     appendFileSync(p, JSON.stringify(line) + '\n', 'utf8');
 }
 /**
- * Atomically write result.json and update meta.json status.
- * result.json's appearance is the ONLY completion signal — never inferred from
- * log content.
+ * Atomically write result.json (structured object) and update meta.json status.
+ * Used by programmatic callers (human, sys) that produce object results.
+ * The result file's appearance is the completion signal — never inferred from log content.
  */
 export function writeResult(jobId, result, terminalStatus) {
     const dir = jobDir(jobId);
@@ -143,44 +158,124 @@ export function writeResult(jobId, result, terminalStatus) {
         result,
         written_at: new Date().toISOString(),
     };
-    // Atomic write: tmp + rename within same directory (same fs, rename is atomic).
     const tmp = join(dir, '.result.tmp');
     writeFileSync(tmp, JSON.stringify(payload, null, 2), 'utf8');
-    renameSync(tmp, resultPath(jobId));
-    // Update meta status.
+    renameSync(tmp, resultJsonPath(jobId));
+    const meta = readMeta(jobId);
+    meta.status = terminalStatus;
+    writeMeta(jobId, meta);
+}
+/**
+ * Atomically write result.md (YAML frontmatter + markdown body) and update meta.json status.
+ * Used by `crtr job submit` for agent-driven markdown results.
+ */
+export function writeMarkdownResult(jobId, body, terminalStatus, reason) {
+    const dir = jobDir(jobId);
+    if (!existsSync(dir)) {
+        throw notFound(`job not found: ${jobId}`, { job_id: jobId });
+    }
+    const fm = {
+        status: terminalStatus,
+        written_at: new Date().toISOString(),
+    };
+    if (reason !== undefined && reason !== '') {
+        fm.reason = reason;
+    }
+    const content = `${renderFrontmatter(fm)}${body}`;
+    const tmp = join(dir, '.result.tmp');
+    writeFileSync(tmp, content, 'utf8');
+    renameSync(tmp, resultMdPath(jobId));
     const meta = readMeta(jobId);
     meta.status = terminalStatus;
     writeMeta(jobId, meta);
 }
 /**
- * Read result.json. If it doesn't exist and waitMs is given, block via fs.watch
- * until result.json appears or the timeout elapses.
- *
- * Race safety: registers the watcher THEN re-stats. If result.json appeared
- * between the first stat and the watch registration, the re-stat catches it
- * before the watcher has a chance to miss it.
+ * Render a small fixed-shape frontmatter block. We control writer and reader,
+ * so a 3-key hand-rolled emitter is plenty — no YAML dep, no escaping surprises.
+ * Values are plain strings; we double-quote `reason` to survive newlines/colons.
  */
+function renderFrontmatter(fm) {
+    const lines = ['---', `status: ${fm.status}`, `written_at: ${fm.written_at}`];
+    if (fm.reason !== undefined) {
+        const escaped = fm.reason.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
+        lines.push(`reason: "${escaped}"`);
+    }
+    lines.push('---', '');
+    return lines.join('\n');
+}
+/**
+ * Parse the small fixed-shape frontmatter we emit. Tolerant of trailing
+ * whitespace; returns `{ frontmatter, body }`. Throws if the document does not
+ * start with `---\n` or no closing `---` is found.
+ */
+function parseMarkdownResult(raw) {
+    if (!raw.startsWith('---\n') && !raw.startsWith('---\r\n')) {
+        throw new Error('result.md missing opening --- delimiter');
+    }
+    const afterOpen = raw.indexOf('\n') + 1;
+    const closeIdx = raw.indexOf('\n---', afterOpen);
+    if (closeIdx === -1) {
+        throw new Error('result.md missing closing --- delimiter');
+    }
+    const fmBlock = raw.slice(afterOpen, closeIdx);
+    // Body starts after the closing `---` line.
+    const afterCloseLine = raw.indexOf('\n', closeIdx + 1);
+    const body = afterCloseLine === -1 ? '' : raw.slice(afterCloseLine + 1);
+    const fm = {};
+    for (const line of fmBlock.split('\n')) {
+        const m = line.match(/^([a-z_]+):\s*(.*)$/);
+        if (m === null)
+            continue;
+        const key = m[1];
+        if (m[2] === undefined)
+            continue;
+        let val = m[2];
+        if (val.startsWith('"') && val.endsWith('"') && val.length >= 2) {
+            val = val.slice(1, -1).replace(/\\n/g, '\n').replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+        }
+        if (key === 'status') {
+            fm.status = val;
+        }
+        else if (key === 'written_at') {
+            fm.written_at = val;
+        }
+        else if (key === 'reason') {
+            fm.reason = val;
+        }
+    }
+    if (fm.status === undefined || fm.written_at === undefined) {
+        throw new Error('result.md frontmatter missing status or written_at');
+    }
+    return { frontmatter: fm, body };
+}
 export function readResult(jobId, opts = {}) {
     const dir = jobDir(jobId);
     if (!existsSync(dir)) {
         throw notFound(`job not found: ${jobId}`, { job_id: jobId });
     }
-    function parseResult() {
-        const raw = readFileSync(resultPath(jobId), 'utf8');
+    function parseAt(path) {
+        const raw = readFileSync(path, 'utf8');
+        if (path.endsWith('.md')) {
+            const { frontmatter, body } = parseMarkdownResult(raw);
+            const out = { status: frontmatter.status, result_md: body };
+            if (frontmatter.reason !== undefined) {
+                out.reason = frontmatter.reason;
+            }
+            return out;
+        }
         const parsed = JSON.parse(raw);
         return { status: parsed.status, result: parsed.result };
     }
-    // Fast path: result already present.
-    if (existsSync(resultPath(jobId))) {
-        const r = parseResult();
-        return Promise.resolve({ status: r.status, result: r.result });
+    const existing = existingResultPath(jobId);
+    if (existing !== null) {
+        return Promise.resolve(parseAt(existing));
     }
     if (opts.waitMs === undefined || opts.waitMs <= 0) {
         return Promise.resolve({ status: 'timeout' });
     }
     return new Promise((resolve) => {
         let settled = false;
-        const finish = (status, result) => {
+        const finish = (response) => {
             if (settled)
                 return;
             settled = true;
@@ -189,41 +284,47 @@ export function readResult(jobId, opts = {}) {
                 watcher.close();
             }
             catch { /* noop */ }
-            resolve({ status, result });
+            resolve(response);
         };
-        // Register watcher first, then re-stat (race safety).
         const watcher = watch(dir, (_event, name) => {
-            if (name === 'result.json' && existsSync(resultPath(jobId))) {
-                const r = parseResult();
-                finish(r.status, r.result);
+            if (name !== 'result.md' && name !== 'result.json')
+                return;
+            const path = existingResultPath(jobId);
+            if (path !== null) {
+                finish(parseAt(path));
             }
         });
-        // Re-stat after watcher is registered to close the race window.
-        if (existsSync(resultPath(jobId))) {
-            const r = parseResult();
-            finish(r.status, r.result);
+        const path = existingResultPath(jobId);
+        if (path !== null) {
+            finish(parseAt(path));
             return;
         }
         const timer = setTimeout(() => {
-            finish('timeout');
+            finish({ status: 'timeout' });
         }, opts.waitMs);
     });
 }
 /**
- * Derive job state from meta.json, result.json, and the tail of log.jsonl.
- * If a pid is recorded, is not alive, and no result.json exists → 'failed'.
+ * Derive job state from meta.json, the result file, and the tail of log.jsonl.
+ * If a pid is recorded, is not alive, and no result file exists → 'failed'.
  */
 export function jobStatus(jobId) {
     const meta = readMeta(jobId);
     const age_s = (Date.now() - new Date(meta.created_at).getTime()) / 1000;
-    // Derive effective state.
     let state = meta.status;
     if (state === 'live') {
-        if (existsSync(resultPath(jobId))) {
-            // result.json present but meta not yet updated (rare); trust the file.
+        const existing = existingResultPath(jobId);
+        if (existing !== null) {
+            // Result file present but meta not yet updated (rare); trust the file.
             try {
-                const r = JSON.parse(readFileSync(resultPath(jobId), 'utf8'));
-                state = r.status;
+                if (existing.endsWith('.md')) {
+                    const { frontmatter } = parseMarkdownResult(readFileSync(existing, 'utf8'));
+                    state = frontmatter.status;
+                }
+                else {
+                    const r = JSON.parse(readFileSync(existing, 'utf8'));
+                    state = r.status;
+                }
             }
             catch { /* leave as live */ }
         }
@@ -271,12 +372,20 @@ export function listJobs() {
             if (!existsSync(mp))
                 continue;
             const meta = JSON.parse(readFileSync(mp, 'utf8'));
-            // Derive effective state (result.json beats meta.status for live jobs).
+            // Derive effective state (result file beats meta.status for live jobs).
             let state = meta.status;
-            if (state === 'live' && existsSync(join(dir, 'result.json'))) {
+            if (state === 'live') {
+                const mdP = join(dir, 'result.md');
+                const jsP = join(dir, 'result.json');
                 try {
-                    const r = JSON.parse(readFileSync(join(dir, 'result.json'), 'utf8'));
-                    state = r.status;
+                    if (existsSync(mdP)) {
+                        const { frontmatter } = parseMarkdownResult(readFileSync(mdP, 'utf8'));
+                        state = frontmatter.status;
+                    }
+                    else if (existsSync(jsP)) {
+                        const r = JSON.parse(readFileSync(jsP, 'utf8'));
+                        state = r.status;
+                    }
                 }
                 catch { /* leave as live */ }
             }

package/dist/core/resolver.d.ts

@@ -22,8 +22,7 @@ export interface SkillResolutionOpts {
 export declare function resolveSkill(rawName: string, opts?: SkillResolutionOpts): Skill;
 export interface ParsedSkillQualifier {
     scope?: Scope;
-    plugin?: string;
-    name: string;
+    segments: string[];
 }
 export declare function parseSkillQualifier(raw: string): ParsedSkillQualifier;
 export declare function listInstalledMarketplaces(scope: Scope): InstalledMarketplace[];

package/dist/core/resolver.js

@@ -5,6 +5,7 @@ import { listDirs, pathExists, readText, walkFiles, } from './fs-utils.js';
 import { readMarketplaceManifest, readPluginManifest } from './manifest.js';
 import { parseFrontmatter } from './frontmatter.js';
 import { ambiguous, notFound, usage } from './errors.js';
+import { InputError } from './io.js';
 import { builtinSkillsRoot, marketplacesDir, pluginsDir, projectScopeRoot, scopeSkillsDir, userScopeRoot, } from './scope.js';
 function getBuiltinPlugin() {
     const root = builtinSkillsRoot();
@@ -202,30 +203,46 @@ export function resolveSkill(rawName, opts = {}) {
     if (parsed.scope && opts.scope && parsed.scope !== opts.scope) {
         throw usage(`scope conflict: identifier "${rawName}" uses scope "${parsed.scope}" but --scope is "${opts.scope}"`);
     }
-    if (parsed.plugin && opts.pluginFilter && parsed.plugin !== opts.pluginFilter) {
-        throw usage(`plugin conflict: identifier "${rawName}" uses plugin "${parsed.plugin}" but --plugin is "${opts.pluginFilter}"`);
-    }
     const effectiveScope = opts.scope ?? parsed.scope;
-    const effectivePluginFilter = opts.pluginFilter ?? parsed.plugin;
-    const direct = findSkillMatches(parsed.name, parsed.plugin, effectiveScope, effectivePluginFilter);
-    if (direct.length > 0)
-        return pickMatch(direct, parsed.name, parsed.plugin);
-    // Fallback: bare `plugin/name` (no colon) — try splitting on first `/`.
-    // Disambiguates "claude-authoring/rules" (which the search/list display also emits as
-    // "user:claude-authoring/rules") from a nested scope-root skill of the same shape.
-    if (!parsed.plugin && parsed.name.includes('/')) {
-        const slashIdx = parsed.name.indexOf('/');
-        const maybePlugin = parsed.name.slice(0, slashIdx);
-        const rest = parsed.name.slice(slashIdx + 1);
-        if (effectivePluginFilter === undefined || effectivePluginFilter === maybePlugin) {
-            const fallback = findSkillMatches(rest, maybePlugin, effectiveScope, maybePlugin);
-            if (fallback.length > 0)
-                return pickMatch(fallback, rest, maybePlugin);
+    // Lookup-based disambiguation: if segments[0] matches an installed plugin, treat it as plugin.
+    // Otherwise the entire segments array is the skill path under the scope-direct plugin.
+    let pluginQualifier;
+    let skillName;
+    if (parsed.segments.length === 0) {
+        throw usage(`skill name required`);
+    }
+    if (opts.pluginFilter !== undefined) {
+        // Explicit plugin filter overrides disambiguation.
+        pluginQualifier = opts.pluginFilter;
+        skillName = parsed.segments.join('/');
+    }
+    else if (parsed.segments.length > 1) {
+        const maybePlugin = parsed.segments[0];
+        const pluginMatch = findPluginByName(maybePlugin, effectiveScope) ??
+            (effectiveScope === undefined ? null : findPluginByName(maybePlugin));
+        if (pluginMatch !== null) {
+            pluginQualifier = maybePlugin;
+            skillName = parsed.segments.slice(1).join('/');
+        }
+        else {
+            pluginQualifier = undefined;
+            skillName = parsed.segments.join('/');
         }
     }
-    throw notFound(formatNotFoundMessage(rawName, parsed), {
-        skill: parsed.name,
-        plugin: parsed.plugin,
+    else {
+        pluginQualifier = undefined;
+        skillName = parsed.segments[0];
+    }
+    if (pluginQualifier && opts.pluginFilter && pluginQualifier !== opts.pluginFilter) {
+        throw usage(`plugin conflict: identifier "${rawName}" uses plugin "${pluginQualifier}" but --plugin is "${opts.pluginFilter}"`);
+    }
+    const effectivePluginFilter = opts.pluginFilter ?? pluginQualifier;
+    const direct = findSkillMatches(skillName, pluginQualifier, effectiveScope, effectivePluginFilter);
+    if (direct.length > 0)
+        return pickMatch(direct, skillName, pluginQualifier);
+    throw notFound(formatNotFoundMessage(rawName, skillName, pluginQualifier), {
+        skill: skillName,
+        plugin: pluginQualifier,
         scope: parsed.scope,
     });
 }
@@ -304,13 +321,13 @@ function pickMatch(matches, name, pluginQualifier) {
         })),
     });
 }
-function formatNotFoundMessage(rawName, parsed) {
-    const suggestions = suggestSkills(parsed.name, parsed.plugin);
+function formatNotFoundMessage(rawName, skillName, pluginQualifier) {
+    const suggestions = suggestSkills(skillName, pluginQualifier);
     const lines = [`skill not found: ${rawName}`];
-    lines.push('       expected forms: <name>, <plugin>:<name>, <scope>:<plugin>/<name>');
+    lines.push('       expected forms: <name>, <plugin>/<name>, <scope>/<name>, <scope>/<plugin>/<name>');
     if (suggestions.length > 0) {
         const formatted = suggestions
-            .map((s) => s.plugin === SCOPE_SKILL_PLUGIN ? s.name : `${s.plugin}:${s.name}`)
+            .map((s) => s.plugin === SCOPE_SKILL_PLUGIN ? s.name : `${s.plugin}/${s.name}`)
             .slice(0, 3);
         lines.push(`       did you mean: ${formatted.join(', ')}`);
     }
@@ -386,29 +403,26 @@ function editDistance(a, b) {
 const SCOPE_QUALIFIERS = new Set(['user', 'project']);
 // Accepted identifier forms:
 //   <name>                         — bare name; scope-root first, then plugins
-//   <plugin>:<name>                — explicit plugin
-//   <scope>:<name>                 — scope-root in a specific scope
-//   <scope>:<plugin>/<name>        — fully qualified (matches `skill list` / `skill search` display)
-// Bare `<plugin>/<name>` (no colon) is handled as a fallback inside resolveSkill.
+//   <plugin>/<name>                — explicit plugin (plugin may contain slashes)
+//   <scope>/<name>                 — scope-root in a specific scope
+//   <scope>/<plugin>/<name>        — fully qualified; plugin-vs-path disambiguation is lookup-based in resolveSkill
 export function parseSkillQualifier(raw) {
-    const colonIdx = raw.indexOf(':');
-    if (colonIdx === -1)
-        return { name: raw };
-    const before = raw.slice(0, colonIdx);
-    const after = raw.slice(colonIdx + 1);
-    if (SCOPE_QUALIFIERS.has(before)) {
-        const scope = before;
-        const slashIdx = after.indexOf('/');
-        if (slashIdx !== -1) {
-            return {
-                scope,
-                plugin: after.slice(0, slashIdx),
-                name: after.slice(slashIdx + 1),
-            };
-        }
-        return { scope, name: after };
+    if (raw.includes(':')) {
+        const suggested = raw.replace(/:/g, '/');
+        throw new InputError({
+            error: 'invalid_qualifier',
+            message: "mixed separators ':' and '/' no longer supported; use slashes throughout",
+            received: raw,
+            field: 'name',
+            next: `Use ${suggested}.`,
+        });
+    }
+    const segments = raw.split('/');
+    if (SCOPE_QUALIFIERS.has(segments[0])) {
+        const scope = segments[0];
+        return { scope, segments: segments.slice(1) };
     }
-    return { plugin: before, name: after };
+    return { segments };
 }
 function orderPluginsByResolution(plugins) {
     const score = (p) => {

package/dist/core/spawn.d.ts

@@ -10,6 +10,8 @@ export interface SpawnAgentOptions {
     };
     /** Max panes per tmux window before overflowing to a new window. */
     maxPanesPerWindow: number;
+    /** Display name passed to `claude -n`; surfaces in pane title and /resume picker. */
+    name?: string;
 }
 export interface SpawnAgentResult {
     status: 'spawned' | 'spawn-failed' | 'not-in-tmux';
@@ -40,6 +42,9 @@ export interface DetachOptions {
      *  uses the attached client's currently-focused pane — which drifts if the
      *  user switches windows between kickoff and spawn. */
     targetPane?: string;
+    /** Display name passed to `claude -n`; ignored when `command` is set
+     *  (caller controls the full argv in that mode). */
+    name?: string;
 }
 export interface DetachResult {
     status: 'spawned' | 'spawn-failed' | 'not-in-tmux';
@@ -49,6 +54,19 @@ export interface DetachResult {
 export declare function isInTmux(): boolean;
 export declare function shellQuote(s: string): string;
 export declare function countPanesInCurrentWindow(): number;
+/**
+ * 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 declare function findWindowWithSpace(maxPanesPerWindow: number): string | null;
 /**
  * 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
@@ -68,9 +86,14 @@ export declare function scheduleKillCurrentPane(delaySeconds: number): boolean;
  */
 export declare function spawnAndDetach(opts: DetachOptions): DetachResult;
 /**
- * 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`.
  */