@kynetic-ai/spec 0.9.1 → 0.11.0

package/dist/agent-runtime/prompts.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Agent Prompt Building
+ *
+ * Resolves skills from the skill registry and builds structured prompts
+ * for agent invocations. Extracted from ralph.ts to be reusable by both
+ * the dispatch engine and CLI one-shot mode.
+ *
+ * AC: @agent-invocation-lifecycle ac-7
+ */
+/**
+ * A resolved skill with its content loaded.
+ */
+export interface ResolvedSkill {
+    /** Skill ID */
+    id: string;
+    /** Full markdown content of the skill */
+    content: string;
+}
+/**
+ * Options for building an agent prompt.
+ */
+export interface BuildPromptOptions {
+    /** Base prompt text */
+    basePrompt: string;
+    /** Skill IDs to resolve and include */
+    skillIds: string[];
+    /** The .kspec directory for resolving skill content */
+    specDir: string;
+    /** Adapter identifier used to format cross-skill references */
+    adapterId?: string;
+}
+/**
+ * Resolve skill content from the skill registry.
+ *
+ * Skills are stored in .kspec/skills/<id>/SKILL.md.
+ * Missing skills are silently skipped.
+ *
+ * AC: @agent-invocation-lifecycle ac-7
+ */
+export declare function resolveSkills(skillIds: string[], specDir: string): Promise<ResolvedSkill[]>;
+/**
+ * Build a prompt with resolved skill content appended.
+ *
+ * When the agent definition specifies skills, their content is resolved
+ * from the skill registry and included in the prompt.
+ *
+ * AC: @agent-invocation-lifecycle ac-7
+ */
+export declare function buildPromptWithSkills(options: BuildPromptOptions): Promise<string>;
+//# sourceMappingURL=prompts.d.ts.map

package/dist/agent-runtime/prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/prompts.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,eAAe;IACf,EAAE,EAAE,MAAM,CAAC;IACX,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,uBAAuB;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA6DD;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAAE,EAClB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,aAAa,EAAE,CAAC,CAc1B;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BxF"}

package/dist/agent-runtime/prompts.js

