@astrosheep/keiyaku 2.9.9 → 2.9.10

package/build/git/refs.js

@@ -1,11 +1,22 @@
-import { createGit, errorContainsAnyPattern, MISSING_HEAD_PATTERNS, runGitProcess, wrapGitError, } from "./core.js";
-const ZERO_OBJECT_ID = "0000000000000000000000000000000000000000";
+import { isFullGitObjectId, runGitProcess, wrapGitError, } from "./core.js";
 /** Normalize a configured branch to the sole local-branch ref spelling. */
 export function normalizeLocalBranchRef(branch) {
     return branch.startsWith("refs/heads/") ? branch : `refs/heads/${branch}`;
 }
+export const REF_TRANSACTION_CAS_MISMATCH = "REF_TRANSACTION_CAS_MISMATCH";
+export const REF_TRANSACTION_NOT_COMMITTED = "REF_TRANSACTION_NOT_COMMITTED";
+export const REF_TRANSACTION_INDETERMINATE = "REF_TRANSACTION_INDETERMINATE";
+export class RefTransactionError extends Error {
+    code = "REF_TRANSACTION_FAILED";
+    constructor(message, options) {
+        super(message, options);
+        this.name = "RefTransactionError";
+    }
+}
 function isMissingExactRef(result) {
-    return result.status === 1 && result.stdout === "";
+    return !result.error
+        && result.stdout === ""
+        && result.status === 1;
 }
 function parseShowRefRows(output) {
     const lines = output.split(/\r?\n/);
@@ -15,14 +26,18 @@ function parseShowRefRows(output) {
         return null;
     const rows = [];
     for (const line of lines) {
-        const match = /^(?<objectId>[0-9a-fA-F]{40}|[0-9a-fA-F]{64}) (?<ref>refs\/\S+)$/.exec(line);
-        if (!match?.groups)
+        const separator = line.indexOf(" ");
+        const objectId = separator < 0 ? "" : line.slice(0, separator);
+        const ref = separator < 0 ? "" : line.slice(separator + 1);
+        if (!isFullGitObjectId(objectId) || !/^refs\/\S+$/.test(ref))
             return null;
-        rows.push({ objectId: match.groups.objectId, ref: match.groups.ref });
+        rows.push({ objectId, ref });
     }
     return rows;
 }
 function throwGitProcessFailure(commandLabel, result, cwd) {
+    if (result.error?.name === "AbortError")
+        throw result.error;
     const failure = result.error ?? Object.assign(new Error(result.stderr || `git ${commandLabel} exited ${result.status}`), {
         stderr: result.stderr,
         stdout: result.stdout,
@@ -46,58 +61,165 @@ export async function resolveLocalBranchHead(cwd, branch, run = runGitProcess) {
     }
     return throwGitProcessFailure(`show-ref ${ref}`, result, cwd);
 }
-async function resolveRefOrNull(cwd, ref) {
-    const git = createGit(cwd);
-    try {
-        return (await git.raw(["rev-parse", "--verify", ref])).trim();
+async function validateTransactionOperation(cwd, operation, objectIdLength) {
+    const refCheck = await runGitProcess(cwd, ["check-ref-format", operation.ref]);
+    if (refCheck.status !== 0 || refCheck.error) {
+        throw new RefTransactionError(`invalid transaction ref ${JSON.stringify(operation.ref)}`, { cause: refCheck.error });
     }
-    catch (error) {
-        if (errorContainsAnyPattern(error, MISSING_HEAD_PATTERNS))
-            return null;
-        throw wrapGitError(`rev-parse ${ref}`, error, cwd);
+    const objectIds = operation.kind === "update"
+        ? [["new", operation.newOid], ["old", operation.expectedOldOid]]
+        : [["old", operation.expectedOldOid]];
+    for (const [label, oid] of objectIds) {
+        if (oid !== null && (oid.length !== objectIdLength || !isFullGitObjectId(oid))) {
+            throw new RefTransactionError(`invalid ${label} object ID for ${operation.ref}`);
+        }
     }
 }
-/** Create an immutable recovery ref, accepting an earlier identical attempt. */
-export async function createRecoveryRef(cwd, ref, objectId) {
-    const existing = await resolveRefOrNull(cwd, ref);
-    if (existing === objectId)
-        return;
-    if (existing !== null) {
-        throw new Error(`recovery ref ${ref} already resolves to ${existing}, not ${objectId}`);
-    }
-    const git = createGit(cwd);
+function formatTransactionOperation(operation, zero) {
+    if (operation.kind === "delete")
+        return `delete ${operation.ref} ${operation.expectedOldOid}`;
+    if (operation.kind === "verify")
+        return `verify ${operation.ref} ${operation.expectedOldOid ?? zero}`;
+    return `update ${operation.ref} ${operation.newOid} ${operation.expectedOldOid ?? zero}`;
+}
+function isUnambiguousCasRefusal(result) {
+    if (result.status === null || result.status === 0 || result.error)
+        return false;
+    return /cannot lock ref '[^']+': (?:is at [0-9a-f]+ but expected [0-9a-f]+|reference already exists|reference is missing but expected [0-9a-f]+)/i.test(result.stderr);
+}
+function isUnableToResolveReference(result) {
+    return result.status !== null
+        && result.status !== 0
+        && !result.error
+        && /cannot lock ref '[^']+': unable to resolve reference/i.test(result.stderr);
+}
+function hasConclusiveMissingExpectedReference(observations) {
+    return observations.some((observation) => (observation.expectedOldOid !== null
+        && observation.observed.status === "absent"));
+}
+function transactionFailureCause(result) {
+    return result.stderr.trim() || result.error?.message || `exit ${String(result.status)}`;
+}
+function requestedNewOid(operation) {
+    if (operation.kind === "update")
+        return operation.newOid;
+    if (operation.kind === "delete")
+        return null;
+    return operation.expectedOldOid;
+}
+function observationMatches(observation, expectedOid) {
+    if (observation.observed.status === "unknown")
+        return false;
+    if (expectedOid === null)
+        return observation.observed.status === "absent";
+    return observation.observed.status === "present" && observation.observed.objectId === expectedOid;
+}
+async function observeExactRef(cwd, ref) {
     try {
-        await git.raw(["update-ref", ref, objectId, ZERO_OBJECT_ID]);
+        const symbolic = await runGitProcess(cwd, ["symbolic-ref", "--quiet", ref]);
+        if (symbolic.status === 0 && !symbolic.error) {
+            const target = symbolic.stdout.trim();
+            return { status: "unknown", cause: `symbolic ref targets ${target || "an unreported ref"}` };
+        }
+        if (symbolic.error || (symbolic.status !== 1 && symbolic.status !== 0)) {
+            const cause = symbolic.stderr.trim() || symbolic.error?.message || `symbolic-ref exited ${String(symbolic.status)}`;
+            return { status: "unknown", cause };
+        }
+        const exact = await runGitProcess(cwd, ["show-ref", ref]);
+        if (exact.status === 0 && !exact.error) {
+            const exactRows = parseShowRefRows(exact.stdout)?.filter((row) => row.ref === ref);
+            if (exactRows?.length === 1) {
+                return { status: "present", objectId: exactRows[0].objectId };
+            }
+            return { status: "unknown", cause: `show-ref returned an invalid exact value for ${ref}` };
+        }
+        if (!exact.error && exact.status === 1 && exact.stdout === "")
+            return { status: "absent" };
+        const cause = exact.stderr.trim() || exact.error?.message || `show-ref exited ${String(exact.status)}`;
+        return { status: "unknown", cause };
     }
     catch (error) {
-        // Another identical attempt may have won the create race.
-        if (await resolveRefOrNull(cwd, ref) === objectId)
-            return;
-        throw wrapGitError(`update-ref ${ref}`, error, cwd);
+        return { status: "unknown", cause: error instanceof Error ? error.message : String(error) };
     }
 }
-/** Remove only the exact attempt ref, returning truthful non-fatal cleanup facts. */
-export async function deleteRecoveryRef(cwd, ref, objectId) {
+async function observeTransactionRefs(cwd, operations) {
+    return await Promise.all(operations.map(async (operation) => ({
+        ref: operation.ref,
+        expectedOldOid: operation.expectedOldOid,
+        requestedNewOid: requestedNewOid(operation),
+        observed: await observeExactRef(cwd, operation.ref),
+    })));
+}
+/**
+ * Atomically apply a closed set of ref operations. Every old-OID assertion is
+ * submitted inside the same update-ref transaction as its operation; no
+ * preflight read is used as authority.
+ */
+export async function commitRefTransaction(cwd, operations, objectIdLength, options = {}) {
+    if (operations.length === 0)
+        throw new RefTransactionError("a ref transaction requires at least one operation");
+    const seen = new Set();
+    for (const operation of operations) {
+        await validateTransactionOperation(cwd, operation, objectIdLength);
+        if (seen.has(operation.ref))
+            throw new RefTransactionError(`duplicate transaction ref ${operation.ref}`);
+        seen.add(operation.ref);
+    }
+    const zero = "0".repeat(objectIdLength);
+    const input = [
+        "start",
+        ...operations.map((operation) => formatTransactionOperation(operation, zero)),
+        "prepare",
+        "commit",
+        "",
+    ].join("\n");
+    let result;
     try {
-        const existing = await resolveRefOrNull(cwd, ref);
-        if (existing === null)
-            return { ref, status: "already-absent" };
-        if (existing !== objectId) {
-            return {
-                ref,
-                status: "retained",
-                diagnostic: `ref resolves to ${existing}, not expected object ${objectId}`,
-            };
-        }
-        const git = createGit(cwd);
-        await git.raw(["update-ref", "-d", ref, objectId]);
-        return { ref, status: "removed" };
+        result = await (options.run ?? runGitProcess)(cwd, ["update-ref", "--no-deref", "--stdin"], { input });
     }
     catch (error) {
+        result = {
+            stdout: "",
+            stderr: "",
+            status: null,
+            error: error instanceof Error ? error : new Error(String(error)),
+        };
+    }
+    if (result.status === 0 && !result.error) {
+        return { status: "committed", proof: "process-success", operations, observations: [] };
+    }
+    const observations = await observeTransactionRefs(cwd, operations);
+    const allPre = observations.every((observation) => observationMatches(observation, observation.expectedOldOid));
+    const allPost = observations.every((observation) => observationMatches(observation, observation.requestedNewOid));
+    const changesAuthority = operations.some((operation) => requestedNewOid(operation) !== operation.expectedOldOid);
+    const cause = transactionFailureCause(result);
+    if (allPost && changesAuthority) {
+        return { status: "committed", proof: "observed-post-state", operations, observations };
+    }
+    if (isUnambiguousCasRefusal(result)
+        || (isUnableToResolveReference(result) && hasConclusiveMissingExpectedReference(observations))) {
+        return {
+            status: "refused",
+            code: REF_TRANSACTION_CAS_MISMATCH,
+            operations,
+            observations,
+            cause,
+        };
+    }
+    if (allPre && changesAuthority) {
         return {
-            ref,
-            status: "retained",
-            diagnostic: wrapGitError(`update-ref -d ${ref}`, error, cwd).message,
+            status: "refused",
+            code: REF_TRANSACTION_NOT_COMMITTED,
+            operations,
+            observations,
+            cause,
         };
     }
+    return {
+        status: "indeterminate",
+        code: REF_TRANSACTION_INDETERMINATE,
+        operations,
+        observations,
+        cause,
+    };
 }

package/build/git/streaming-batch.js

@@ -1,6 +1,7 @@
 import { spawn } from "node:child_process";
+import { isFullGitObjectId } from "./core.js";
 import { normalizeFilesystemCoordinate } from "../fs/path-coordinate.js";
-import { gitProcessEnv, resolveGitTimeoutMs, } from "./core.js";
+import { gitProcessEnv, resolveGitTimeoutMs, terminateGitChild, } from "./core.js";
 /** Default long-lived batch argv. One-shot calls must not use this gate. */
 export const GIT_STREAMING_BATCH_DEFAULT_ARGS = ["cat-file", "--batch"];
 /** Safety cap for a single response header line before the body frame. */
@@ -15,10 +16,12 @@ export class GitStreamingBatchResponseEndedError extends Error {
 }
 class BufferedReader {
     #iterator;
+    #onProgress;
     #buffer = Buffer.alloc(0);
     #ended = false;
-    constructor(stream) {
+    constructor(stream, onProgress) {
         this.#iterator = stream[Symbol.asyncIterator]();
+        this.#onProgress = onProgress;
     }
     async #fill() {
         if (this.#ended) {
@@ -30,6 +33,7 @@ class BufferedReader {
             throw new GitStreamingBatchResponseEndedError("git streaming batch response ended unexpectedly");
         }
         const chunk = Buffer.isBuffer(next.value) ? next.value : Buffer.from(next.value);
+        this.#onProgress();
         this.#buffer = this.#buffer.length === 0 ? chunk : Buffer.concat([this.#buffer, chunk]);
     }
     async readLine(maxBytes) {
@@ -84,20 +88,36 @@ export class GitStreamingBatchSession {
     #child;
     #reader;
     #stderr = [];
-    #timeout;
+    #timeoutMs;
     #closed;
     #maxHeaderBytes;
+    #signal;
+    #abortListener;
+    #timeout = null;
     #state = { kind: "open" };
     #timedOut = false;
     #aborted = false;
     #inputError = null;
     #requestInFlight = false;
+    #requestDone = null;
+    #finishRequest = null;
+    #requestTimeoutOwner = null;
     #closePromise = null;
-    constructor(cwd, child, timeoutMs, maxHeaderBytes) {
+    #terminationPromise = null;
+    constructor(cwd, child, timeoutMs, maxHeaderBytes, signal) {
         this.cwd = cwd;
         this.#child = child;
-        this.#reader = new BufferedReader(this.#child.stdout);
+        this.#timeoutMs = timeoutMs;
+        this.#reader = new BufferedReader(this.#child.stdout, () => {
+            if (this.#requestTimeoutOwner)
+                this.#armTimeout(this.#requestTimeoutOwner);
+        });
         this.#maxHeaderBytes = maxHeaderBytes;
+        this.#signal = signal;
+        this.#abortListener = () => this.abort();
+        signal?.addEventListener("abort", this.#abortListener, { once: true });
+        if (signal?.aborted)
+            this.abort();
         this.#child.stderr.on("data", (chunk) => this.#stderr.push(chunk));
         this.#child.stdin.on("error", (error) => {
             this.#inputError = error;
@@ -110,10 +130,27 @@ export class GitStreamingBatchSession {
                 resolve({ code, signal });
             });
         });
-        this.#timeout = setTimeout(() => {
+    }
+    #armTimeout(owner) {
+        this.#clearTimeout();
+        const handle = setTimeout(() => {
+            if (this.#timeout?.owner !== owner)
+                return;
+            this.#timeout = null;
             this.#timedOut = true;
+            if (this.#state.kind === "open")
+                this.#state = { kind: "closing" };
             this.#child.kill("SIGKILL");
-        }, timeoutMs);
+        }, this.#timeoutMs);
+        this.#timeout = { owner, handle };
+    }
+    #clearTimeout(owner) {
+        if (this.#timeout === null)
+            return;
+        if (owner !== undefined && this.#timeout.owner !== owner)
+            return;
+        clearTimeout(this.#timeout.handle);
+        this.#timeout = null;
     }
     /**
      * Open the sole long-lived Git batch process for `cwd`.
@@ -125,11 +162,11 @@ export class GitStreamingBatchSession {
         const maxHeaderBytes = options?.maxHeaderBytes ?? GIT_STREAMING_BATCH_MAX_HEADER_BYTES;
         const child = spawn("git", [...args], {
             cwd: normalizeFilesystemCoordinate(cwd),
-            env: gitProcessEnv(),
+            env: gitProcessEnv(options?.env),
             shell: false,
             stdio: ["pipe", "pipe", "pipe"],
         });
-        return new GitStreamingBatchSession(cwd, child, timeoutMs, maxHeaderBytes);
+        return new GitStreamingBatchSession(cwd, child, timeoutMs, maxHeaderBytes, options?.signal);
     }
     /**
      * Write one request line and read one framed response record.
@@ -142,7 +179,13 @@ export class GitStreamingBatchSession {
         if (this.#requestInFlight) {
             throw new Error("git streaming batch rejects concurrent requests");
         }
+        const timeoutOwner = Symbol("git-streaming-batch-request");
         this.#requestInFlight = true;
+        this.#requestTimeoutOwner = timeoutOwner;
+        this.#requestDone = new Promise((resolve) => {
+            this.#finishRequest = resolve;
+        });
+        this.#armTimeout(timeoutOwner);
         try {
             if (this.#inputError)
                 throw this.#inputError;
@@ -168,7 +211,8 @@ export class GitStreamingBatchSession {
             catch (error) {
                 if (error instanceof GitStreamingBatchFramingError
                     || error instanceof GitStreamingBatchResponseEndedError) {
-                    this.abort();
+                    if (!this.#timedOut)
+                        this.abort();
                 }
                 throw error;
             }
@@ -183,7 +227,7 @@ export class GitStreamingBatchSession {
             const size = Number(sizeText);
             if (unexpected.length > 0
                 || !oid
-                || !/^[0-9a-f]{40,64}$/.test(oid)
+                || !isFullGitObjectId(oid)
                 || !type
                 || !Number.isSafeInteger(size)
                 || size < 0) {
@@ -221,7 +265,13 @@ export class GitStreamingBatchSession {
             };
         }
         finally {
+            this.#clearTimeout(timeoutOwner);
+            this.#requestTimeoutOwner = null;
             this.#requestInFlight = false;
+            const finishRequest = this.#finishRequest;
+            this.#finishRequest = null;
+            this.#requestDone = null;
+            finishRequest?.();
         }
     }
     /**
@@ -232,11 +282,12 @@ export class GitStreamingBatchSession {
         if (this.#aborted)
             return;
         this.#aborted = true;
+        this.#clearTimeout();
         if (this.#state.kind === "open") {
             this.#state = { kind: "closing" };
         }
         this.#child.stdin.destroy();
-        this.#child.kill("SIGKILL");
+        this.#terminationPromise ??= terminateGitChild(this.#child, this.#closed);
     }
     /**
      * End stdin, await process exit, and return structured close facts.
@@ -263,7 +314,15 @@ export class GitStreamingBatchSession {
         return this.#closePromise;
     }
     async #closeOnce() {
+        const pendingRequest = this.#requestDone;
+        if (pendingRequest)
+            await pendingRequest;
+        if (this.#terminationPromise)
+            await this.#terminationPromise;
+        const timeoutOwner = Symbol("git-streaming-batch-close");
         if (!this.#aborted && this.#child.stdin?.writable) {
+            if (!this.#timedOut)
+                this.#armTimeout(timeoutOwner);
             this.#child.stdin.end();
         }
         let exit;
@@ -271,8 +330,9 @@ export class GitStreamingBatchSession {
             exit = await this.#closed;
         }
         finally {
-            clearTimeout(this.#timeout);
+            this.#clearTimeout(timeoutOwner);
         }
+        this.#signal?.removeEventListener("abort", this.#abortListener);
         if (exit.processError && !this.#aborted) {
             const fact = {
                 code: null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/keiyaku",
-  "version": "2.9.9",
+  "version": "2.9.10",
   "description": "CLI for running iterative keiyaku workflows with Codex subagents.",
   "license": "MIT",
   "type": "module",

package/skills/keiyaku/SKILL.md

@@ -33,7 +33,7 @@ EOF
 ```
 
 That's the whole loop. Skip the task when the work needs no planning:
-`keiyaku bind --place NAME --objective TEXT --scope GLOB --checks CHECK` (or the same as Markdown through `keiyaku bind -` — `bind --help` shows the shape).
+`keiyaku bind --title TEXT --context TEXT --objective TEXT --design TEXT --scope GLOB --criteria TEXT [--verification COMMAND]` (or the same settled document through `keiyaku bind -` — `bind --help` shows the shape).
 
 ## Getting oriented
 

package/skills/keiyaku-akuma/SKILL.md

@@ -41,10 +41,10 @@ addressable. `revive` starts a new projection and does not inherit an alias.
 
 ```bash
 keiyaku akuma ls                              # who's callable
-keiyaku akuma view NAME                       # resolved profile + live projections
+keiyaku akuma show NAME                       # resolved profile + live projections
 keiyaku call NAME "do the thing"              # run in foreground until it finishes
 keiyaku call NAME --wait 10m "do the thing"   # bounded: after 10m you get a snapshot, it keeps running
-keiyaku call NAME --detach "do the thing"     # fire and forget; note the projection id
+keiyaku call NAME -d "do the thing"           # short for --detach; note the projection id
 keiyaku call NAME - < prompt.md               # long prompt: literal `-` reads stdin
 keiyaku wait <proj-id>                        # join a running one; prints its activity
 keiyaku wait <proj-id> --timeout 5m           # peek for 5m; timeout = snapshot, not death
@@ -63,7 +63,7 @@ keiyaku status                                # forgot an id? it's on the board
 <KEIYAKU_HOME>/akuma/<name>.md           user profile (normally ~/.keiyaku)
 ```
 
-Use `keiyaku akuma view NAME` to inspect the resolved source and configuration.
+Use `keiyaku akuma show NAME` to inspect the resolved source and configuration.
 
 ## Expectations
 

package/skills/keiyaku-task/SKILL.md

@@ -52,8 +52,10 @@ keiyaku bind --task fix-parser --task fix-parser-help - < contract.md
 Only ready tasks bind. Multi-bind only when the tasks describe one delivery
 intent, share a coherent write surface, and should settle together; otherwise
 keep separate contracts and express order with task `needs` or contract
-`--after`. The first task supplies name/objective defaults; provide a partial
-bind document for any missing `Scope` or `Checks`.
+`--after`. The first task supplies title/objective defaults; provide a partial
+bind document for every remaining resolved section. Final bind admission always
+requires Title, Context, Objective, Design, Scope, and Criteria; Verification
+is optional.
 
 ## Gotcha