@astrosheep/keiyaku 4.0.2 → 4.0.3

package/build/integrations/marketplace/plugins/keiyaku/skills/keiyaku-bind/SKILL.md

@@ -31,14 +31,6 @@ Bind is the last step of an investigation, never the first step of an idea.
   now. Cannot draft means unresolved design — "the worker will sort out the
   docs" is a design gap in disguise.
 
-Split complex work wherever independently acceptable delivery boundaries
-exist. When a complex Keiyaku cannot be split without breaking one acceptance
-boundary, bind one Contract and plan its fulfillment as explicit arcs. Treat
-each arc as a chapter as in a work of literature, not as a task sequence.
-Commission one current chapter at a time; never hand the whole undifferentiated
-Contract to one Deliverer and trust it to finish everything in one pass.
-Continue with `keiyaku-workflow` for the arc document and command.
-
 Two tests close the gate:
 
 - **Substitution.** Two workers who never met each deliver test-green from
@@ -67,8 +59,7 @@ Design read the same without a sentence here, delete it.>
 
 ## Objective
 <One observable end-state, judged done/not-done without reading Design.
-If "and" joins independently acceptable outcomes, bind two Contracts. A
-single outcome may still require several arcs during fulfillment.>
+If you need "and", bind two Contracts.>
 
 ## Design
 <The closed decisions. A statement belongs here exactly when a test-green

package/build/integrations/marketplace/plugins/keiyaku/skills/keiyaku-workflow/SKILL.md

@@ -121,17 +121,11 @@ the test. Give each resulting Contract coherent terms. Connect them with
 `--after` only when one must proceed from another's settled result or their
 intended work is unsafe to run concurrently.
 