@@ -0,0 +1,108 @@
+/**
+ * Agent Prompt Building
+ *
+ * Resolves skills from the skill registry and builds structured prompts
+ * for agent invocations. Extracted from ralph.ts to be reusable by both
+ * the dispatch engine and CLI one-shot mode.
+ *
+ * AC: @agent-invocation-lifecycle ac-7
+ */
+import * as path from "node:path";
+import * as fs from "node:fs/promises";
+import { resolveSkillReferenceTokensForPlatform } from "../parser/skill-render.js";
+function getSkillReferencePlatform(adapterId) {
+    switch (adapterId) {
+        case "claude-agent-acp":
+        case "claude-code-acp":
+            return "claude-code";
+        case "codex-acp":
+            return "codex";
+        default:
+            return null;
+    }
+}
+function getProjectRootFromSpecDir(specDir) {
+    return path.basename(specDir) === ".kspec" ? path.dirname(specDir) : specDir;
+}
+async function loadKspecSkillIds(specDir) {
+    const projectRoot = getProjectRootFromSpecDir(specDir);
+    const skillsDir = path.join(projectRoot, ".agents", "skills");
+    try {
+        const entries = await fs.readdir(skillsDir, { withFileTypes: true });
+        const ids = new Set();
+        for (const entry of entries) {
+            if (!entry.isDirectory()) {
+                continue;
+            }
+            if (!entry.name.startsWith("kspec-")) {
+                continue;
+            }
+            ids.add(entry.name.slice("kspec-".length));
+        }
+        return ids;
+    }
+    catch {
+        return new Set();
+    }
+}
+async function rewriteSkillReferences(text, specDir, adapterId) {
+    const platform = getSkillReferencePlatform(adapterId);
+    if (!platform) {
+        return text;
+    }
+    const kspecSkillIds = await loadKspecSkillIds(specDir);
+    const skillOrigins = new Map();
+    for (const skillId of kspecSkillIds) {
+        skillOrigins.set(skillId, "core");
+    }
+    return resolveSkillReferenceTokensForPlatform(text, platform, skillOrigins);
+}
+// ─── Skill Resolution ─────────────────────────────────────────────────────────
+/**
+ * Resolve skill content from the skill registry.
+ *
+ * Skills are stored in .kspec/skills/<id>/SKILL.md.
+ * Missing skills are silently skipped.
+ *
+ * AC: @agent-invocation-lifecycle ac-7
+ */
+export async function resolveSkills(skillIds, specDir) {
+    const resolved = [];
+    for (const skillId of skillIds) {
+        const contentPath = path.join(specDir, "skills", skillId, "SKILL.md");
+        try {
+            const content = await fs.readFile(contentPath, "utf-8");
+            resolved.push({ id: skillId, content });
+        }
+        catch {
+            // Skill not found — skip silently
+        }
+    }
+    return resolved;
+}
+/**
+ * Build a prompt with resolved skill content appended.
+ *
+ * When the agent definition specifies skills, their content is resolved
+ * from the skill registry and included in the prompt.
+ *
+ * AC: @agent-invocation-lifecycle ac-7
+ */
+export async function buildPromptWithSkills(options) {
+    const { basePrompt, skillIds, specDir, adapterId, } = options;
+    if (skillIds.length === 0) {
+        return basePrompt;
+    }
+    const resolvedSkills = await resolveSkills(skillIds, specDir);
+    if (resolvedSkills.length === 0) {
+        return basePrompt;
+    }
+    const skillSections = resolvedSkills
+        .map((skill) => `<!-- Skill: ${skill.id} -->\n${skill.content}`)
+        .join("\n\n");
+    const promptWithSkills = `${basePrompt}\n\n## Skills\n\n${skillSections}`;
+    // AC: @agent-invocation-lifecycle ac-10
+    // Rewrite portable {skill:<id>} references to adapter-specific invocation syntax.
+    return rewriteSkillReferences(promptWithSkills, specDir, adapterId);
+}
+//# sourceMappingURL=prompts.js.map

package/dist/agent-runtime/prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../../src/agent-runtime/prompts.ts"],"names":[],"mappings":"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"}

package/dist/agents/spawner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spawner.d.ts","sourceRoot":"","sources":["../../src/agents/spawner.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,YAAY,EAAS,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,sCAAsC;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,uCAAuC;IACvC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,yBAAyB;IACzB,aAAa,CAAC,EAAE,IAAI,CAAC,gBAAgB,EAAE,OAAO,GAAG,QAAQ,CAAC,CAAC;CAC5D;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,uCAAuC;IACvC,MAAM,EAAE,SAAS,CAAC;IAClB,+BAA+B;IAC/B,OAAO,EAAE,YAAY,CAAC;IACtB,6BAA6B;IAC7B,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,OAAO,KAAK,IAAI,CAAC;CACzC;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,iBAAiB,GACzB,YAAY,CAoDd;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,YAAY,CAAC,CAWvB"}
+{"version":3,"file":"spawner.d.ts","sourceRoot":"","sources":["../../src/agents/spawner.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,YAAY,EAAS,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,sCAAsC;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,uCAAuC;IACvC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,yBAAyB;IACzB,aAAa,CAAC,EAAE,IAAI,CAAC,gBAAgB,EAAE,OAAO,GAAG,QAAQ,CAAC,CAAC;CAC5D;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,uCAAuC;IACvC,MAAM,EAAE,SAAS,CAAC;IAClB,+BAA+B;IAC/B,OAAO,EAAE,YAAY,CAAC;IACtB,6BAA6B;IAC7B,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,OAAO,KAAK,IAAI,CAAC;CACzC;AAmDD;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,iBAAiB,GACzB,YAAY,CA+Dd;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,YAAY,CAAC,CAWvB"}

package/dist/agents/spawner.js

@@ -6,6 +6,50 @@
  */
 import { spawn } from "node:child_process";
 import { ACPClient } from "../acp/index.js";
+const UNEXPECTED_CASE_PREFIX = "Unexpected case:";
+const RATE_LIMIT_EVENT_TYPE = "rate_limit_event";
+function isNonActionableAdapterStderrLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith(UNEXPECTED_CASE_PREFIX))
+        return false;
+    const payload = trimmed.slice(UNEXPECTED_CASE_PREFIX.length).trim();
+    if (!payload)
+        return false;
+    try {
+        const parsed = JSON.parse(payload);
+        return parsed.type === RATE_LIMIT_EVENT_TYPE;
+    }
+    catch {
+        // Keep a narrow fallback pattern in case adapter logs malformed JSON.
+        return /"type"\s*:\s*"rate_limit_event"/.test(payload);
+    }
+}
+function forwardFilteredAdapterStderr(child) {
+    if (!child.stderr)
+        return;
+    child.stderr.setEncoding("utf-8");
+    let pending = "";
+    const forward = (line, withNewline) => {
+        if (isNonActionableAdapterStderrLine(line))
+            return;
+        process.stderr.write(withNewline ? `${line}\n` : line);
+    };
+    child.stderr.on("data", (chunk) => {
+        pending += chunk.toString();
+        let newlineIndex = pending.indexOf("\n");
+        while (newlineIndex !== -1) {
+            const line = pending.slice(0, newlineIndex);
+            pending = pending.slice(newlineIndex + 1);
+            forward(line, true);
+            newlineIndex = pending.indexOf("\n");
+        }
+    });
+    child.stderr.on("end", () => {
+        if (pending.length > 0) {
+            forward(pending, false);
+        }
+    });
+}
 /**
  * Spawn an ACP agent using the specified adapter.
  *
@@ -31,8 +75,10 @@ export function spawnAgent(adapter, options) {
         cwd,
         env: processEnv,
         shell: adapter.shell,
-        stdio: ["pipe", "pipe", "inherit"], // pipe stdin/stdout, inherit stderr
+        stdio: ["pipe", "pipe", "pipe"], // pipe all stdio so stderr can be filtered
     });
+    // Keep actionable adapter stderr visible while dropping known non-actionable noise.
+    forwardFilteredAdapterStderr(child);
     // Ensure stdin/stdout are available
     if (!child.stdin || !child.stdout) {
         child.kill();
@@ -47,10 +93,20 @@ export function spawnAgent(adapter, options) {
         stdin: child.stdout, // We read from child's stdout
         stdout: child.stdin, // We write to child's stdin
     });
-    // Forward process exit to client close
-    child.on("exit", () => {
+    // Forward process exit to client close, surfacing exit code/signal
+    child.on("exit", (code, signal) => {
         if (!client.isClosed()) {
-            client.close();
+            let reason;
+            if (signal !== null) {
+                reason = `Subagent process exited with signal ${signal}`;
+            }
+            else if (code !== null) {
+                reason = `Subagent process exited with code ${code}`;
+            }
+            else {
+                reason = "Subagent process exited unexpectedly";
+            }
+            client.close(reason);
         }
     });
     // Kill function with graceful shutdown

package/dist/agents/spawner.js.map

@@ -1 +1 @@
-{"version":3,"file":"spawner.js","sourceRoot":"","sources":["../../src/agents/spawner.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAqB,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,SAAS,EAAyB,MAAM,iBAAiB,CAAC;AA6BnE;;;;;;;;;GASG;AACH,MAAM,UAAU,UAAU,CACxB,OAAqB,EACrB,OAA0B;IAE1B,MAAM,EAAE,GAAG,EAAE,GAAG,GAAG,EAAE,EAAE,SAAS,EAAE,aAAa,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC;IAEjE,8BAA8B;IAC9B,MAAM,UAAU,GAAG;QACjB,GAAG,OAAO,CAAC,GAAG;QACd,GAAG,OAAO,CAAC,GAAG;QACd,GAAG,GAAG;KACP,CAAC;IAEF,2DAA2D;IAC3D,MAAM,IAAI,GAAG,CAAC,GAAG,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,CAAC;IAErD,0BAA0B;IAC1B,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,EAAE;QACzC,GAAG;QACH,GAAG,EAAE,UAAU;QACf,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,oCAAoC;KACzE,CAAC,CAAC;IAEH,oCAAoC;IACpC,IAAI,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;QAClC,KAAK,CAAC,IAAI,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAC9D,CAAC;IAED,+CAA+C;IAC/C,uCAAuC;IACvC,iDAAiD;IACjD,gDAAgD;IAChD,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,GAAG,aAAa;QAChB,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,8BAA8B;QACnD,MAAM,EAAE,KAAK,CAAC,KAA8B,EAAE,4BAA4B;KAC3E,CAAC,CAAC;IAEH,uCAAuC;IACvC,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE;QACpB,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC;YACvB,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,uCAAuC;IACvC,MAAM,IAAI,GAAG,CAAC,SAAyB,SAAS,EAAQ,EAAE;QACxD,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;YAClB,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACrB,CAAC;IACH,CAAC,CAAC;IAEF,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AAC1C,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,OAAqB,EACrB,OAA0B;IAE1B,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAE3C,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;QAChC,OAAO,KAAK,CAAC;IACf,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,qCAAqC;QACrC,KAAK,CAAC,IAAI,EAAE,CAAC;QACb,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}
+{"version":3,"file":"spawner.js","sourceRoot":"","sources":["../../src/agents/spawner.ts"],"names":[],"mappings":"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"}

package/dist/cli/batch-exec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"batch-exec.d.ts","sourceRoot":"","sources":["../../src/cli/batch-exec.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAkB,MAAM,WAAW,CAAC;AAEzD,OAAO,EAEL,KAAK,YAAY,EAGjB,KAAK,eAAe,EACpB,KAAK,UAAU,EAChB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAgBtD,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAIrC,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,MAAM,wBAAwB,GAChC,iBAAiB,GACjB,kBAAkB,GAClB,aAAa,GACb,kBAAkB,CAAC;AAEvB,MAAM,WAAW,oBAAoB;IACnC,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,2BAA2B;IAC3B,IAAI,EAAE,wBAAwB,CAAC;IAC/B,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,qBAAqB;IACpC,6CAA6C;IAC7C,KAAK,EAAE,OAAO,CAAC;IACf,mDAAmD;IACnD,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,wBAAwB;IACxB,MAAM,EAAE,oBAAoB,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC;CAC/C;AAmCD;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAAC,UAAU,CAAC,CA4BrB;AA0FD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,YAAY,EAAE,EACxB,OAAO,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE,oBAAoB,GAC7B,qBAAqB,CAkHvB;AAID;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,qBAAqB,EAC7B,IAAI,GAAE,OAAe,GACpB,MAAM,CA6BR;AAID,MAAM,WAAW,mBAAmB;IAClC,qCAAqC;IACrC,MAAM,EAAE,OAAO,CAAC;IAChB,iDAAiD;IACjD,eAAe,EAAE,OAAO,CAAC;IACzB,yBAAyB;IACzB,MAAM,EAAE,OAAO,CAAC;IAChB,kBAAkB;IAClB,IAAI,EAAE,OAAO,CAAC;CACf;AAsBD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,YAAY,EAAE,OAAO,EAAE,WAAW,GAAG,MAAM,EAAE,CAuElF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAOnD;AAYD;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,YAAY,EAAE,EACxB,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,eAAe,CAAC,CAqD1B"}
+{"version":3,"file":"batch-exec.d.ts","sourceRoot":"","sources":["../../src/cli/batch-exec.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,OAAO,EAAkB,MAAM,WAAW,CAAC;AAEzD,OAAO,EAEL,KAAK,YAAY,EAGjB,KAAK,eAAe,EACpB,KAAK,UAAU,EAChB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAoBtD,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAMrC,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,MAAM,wBAAwB,GAChC,iBAAiB,GACjB,kBAAkB,GAClB,aAAa,GACb,kBAAkB,CAAC;AAEvB,MAAM,WAAW,oBAAoB;IACnC,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,2BAA2B;IAC3B,IAAI,EAAE,wBAAwB,CAAC;IAC/B,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,qBAAqB;IACpC,6CAA6C;IAC7C,KAAK,EAAE,OAAO,CAAC;IACf,mDAAmD;IACnD,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,wBAAwB;IACxB,MAAM,EAAE,oBAAoB,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC;CAC/C;AA+FD;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAAC,UAAU,CAAC,CA4BrB;AAuGD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,YAAY,EAAE,EACxB,OAAO,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE,oBAAoB,GAC7B,qBAAqB,CAkHvB;AAID;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,qBAAqB,EAC7B,IAAI,GAAE,OAAe,GACpB,MAAM,CA6BR;AAID,MAAM,WAAW,mBAAmB;IAClC,qCAAqC;IACrC,MAAM,EAAE,OAAO,CAAC;IAChB,iDAAiD;IACjD,eAAe,EAAE,OAAO,CAAC;IACzB,yBAAyB;IACzB,MAAM,EAAE,OAAO,CAAC;IAChB,kBAAkB;IAClB,IAAI,EAAE,OAAO,CAAC;CACf;AAmDD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,YAAY,EAAE,OAAO,EAAE,WAAW,GAAG,MAAM,EAAE,CAoFlF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAOnD;AAYD;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,YAAY,EAAE,EACxB,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,eAAe,CAAC,CAqD1B"}

package/dist/cli/batch-exec.js

@@ -6,8 +6,6 @@
  * mode, and produces helpful error messages.
  */
 import * as fs from "node:fs/promises";