-When a complex Keiyaku cannot be split without breaking one acceptance
-boundary, organize its fulfillment into arcs. Do not hand the whole
-undifferentiated Contract to one Deliverer and trust one pass to finish it.
-Record and work one current chapter at a time.
-
-An arc is a chapter as in a work of literature: one named part of the
-delivery's story, not a task list, progress slice, or claim that the work is
-mechanically sequential. Its title names the chapter, Objective states that
-chapter's aim, and Brief commissions work for that chapter. When an Arc is
-active, stay within that current chapter. `.keiyaku/KEIYAKU.md` renders the
-current Arc.
+When one acceptance boundary still spans several coherent chapters,
+organize them as arcs. An arc is a chapter of the delivery's
+story, not a task list: its title names the chapter, Objective is the
+chapter's aim, Brief opens the next chapter. When an Arc is active, stay
+within that current chapter. `.keiyaku/KEIYAKU.md` renders the current Arc.
 Record the next chapter before entering it:
 
 ```bash

package/build/src/akuma/body.js

@@ -580,8 +580,16 @@ export async function driveAkumaBody(launch, adapter, runtime = defaultRuntime()
         }
     }
     catch (error) {
-        if (await heartExists(launch.paths))
-            throw error;
+        if (!await heartExists(launch.paths))
+            return;
+        try {
+            await leash.sealIfUnborn(launch.paths, {
+                evidence: error instanceof Error ? error.message : String(error),
+                at: runtime.now(),
+            });
+        }
+        catch { /* the original Body failure remains authoritative */ }
+        throw error;
     }
     finally {
         leash.release();

package/build/src/akuma/heart/storage.d.ts

@@ -21,6 +21,7 @@ export declare class HeldAkumaLeash {
         evidence: string;
         at: string;
     }>): Promise<"born" | "sealed">;
+    readSeal(): ReturnType<typeof sealFact>;
     clearPause(paths: AkumaPaths): Promise<void>;
     clearStop(paths: AkumaPaths): Promise<void>;
     recordBody(paths: AkumaPaths, input: Readonly<{

package/build/src/akuma/heart/storage.js

@@ -136,6 +136,8 @@ export class HeldAkumaLeash {
         }));
     }
     async sealIfUnborn(paths, input) {
+        if (sealExists(this.database))
+            return "sealed";
         if (await withHeart(paths, (heart) => soulFact(heart)) !== null)
             return "born";
         insertSealFact(this.database, input);
@@ -144,6 +146,9 @@ export class HeldAkumaLeash {
         this.database.close();
         return "sealed";
     }
+    readSeal() {
+        return sealFact(this.database);
+    }
     async clearPause(paths) { await withHeart(paths, deletePauseControl); }
     async clearStop(paths) { await withHeart(paths, deleteStopControl); }
     async recordBody(paths, input) {

package/build/src/akuma/publication.js

@@ -1,4 +1,4 @@
-import { HeldAkumaLeash, initializeHeart, readHeart, readSoul, } from "./heart/index.js";
+import { HeldAkumaLeash, initializeHeart, readHeart, readSeal, readSoul, } from "./heart/index.js";
 import { allocateAkumaDirectory, } from "./identity.js";
 import { abortableDelay } from "./abort.js";
 const POLL_MS = 25;
@@ -10,15 +10,38 @@ async function settleTimedOutBirth(paths) {
     const leash = await HeldAkumaLeash.try(paths);
     if (leash === null)
         return null;
-    const result = await leash.sealIfUnborn(paths, { evidence: "call-timeout", at: new Date().toISOString() });
-    if (result === "sealed")
-        throw new Error("Akuma body failed before birth");
-    leash.release();
+    let result;
+    try {
+        result = await leash.sealIfUnborn(paths, {
+            evidence: "call-timeout",
+            at: new Date().toISOString(),
+        });
+    }
+    finally {
+        leash.release();
+    }
+    if (result === "sealed") {
+        const seal = await readSeal(paths);
+        throw new Error(seal?.evidence === "call-timeout" || seal === null
+            ? "Akuma body failed before birth"
+            : seal.evidence);
+    }
     const soul = await readSoul(paths);
     if (soul === null)
         throw new Error("Akuma birth settled without a soul");
     return soul;
 }
+async function observedBirthFailure(paths) {
+    const leash = await HeldAkumaLeash.try(paths);
+    if (leash === null)
+        return null;
+    try {
+        return leash.readSeal()?.evidence ?? null;
+    }
+    finally {
+        leash.release();
+    }
+}
 async function awaitBirth(paths, signal) {
     const deadline = performance.now() + BIRTH_TIMEOUT_MS;
     for (;;) {
@@ -26,6 +49,9 @@ async function awaitBirth(paths, signal) {
         const soul = await readSoul(paths);
         if (soul !== null)
             return soul;
+        const failure = await observedBirthFailure(paths);
+        if (failure !== null)
+            throw new Error(failure);
         if (performance.now() >= deadline) {
             const settled = await settleTimedOutBirth(paths);
             if (settled !== null)
@@ -63,7 +89,10 @@ async function sealLocalFailure(allocated, error) {
         if (leash === null)
             return;
         try {
-            await leash.sealIfUnborn(allocated.paths, { evidence: diagnostic(error), at: new Date().toISOString() });
+            await leash.sealIfUnborn(allocated.paths, {
+                evidence: diagnostic(error),
+                at: new Date().toISOString(),
+            });
         }
         finally {
             leash.release();

package/build/src/cli/commands/akuma.js

@@ -1,4 +1,4 @@
-import { CliUsageError, isBlankInput, usageLine } from "../usage.js";
+import { CliUsageError, isBlankInput, usageLine, withJsonAutomationHelp } from "../usage.js";
 import { archetypeName, parseAkuId } from "../../akuma/identity.js";
 import { parseDuration as decodeDuration } from "../../duration.js";
 import { parseAkumaAlias, parseAkumaGlob } from "../../identity/selector.js";
@@ -74,7 +74,7 @@ export function renderAkumaRootRows() {
 }
 export function renderAkumaHelp(action) {
     const spec = AKUMA_COMMAND_SPECS[action];
-    return `${spec.purpose}\n\n${usageLine(spec.usage)}${spec.details === undefined ? "" : `\n\n${spec.details}`}`;
+    return withJsonAutomationHelp(`${spec.purpose}\n\n${usageLine(spec.usage)}${spec.details === undefined ? "" : `\n\n${spec.details}`}`);
 }
 export function renderAkumaUsage(action) {
     return usageLine(AKUMA_COMMAND_SPECS[action].usage);

package/build/src/cli/commands/install.js

@@ -1,7 +1,7 @@
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { runProcess } from "../../runtime/proc/run.js";
-import { CliUsageError, usageLine } from "../usage.js";
+import { CliUsageError, usageLine, withJsonAutomationHelp } from "../usage.js";
 export const HARNESS_NAMES = ["codex", "claude", "opencode", "pi"];
 export const INSTALL_USAGE = "install <codex|claude|opencode|pi> [--json]\n       install --all [--json]";
 function isHarness(value) {
@@ -43,7 +43,7 @@ export function parseInstallCommand(argv) {
     };
 }
 export function renderInstallHelp() {
-    return `Install the Keiyaku skills into one or more agent harnesses.\n\n${usageLine(INSTALL_USAGE)}`;
+    return withJsonAutomationHelp(`Install the Keiyaku skills into one or more agent harnesses.\n\n${usageLine(INSTALL_USAGE)}`);
 }
 const INSTALL_TIMEOUT_MS = 5 * 60 * 1000;
 const ASSET_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../../../integrations/marketplace");

package/build/src/cli/commands/task.js

@@ -1,4 +1,4 @@
-import { CliUsageError, isBlankInput, usageLine } from "../usage.js";
+import { CliUsageError, isBlankInput, usageLine, withJsonAutomationHelp } from "../usage.js";
 import { parseTaskQueryExpression, validateTaskLimit, validateTaskParent, } from "./task-query.js";
 const COMMON = { json: "boolean" };
 const TASK_COMMAND_SPECS = {
@@ -46,14 +46,14 @@ export function isTaskAction(value) {
 export function renderTaskHelp(action) {
     if (action !== undefined) {
         const spec = TASK_COMMAND_SPECS[action];
-        return `${spec.purpose}\n\n${usageLine(spec.usage)}`;
+        return withJsonAutomationHelp(`${spec.purpose}\n\n${usageLine(spec.usage)}`);
     }
-    return [
+    return withJsonAutomationHelp([
         "usage: keiyaku task <command> ...",
         "",
         "commands:",
         ...Object.values(TASK_COMMAND_SPECS).flatMap((spec) => spec.usage.split("\n").map((line) => `  ${line}`).concat(`    ${spec.purpose}`)),
-    ].join("\n");
+    ].join("\n"));
 }
 export function renderTaskUsage(action) {
     return usageLine(TASK_COMMAND_SPECS[action].usage);

package/build/src/cli/parse.js

@@ -2,11 +2,11 @@ import { isTaskAction, parseTaskCommand, renderTaskUsage, } from "./commands/tas
 import { isAkumaAction, parseAkumaCatalogPath, parseAkumaCommand, renderAkumaRootRows, renderAkumaUsage, } from "./commands/akuma.js";
 import { INSTALL_USAGE, parseInstallCommand, renderInstallHelp } from "./commands/install.js";
 import { AMEND_MINIMAL_STDIN_HELP, CONTRACT_COMMAND_SPECS } from "./commands/contract.js";
-import { CliUsageError, isBlankInput, usageLine } from "./usage.js";
+import { CliUsageError, isBlankInput, usageLine, withJsonAutomationHelp } from "./usage.js";
 export { CliUsageError } from "./usage.js";
 const ROOT_USAGE = "usage: keiyaku [-C <path>] [--repo <path>] <command> [<contract>|@<contract>] [--flag ...] [-]";
 export function renderRootHelp() {
-    return [
+    return withJsonAutomationHelp([
         ROOT_USAGE,
         "",
         "global options:",
@@ -20,12 +20,12 @@ export function renderRootHelp() {
         "  task ...",
         "    Task coordination; see `keiyaku task --help`.",
         ...renderAkumaRootRows(),
-    ].join("\n");
+    ].join("\n"));
 }
 export function renderContractHelp(command) {
     const spec = CONTRACT_COMMAND_SPECS[command];
     const help = `${spec.purpose}\n\n${usageLine(spec.usage)}`;
-    return command === "amend" ? `${help}\n\n${AMEND_MINIMAL_STDIN_HELP}` : help;
+    return withJsonAutomationHelp(command === "amend" ? `${help}\n\n${AMEND_MINIMAL_STDIN_HELP}` : help);
 }
 function contractUsage(command) {
     return usageLine(CONTRACT_COMMAND_SPECS[command].usage);

package/build/src/cli/usage.d.ts

@@ -3,5 +3,7 @@ export declare class CliUsageError extends Error {
     readonly projection?: string | undefined;
     constructor(diagnostic: string, projection?: string | undefined);
 }
+export declare const JSON_AUTOMATION_HELP = "--json is only for automation script input/output and should not be used for daily interactive use.";
+export declare function withJsonAutomationHelp(help: string): string;
 export declare function isBlankInput(value: string): boolean;
 export declare function usageLine(usage: string): string;

package/build/src/cli/usage.js

@@ -8,6 +8,10 @@ export class CliUsageError extends Error {
         this.name = "CliUsageError";
     }
 }
+export const JSON_AUTOMATION_HELP = "--json is only for automation script input/output and should not be used for daily interactive use.";
+export function withJsonAutomationHelp(help) {
+    return help.includes("--json") ? `${help}\n\n${JSON_AUTOMATION_HELP}` : help;
+}
 export function isBlankInput(value) {
     return value.trim().length === 0;
 }

package/build/src/git/read-observation.js

@@ -39,6 +39,7 @@ function batchObjectReader(repository) {
     const child = spawn("git", ["cat-file", "--batch"], {
         cwd: repository.effectiveCwd,
         stdio: ["pipe", "pipe", "pipe"],
+        windowsHide: true,
     });
     const cursor = streamCursor(child.stdout);
     const cache = new Map();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/keiyaku",
-  "version": "4.0.2",
+  "version": "4.0.3",
   "files": [
     "build"
   ],