-import * as path from "node:path";
-import * as os from "node:os";
 import chalk from "chalk";
 import { ZodError } from "zod";
 import { BatchInputSchema, } from "../schema/batch.js";
@@ -18,6 +16,8 @@ import { findClosestCommand } from "./suggest.js";
 import { createBatchCommandFilter } from "./command-annotations.js";
 import { setJsonMode, setVerboseMode } from "./output.js";
 import { BatchExitError, OutputCapture, installExitInterceptor, uninstallExitInterceptor, setBatchMode, } from "./batch-context.js";
+import { activateBatchBuffer, deactivateBatchBuffer, } from "./batch-write-buffer.js";
+const BATCH_STDIN_IDLE_TIMEOUT_MS = 1000;
 // ── Error Types ─────────────────────────────────────────────────────
 export class BatchParseError extends Error {
     constructor(message) {
@@ -26,6 +26,52 @@ export class BatchParseError extends Error {
     }
 }
 // ── Parsing ─────────────────────────────────────────────────────────
+/**
+ * Read stdin with an idle timeout so non-interactive callers that keep
+ * stdin open without writing do not block forever.
+ */
+async function readStdinWithIdleTimeout(timeoutMs) {
+    return new Promise((resolve) => {
+        let data = "";
+        let timeout;
+        const cleanup = () => {
+            if (timeout) {
+                clearTimeout(timeout);
+            }
+            process.stdin.removeListener("data", onData);
+            process.stdin.removeListener("end", onEnd);
+            process.stdin.removeListener("error", onError);
+        };
+        const armTimeout = () => {
+            if (timeout) {
+                clearTimeout(timeout);
+            }
+            timeout = setTimeout(() => {
+                cleanup();
+                resolve(data);
+            }, timeoutMs);
+            timeout.unref?.();
+        };
+        const onData = (chunk) => {
+            data += chunk;
+            armTimeout();
+        };
+        const onEnd = () => {
+            cleanup();
+            resolve(data);
+        };
+        const onError = () => {
+            cleanup();
+            resolve(data);
+        };
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", onData);
+        process.stdin.on("end", onEnd);
+        process.stdin.on("error", onError);
+        process.stdin.resume();
+        armTimeout();
+    });
+}
 /**
  * Read raw text from a batch input source.
  */
@@ -41,13 +87,17 @@ async function readSource(source) {
                 throw new BatchParseError(`Failed to read batch file: ${err.message}`);
             }
         case "stdin": {
-            const chunks = [];
-            for await (const chunk of process.stdin) {
-                chunks.push(chunk);
-            }
-            const text = Buffer.concat(chunks).toString("utf-8");
+            const text = process.stdin.isTTY
+                ? await (async () => {
+                    const chunks = [];
+                    for await (const chunk of process.stdin) {
+                        chunks.push(chunk);
+                    }
+                    return Buffer.concat(chunks).toString("utf-8");
+                })()
+                : await readStdinWithIdleTimeout(BATCH_STDIN_IDLE_TIMEOUT_MS);
             if (!text.trim()) {
-                throw new BatchParseError("No input received on stdin");
+                throw new BatchParseError(`No input received on stdin. Provide --commands <json>, --file <path>, or pipe JSON via stdin.`);
             }
             return text;
         }
@@ -116,6 +166,17 @@ function normalizeArgKey(key) {
         .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
         .toLowerCase();
 }
+/**
+ * Batch-only argument aliases for common plural forms.
+ * Keys and values are canonical kebab-case.
+ */
+const BATCH_ARG_ALIASES = {
+    tags: "tag",
+};
+function resolveBatchArgAlias(key) {
+    const canonical = normalizeArgKey(key);
+    return BATCH_ARG_ALIASES[canonical] ?? canonical;
+}
 /**
  * Get all known argument and option names for a command, returning both
  * kebab-case, camelCase, and underscore variants.
@@ -231,7 +292,7 @@ export function validateBatchCommands(commands, program, options) {
         // Collect all known names as flat array for suggestion matching
         const knownNamesArray = Array.from(knownNames);
         for (const argKey of Object.keys(cmd.args)) {
-            if (!knownCanonicalNames.has(normalizeArgKey(argKey))) {
+            if (!knownCanonicalNames.has(resolveBatchArgAlias(argKey))) {
                 const suggestion = findClosestCommand(argKey, knownNamesArray);
                 errors.push({
                     index: i,
@@ -246,7 +307,7 @@ export function validateBatchCommands(commands, program, options) {
         // 5. Check for missing required args
         for (const reqName of requiredNames) {
             const normalizedReqName = normalizeArgKey(reqName);
-            if (!Object.keys(cmd.args).some((k) => normalizeArgKey(k) === normalizedReqName)) {
+            if (!Object.keys(cmd.args).some((k) => resolveBatchArgAlias(k) === normalizedReqName)) {
                 errors.push({
                     index: i,
                     id: cmd.id,
@@ -314,6 +375,30 @@ function toArgString(value) {
     }
     return String(value);
 }
+function normalizePriorityAlias(value) {
+    if (Array.isArray(value)) {
+        return value.map((v) => normalizePriorityAlias(v));
+    }
+    if (typeof value !== "string") {
+        return value;
+    }
+    const match = value.match(/^[Pp]([1-5])$/);
+    return match ? match[1] : value;
+}
+function isNumericPriorityOption(option) {
+    if (!option || normalizeArgKey(option.name) !== "priority") {
+        return false;
+    }
+    const hasNumericPlaceholder = /<n(?:umber)?>/.test(option.flags);
+    const hasNumericRangeHint = /\b1-5\b/.test(option.description ?? "");
+    return hasNumericPlaceholder || hasNumericRangeHint;
+}
+function isNumericPriorityArgument(arg) {
+    if (normalizeArgKey(arg.name) !== "priority") {
+        return false;
+    }
+    return /\b1-5\b/.test(arg.description ?? "");
+}
 export function buildCommandArgv(cmd, cmdMeta) {
     const argv = [...cmd.command.trim().split(/\s+/)];
     const consumedKeys = new Set();
@@ -331,23 +416,27 @@ export function buildCommandArgv(cmd, cmdMeta) {
                 flags: opt.flags,
                 variadic: opt.variadic,
                 name,
+                description: opt.description,
             });
         }
     }
     // Phase 1: Emit positional args in Commander definition order
     for (const argDef of positionalDefs) {
         const canonicalName = normalizeArgKey(argDef.name);
-        const matchedKey = Object.keys(cmd.args).find((k) => normalizeArgKey(k) === canonicalName);
+        const matchedKey = Object.keys(cmd.args).find((k) => resolveBatchArgAlias(k) === canonicalName);
         const value = matchedKey ? cmd.args[matchedKey] : undefined;
         if (value === undefined)
             continue;
         consumedKeys.add(matchedKey);
-        if (Array.isArray(value)) {
-            for (const v of value)
+        const normalizedValue = isNumericPriorityArgument(argDef)
+            ? normalizePriorityAlias(value)
+            : value;
+        if (Array.isArray(normalizedValue)) {
+            for (const v of normalizedValue)
                 argv.push(toArgString(v));
         }
         else {
-            argv.push(toArgString(value));
+            argv.push(toArgString(normalizedValue));
         }
     }
     // Phase 2: Emit options from remaining keys
@@ -355,27 +444,30 @@ export function buildCommandArgv(cmd, cmdMeta) {
         if (consumedKeys.has(key)) {
             continue;
         }
-        const canonicalKey = normalizeArgKey(key);
+        const canonicalKey = resolveBatchArgAlias(key);
         // Skip positional args (already emitted)
         if (positionalCanonicalNameSet.has(canonicalKey)) {
             continue;
         }
         const knownOption = optionMap.get(canonicalKey);
         const flagName = `--${knownOption?.name ?? canonicalKey}`;
-        if (typeof value === "boolean") {
-            if (value) {
+        const normalizedValue = isNumericPriorityOption(knownOption)
+            ? normalizePriorityAlias(value)
+            : value;
+        if (typeof normalizedValue === "boolean") {
+            if (normalizedValue) {
                 argv.push(flagName);
             }
             // false booleans: omit (Commander treats absence as false)
         }
-        else if (Array.isArray(value)) {
+        else if (Array.isArray(normalizedValue)) {
             // Variadic or repeated options
-            for (const v of value) {
+            for (const v of normalizedValue) {
                 argv.push(flagName, toArgString(v));
             }
         }
-        else if (value !== null && value !== undefined) {
-            argv.push(flagName, toArgString(value));
+        else if (normalizedValue !== null && normalizedValue !== undefined) {
+            argv.push(flagName, toArgString(normalizedValue));
         }
     }
     return argv;
@@ -464,34 +556,37 @@ export async function executeBatch(commands, program, options) {
     }
 }
 /**
- * Atomic execution: copy specDir to temp, run all, copy back on success.
+ * Atomic execution: buffer all writes in memory, flush to disk on success.
+ *
+ * Replaces the old fs.cp(realSpecDir, tempDir) approach with an in-memory
+ * write buffer. Writes during batch execution are intercepted by yaml.ts and
+ * stored in the buffer. On success, the buffer is flushed to the real specDir.
+ * On failure, the buffer is discarded — the real .kspec/ is never touched.
  *
  * AC: @batch-exec ac-default-atomic
  * AC: @batch-exec ac-atomic-rollback
  * AC: @batch-exec ac-atomic-isolation
  * AC: @batch-exec ac-single-commit
+ * AC: @batch-write-buffer ac-1 — writes buffered in memory, not on disk
+ * AC: @batch-write-buffer ac-4 — rollback discards buffer
+ * AC: @batch-write-buffer ac-5 — sessions/ never copied (buffer is per-file)
+ * AC: @batch-write-buffer ac-6 — real .kspec/ unchanged until flush
  */
 async function executeAtomic(commands, program, tree, options) {
-    // Get the real context for copy-back
     const ctx = await initContext();
     const realSpecDir = ctx.specDir;
-    // Create temp copy using mkdtemp for safe, collision-free naming
-    const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "kspec-batch-"));
-    await fs.cp(realSpecDir, tempDir, { recursive: true });
-    // Remove .git from temp copy to prevent worktree pointer leaks
-    await fs.rm(path.join(tempDir, ".git"), { force: true, recursive: true });
+    // Activate in-memory write buffer — writes to specDir go to buffer
+    const buffer = activateBatchBuffer(realSpecDir);
     // Set up atomic context
     const savedChalkLevel = chalk.level;
-    const savedSpecDir = process.env.KSPEC_SPEC_DIR;
     const savedBatchProjectRoot = process.env.KSPEC_BATCH_PROJECT_ROOT;
-    // AC: @project-config ac-7 — set real project root before redirecting spec dir
+    // AC: @project-config ac-7 — set real project root for config resolution
     process.env.KSPEC_BATCH_PROJECT_ROOT = ctx.rootDir;
-    process.env.KSPEC_SPEC_DIR = tempDir;
     setBatchMode(true);
     chalk.level = 0;
     const results = [];
     let allSucceeded = true;
-    let copyBackFailed = false;
+    let flushFailed = false;
     try {
         for (let i = 0; i < commands.length; i++) {
             const cmd = commands[i];
@@ -499,7 +594,7 @@ async function executeAtomic(commands, program, tree, options) {
             results.push(result);
             if (!result.success) {
                 allSucceeded = false;
-                // Atomic mode: stop on first failure, discard everything
+                // Atomic mode: stop on first failure, discard buffer
                 // Fill remaining as not-executed
                 for (let j = i + 1; j < commands.length; j++) {
                     results.push({
@@ -513,21 +608,12 @@ async function executeAtomic(commands, program, tree, options) {
                 break;
             }
         }
-        // Copy back on success
+        // Flush buffer to disk on success
+        // AC: @batch-write-buffer ac-3 — only written files flushed
+        // AC: @batch-write-buffer ac-7 — flush failure reported, pre-batch state preserved
         if (allSucceeded) {
             try {
-                // Clear real specDir contents (except .git and .gitattributes) before copy-back
-                const entries = await fs.readdir(realSpecDir);
-                for (const entry of entries) {
-                    if (entry === ".git" || entry === ".gitattributes")
-                        continue;
-                    await fs.rm(path.join(realSpecDir, entry), { recursive: true, force: true });
-                }
-                // Copy temp contents back
-                const tempEntries = await fs.readdir(tempDir);
-                for (const entry of tempEntries) {
-                    await fs.cp(path.join(tempDir, entry), path.join(realSpecDir, entry), { recursive: true });
-                }
+                await buffer.flush();
                 // Single shadow commit for all changes
                 if (ctx.shadow?.enabled) {
                     const successCount = results.filter((r) => r.success).length;
@@ -535,25 +621,21 @@ async function executeAtomic(commands, program, tree, options) {
                     shadowPushAsync(ctx.shadow.worktreeDir);
                 }
             }
-            catch (copyErr) {
-                // Copy-back failed — preserve tempDir for manual recovery
-                copyBackFailed = true;
+            catch (flushErr) {
+                flushFailed = true;
                 allSucceeded = false;
-                console.error(`Batch copy-back failed: ${copyErr instanceof Error ? copyErr.message : copyErr}`);
-                console.error(`Temp dir preserved for recovery: ${tempDir}`);
+                console.error(`Batch flush failed: ${flushErr instanceof Error ? flushErr.message : flushErr}`);
             }
         }
     }
     finally {
-        // Clean up
+        // Always deactivate buffer (discard if not flushed)
+        if (!allSucceeded || flushFailed) {
+            buffer.discard();
+        }
+        deactivateBatchBuffer();
         setBatchMode(false);
         chalk.level = savedChalkLevel;
-        if (savedSpecDir !== undefined) {
-            process.env.KSPEC_SPEC_DIR = savedSpecDir;
-        }
-        else {
-            delete process.env.KSPEC_SPEC_DIR;
-        }
         // AC: @project-config ac-7 — restore batch project root env var
         if (savedBatchProjectRoot !== undefined) {
             process.env.KSPEC_BATCH_PROJECT_ROOT = savedBatchProjectRoot;
@@ -561,10 +643,6 @@ async function executeAtomic(commands, program, tree, options) {
         else {
             delete process.env.KSPEC_BATCH_PROJECT_ROOT;
         }
-        // Only remove temp dir if copy-back succeeded (or commands failed)
-        if (!copyBackFailed) {
-            await fs.rm(tempDir, { recursive: true, force: true }).catch(() => { });
-        }
     }
     const succeeded = results.filter((r) => r.success).length;
     const failed = results.filter((r) => !r.success).length;