@astrosheep/keiyaku 4.5.19 → 4.5.21

package/build/src/runtime/proc/run.js

@@ -1,5 +1,6 @@
 import { spawn } from "node:child_process";
 import { open } from "node:fs/promises";
+import { StringDecoder } from "node:string_decoder";
 import crossSpawn from "cross-spawn";
 import { spawnOptionsFor } from "./launch.js";
 import { detachedExitStatus, retainDetachedExitEvidence } from "./process-exit.js";
@@ -73,7 +74,10 @@ function tailCapture(limit) {
             const size = Math.min(total, limit);
             const start = total > limit ? cursor : 0;
             const value = start === 0 ? bytes.subarray(0, size) : Buffer.concat([bytes.subarray(start), bytes.subarray(0, start)]);
-            return { text: value.toString("utf8"), truncated: total > limit };
+            let startAt = 0;
+            while (startAt < value.length && (value[startAt] & 0xc0) === 0x80)
+                startAt += 1;
+            return { text: value.subarray(startAt).toString("utf8"), truncated: total > limit };
         },
     };
 }
@@ -137,21 +141,55 @@ export async function spawnDetachedProcess(input) {
             await log.close();
     }
 }
-function terminalOutcome(code, stdout, stderr, consuming) {
+function capturedOutput(stdout, stderr, consuming) {
     return {
-        kind: "terminal",
-        code,
         stdout: consuming ? "" : stdout.text,
         stderr: stderr.text,
         truncated: (consuming ? false : stdout.truncated) || stderr.truncated,
     };
 }
+function outputObservation(input, consumingStdout) {
+    const decoders = input.onOutput === undefined
+        ? undefined
+        : {
+            ...(consumingStdout ? {} : { stdout: new StringDecoder("utf8") }),
+            stderr: new StringDecoder("utf8"),
+        };
+    const report = (stream, text) => {
+        if (text.length === 0)
+            return;
+        try {
+            input.onOutput?.({ stream, text });
+        }
+        catch {
+            // Observation is not process ownership: a consumer cannot strand the owned child.
+        }
+    };
+    return {
+        observe(stream, chunk) {
+            const decoder = decoders?.[stream];
+            if (decoder !== undefined)
+                report(stream, decoder.write(chunk));
+        },
+        finish() {
+            if (decoders === undefined)
+                return;
+            for (const stream of ["stdout", "stderr"]) {
+                const decoder = decoders[stream];
+                if (decoder !== undefined)
+                    report(stream, decoder.end());
+            }
+        },
+    };
+}
 async function executeProcess(input, timeoutMs, consumeStdout, spawnProcess = spawn) {
-    if (input.signal?.aborted === true)
-        return { outcome: { kind: "cancelled" }, pid: null };
+    if (input.signal?.aborted === true) {
+        return { outcome: { kind: "cancelled", stdout: "", stderr: "", truncated: false }, pid: null };
+    }
     const child = spawnProcess(input.argv[0], input.argv.slice(1), spawnOptionsFor(input, ["ignore", "pipe", "pipe"]));
     const stdout = tailCapture(STREAM_TAIL_BYTES);
     const stderr = tailCapture(STREAM_TAIL_BYTES);
+    const output = outputObservation(input, consumeStdout !== undefined);
     let stop;
     let streamError;
     let termination;
@@ -175,16 +213,21 @@ async function executeProcess(input, timeoutMs, consumeStdout, spawnProcess = sp
     child.stdout.on("data", (chunk) => {
         if (consumeStdout === undefined) {
             stdout.append(chunk);
-            return;
-        }
-        try {
-            consumeStdout(chunk);
         }
-        catch (error) {
-            failStream(error);
+        else {
+            try {
+                consumeStdout(chunk);
+            }
+            catch (error) {
+                failStream(error);
+            }
         }
+        output.observe("stdout", chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+        stderr.append(chunk);
+        output.observe("stderr", chunk);
     });
-    child.stderr.on("data", (chunk) => stderr.append(chunk));
     if (consumeStdout !== undefined) {
         child.stdout.once("error", failStream);
         child.stderr.once("error", failStream);
@@ -199,29 +242,28 @@ async function executeProcess(input, timeoutMs, consumeStdout, spawnProcess = sp
     if (terminal.kind === "termination-error")
         throw terminal.error;
     await termination;
+    output.finish();
     const pid = child.pid ?? null;
+    const capture = capturedOutput(stdout.result(), stderr.result(), consumeStdout !== undefined);
     if (terminal.kind === "spawn-error") {
-        return { outcome: { kind: "spawn-error", diagnostic: terminal.error.message }, pid };
+        return { outcome: { kind: "spawn-error", diagnostic: terminal.error.message, ...capture }, pid };
     }
     if (streamError !== undefined) {
         return {
             outcome: {
                 kind: "stream-error",
                 diagnostic: streamError instanceof Error ? streamError.message : String(streamError),
+                stderr: capture.stderr,
+                truncated: capture.truncated,
             },
             pid,
         };
     }
     if (stop !== undefined)
-        return { outcome: { kind: stop }, pid };
+        return { outcome: { kind: stop, ...capture }, pid };
     if (terminal.code === null)
-        return { outcome: { kind: "unknown-exit" }, pid };
-    const capturedStdout = stdout.result();
-    const capturedStderr = stderr.result();
-    return {
-        outcome: terminalOutcome(terminal.code, capturedStdout, capturedStderr, consumeStdout !== undefined),
-        pid,
-    };
+        return { outcome: { kind: "unknown-exit", ...capture }, pid };
+    return { outcome: { kind: "terminal", code: terminal.code, ...capture }, pid };
 }
 export async function runProcess(input) {
     const result = await executeProcess(input, input.timeoutMs);

package/build/src/settings.js

@@ -152,9 +152,6 @@ function bundleGates(name, value) {
         if (!gateWord(gate)) {
             throw new SettingsError(`gate bundle '${name}' contains an invalid gate word`);
         }
-        if (gate !== "reviewed" && gate !== "verified") {
-            throw new SettingsError(`gate bundle '${name}' contains a gate without a producer: ${gate}`);
-        }
         return gate;
     });
 }
@@ -167,8 +164,10 @@ export function gatesFrom(input) {
     const names = input.names ?? ["default"];
     for (const name of names) {
         if (!gateWord(name))
-            throw new SettingsError("gate bundle name must match ^[a-z][a-z0-9-]{0,63}$");
+            throw new SettingsError("gate or bundle name must match ^[a-z][a-z0-9-]{0,63}$");
     }
+    if (names.length === 0)
+        return Object.freeze([]);
     const view = input.settings.namespace("gates");
     if (view.kind === "failed")
         namespaceFailure(view);
@@ -176,16 +175,8 @@ export function gatesFrom(input) {
     const seen = new Set();
     for (const name of names) {
         const selected = view.entries.find((entry) => entry.name === name);
-        if (selected === undefined) {
-            if (input.names === undefined) {
-                if (!seen.has("reviewed"))
-                    expanded.push("reviewed");
-                seen.add("reviewed");
-                continue;
-            }
-            throw new SettingsError(`unknown gate bundle: ${name}`);
-        }
-        for (const gate of bundleGates(name, selected.value)) {
+        const gates = selected === undefined ? [input.names === undefined ? "reviewed" : name] : bundleGates(name, selected.value);
+        for (const gate of gates) {
             if (seen.has(gate))
                 continue;
             seen.add(gate);

package/build/src/task/document.d.ts

@@ -18,7 +18,11 @@ export type TaskDocument = Readonly<{
 }>;
 export type TaskCreationDocument = Omit<TaskDocument, "id" | "createdBy" | "createdAt" | "updatedAt">;
 export declare class TaskAuthorityCorruptionError extends Error {
-    constructor(message: string, options?: ErrorOptions);
+    /** The Task document whose bytes failed decode, when the reader knew its coordinate. */
+    readonly coordinate?: TaskId;
+    constructor(message: string, options?: ErrorOptions & {
+        coordinate?: TaskId;
+    });
 }
 export declare function parseTaskDocument(bytes: Uint8Array, expected: TaskCoordinate): TaskDocument;
 export declare function parseTaskCreationDocument(markdown: string): TaskCreationDocument;

package/build/src/task/document.js

@@ -1,9 +1,13 @@
 import { isMap, parseDocument, stringify } from "yaml";
 import { formatTaskId, parseTaskId } from "./identity.js";
 export class TaskAuthorityCorruptionError extends Error {
+    /** The Task document whose bytes failed decode, when the reader knew its coordinate. */
+    coordinate;
     constructor(message, options) {
         super(message, options);
         this.name = "TaskAuthorityCorruptionError";
+        if (options?.coordinate !== undefined)
+            this.coordinate = options.coordinate;
     }
 }
 const STATES = new Set(["open", "in_progress", "on_hold", "done", "drop"]);
@@ -107,8 +111,9 @@ function fields(value, body, fail) {
     };
 }
 export function parseTaskDocument(bytes, expected) {
+    const coordinate = formatTaskId(expected);
     const fail = (message, cause) => {
-        throw new TaskAuthorityCorruptionError(message, cause === undefined ? {} : { cause });
+        throw new TaskAuthorityCorruptionError(message, { coordinate, ...(cause === undefined ? {} : { cause }) });
     };
     const { value, body } = frontMatter(Buffer.from(bytes).toString("utf8"), fail);
     closed(value, STORED_KEYS, REQUIRED_STORED_KEYS, fail);

package/build/src/verification/execution.d.ts

@@ -3,6 +3,7 @@ import { type HookFailure } from "../git/hooks.js";
 import type { MaterializedScratchCandidate, WorktreeLeak } from "../git/scratch.js";
 import type { GitRepository } from "../git/process.js";
 import type { Settings } from "../settings.js";
+import type { VerificationObservation } from "./observation.js";
 import type { VerificationDeclaration } from "./declaration.js";
 type VerificationVerdict = "satisfied" | "unsatisfied";
 export type VerificationTerminalOutcome = Readonly<{
@@ -12,14 +13,20 @@ export type VerificationTerminalOutcome = Readonly<{
     total: number;
     summary?: string;
 }>;
-export type VerificationNonterminalOutcome = Readonly<{
+export type CapturedOutput = Readonly<{
+    stdout?: string;
+    stderr?: string;
+    truncated?: boolean;
+}>;
+export type VerificationNonterminalOutcome = CapturedOutput & (Readonly<{
     kind: "unknown-exit";
 }> | Readonly<{
     kind: "cancelled";
 }> | Readonly<{
     kind: "spawn-error";
     diagnostic: string;
-}>;
+}>);
+export declare function capturedOutput(value: CapturedOutput): CapturedOutput;
 export type VerificationExecutionStop = VerificationNonterminalOutcome | Readonly<{
     kind: "candidate-unavailable" | "environment-failure";
     diagnostic: string;
@@ -43,6 +50,7 @@ export type ExecuteVerificationInput = Readonly<{
     declarations: readonly VerificationDeclaration[];
     materializeScratchCandidate: (repository: GitRepository, candidate: SnapshotId) => Promise<MaterializedScratchCandidate>;
     projectSettings: (root: string) => Promise<Settings>;
+    observe?: (event: VerificationObservation) => void;
     signal?: AbortSignal;
 }>;
 /** Execute one disposable Verification attempt over the exact integration snapshot. */

package/build/src/verification/execution.js

@@ -1,6 +1,28 @@
 import { runHookCommands, worktreeHooksFrom } from "../git/hooks.js";
 import { runProcess } from "../runtime/proc/run.js";
 const SUMMARY_BYTES = 32 * 1024;
+export function capturedOutput(value) {
+    return {
+        ...(value.stdout ? { stdout: value.stdout } : {}),
+        ...(value.stderr ? { stderr: value.stderr } : {}),
+        ...(value.truncated === true ? { truncated: true } : {}),
+    };
+}
+function observe(input, event) {
+    try {
+        input.observe?.(event);
+    }
+    catch {
+        /* Observation does not own execution. */
+    }
+}
+function outputSummary(output) {
+    return [
+        ...(output.stdout ? [`stdout:\n${output.stdout}`] : []),
+        ...(output.stderr ? [`stderr:\n${output.stderr}`] : []),
+        ...(output.truncated ? ["[output truncated]"] : []),
+    ].join("\n");
+}
 function argvFor(declaration) {
     const args = declaration.executor === "pwsh" ? ["-Command", declaration.script] : ["-c", declaration.script];
     return [declaration.executor, ...args];
@@ -27,26 +49,63 @@ function appendSummary(current, diagnostic) {
         start += 1;
     return Buffer.concat([marker, combined.subarray(start)]).toString("utf8");
 }
+async function observedHooks(input) {
+    const { execution, cwd, commands, phase, signal, environment } = input;
+    for (const command of commands) {
+        const coordinate = { phase, cwd, name: command.name };
+        const started = performance.now();
+        observe(execution, { kind: "phase", ...coordinate, state: "started" });
+        const result = await runHookCommands(cwd, [command], signal, environment, (output) => observe(execution, { kind: "output", ...coordinate, ...output }));
+        observe(execution, {
+            kind: "phase",
+            ...coordinate,
+            state: "finished",
+            outcome: result.kind,
+            elapsedMs: performance.now() - started,
+        });
+        if (result.kind !== "ok")
+            return result;
+    }
+    return { kind: "ok" };
+}
+function nonterminalOutcome(outcome) {
+    return outcome.kind === "spawn-error"
+        ? { kind: outcome.kind, diagnostic: outcome.diagnostic, ...capturedOutput(outcome) }
+        : { kind: outcome.kind, ...capturedOutput(outcome) };
+}
 async function executeDeclarations(input) {
     let verdict = "satisfied";
     let passed = 0;
     const total = input.declarations.length;
     let summary;
     for (const [index, declaration] of input.declarations.entries()) {
+        const coordinate = { phase: "declaration", cwd: input.cwd, index: index + 1, total };
+        const started = performance.now();
+        observe(input, { kind: "phase", ...coordinate, state: "started" });
         const outcome = await runProcess({
             argv: argvFor(declaration),
             cwd: input.cwd,
             env: input.environment,
+            onOutput: (output) => observe(input, { kind: "output", ...coordinate, ...output }),
             ...(input.signal === undefined ? {} : { signal: input.signal }),
             ...(declaration.timeoutMs === undefined ? {} : { timeoutMs: declaration.timeoutMs }),
         });
+        observe(input, {
+            kind: "phase",
+            ...coordinate,
+            state: "finished",
+            outcome: outcome.kind === "terminal" ? `exit ${outcome.code}` : outcome.kind,
+            elapsedMs: performance.now() - started,
+        });
         if (outcome.kind === "timeout") {
             verdict = "unsatisfied";
-            summary = appendSummary(summary, `[${index + 1} ${declaration.executor} timeout after ${declaration.timeoutMs}ms]`);
+            summary = appendSummary(summary, [`[${index + 1} ${declaration.executor} timeout after ${declaration.timeoutMs}ms]`, outputSummary(outcome)]
+                .filter(Boolean)
+                .join("\n"));
             continue;
         }
         if (outcome.kind === "spawn-error" || outcome.kind === "unknown-exit" || outcome.kind === "cancelled")
-            return outcome;
+            return nonterminalOutcome(outcome);
         if (outcome.code === 0)
             passed += 1;
         else
@@ -55,58 +114,100 @@ async function executeDeclarations(input) {
     }
     return { kind: "terminal", verdict, passed, total, ...(summary === undefined ? {} : { summary }) };
 }
-/** Execute one disposable Verification attempt over the exact integration snapshot. */
-export async function executeVerification(input) {
-    const environment = process.env;
-    let scratch;
+async function materializeScratch(input) {
+    observe(input, { kind: "phase", phase: "materialize", state: "started" });
     try {
-        scratch = await input.materializeScratchCandidate(input.repository, input.candidate);
+        input.signal?.throwIfAborted();
+        const scratch = await input.materializeScratchCandidate(input.repository, input.candidate);
+        observe(input, { kind: "phase", phase: "materialize", state: "finished", cwd: scratch.cwd, outcome: "ok" });
+        return scratch;
     }
     catch (error) {
+        observe(input, {
+            kind: "phase",
+            phase: "materialize",
+            state: "finished",
+            outcome: input.signal?.aborted ? "cancelled" : "failed",
+        });
+        if (input.signal?.aborted)
+            return { outcome: { kind: "cancelled" } };
         return {
             outcome: { kind: "candidate-unavailable", diagnostic: error instanceof Error ? error.message : String(error) },
         };
     }
-    let outcome;
-    let cleanup;
-    let leak = null;
-    let destroy;
+}
+async function runScratch(input, scratch) {
     try {
-        try {
-            const hooks = worktreeHooksFrom({ settings: await input.projectSettings(scratch.cwd) });
-            destroy = hooks.destroy;
-            const readiness = await runHookCommands(scratch.cwd, hooks.create, input.signal, environment);
-            outcome =
-                readiness.kind === "cancelled"
-                    ? { kind: "cancelled" }
-                    : readiness.kind === "failed"
-                        ? { kind: "environment-failure", name: readiness.name, detail: readiness.failure }
-                        : await executeDeclarations({
-                            declarations: input.declarations,
-                            cwd: scratch.cwd,
-                            environment,
-                            ...(input.signal === undefined ? {} : { signal: input.signal }),
-                        });
-        }
-        catch (error) {
-            outcome = { kind: "environment-failure", diagnostic: error instanceof Error ? error.message : String(error) };
-        }
+        input.signal?.throwIfAborted();
+        const hooks = worktreeHooksFrom({ settings: await input.projectSettings(scratch.cwd) });
+        const readiness = await observedHooks({
+            execution: input,
+            cwd: scratch.cwd,
+            commands: hooks.create,
+            phase: "setup",
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
+            environment: process.env,
+        });
+        if (readiness.kind === "cancelled")
+            return { outcome: { kind: "cancelled", ...capturedOutput(readiness) }, destroy: hooks.destroy };
+        if (readiness.kind === "failed")
+            return {
+                outcome: { kind: "environment-failure", name: readiness.name, detail: readiness.failure },
+                destroy: hooks.destroy,
+            };
+        return {
+            outcome: await executeDeclarations({
+                declarations: input.declarations,
+                cwd: scratch.cwd,
+                environment: process.env,
+                ...(input.observe === undefined ? {} : { observe: input.observe }),
+                ...(input.signal === undefined ? {} : { signal: input.signal }),
+            }),
+            destroy: hooks.destroy,
+        };
     }
-    finally {
-        if (destroy !== undefined) {
-            const result = await runHookCommands(scratch.cwd, destroy, undefined, environment);
-            if (result.kind === "cancelled")
-                throw new Error("scratch destroy cancelled without a signal");
-            if (result.kind === "failed")
-                cleanup = { phase: "destroy", name: result.name, detail: result.failure };
-        }
-        leak = await scratch.dispose();
+    catch (error) {
+        return {
+            outcome: input.signal?.aborted
+                ? { kind: "cancelled" }
+                : { kind: "environment-failure", diagnostic: error instanceof Error ? error.message : String(error) },
+        };
     }
-    if (outcome === undefined)
-        throw new Error("Verification ended without an outcome");
+}
+async function retireScratch(input, scratch, destroy) {
+    observe(input, { kind: "phase", phase: "cleanup", cwd: scratch.cwd, state: "started" });
+    let cleanup;
+    if (destroy !== undefined) {
+        const result = await observedHooks({
+            execution: input,
+            cwd: scratch.cwd,
+            commands: destroy,
+            phase: "cleanup",
+            environment: process.env,
+        });
+        if (result.kind === "cancelled")
+            throw new Error("scratch destroy cancelled without a signal");
+        if (result.kind === "failed")
+            cleanup = { phase: "destroy", name: result.name, detail: result.failure };
+    }
+    const leak = await scratch.dispose();
+    observe(input, {
+        kind: "phase",
+        phase: "cleanup",
+        cwd: scratch.cwd,
+        state: "finished",
+        outcome: leak !== null || cleanup !== undefined ? "failed" : "ok",
+    });
     return {
-        outcome,
         ...(cleanup === undefined ? {} : { cleanup }),
         ...(leak === null ? {} : { leak }),
     };
 }
+/** Execute one disposable Verification attempt over the exact integration snapshot. */
+export async function executeVerification(input) {
+    const materialized = await materializeScratch(input);
+    if ("outcome" in materialized)
+        return materialized;
+    const prepared = await runScratch(input, materialized);
+    return { outcome: prepared.outcome, ...(await retireScratch(input, materialized, prepared.destroy)) };
+}

package/build/src/verification/observation.d.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+export declare const verificationObservationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    state: z.ZodEnum<{
+        finished: "finished";
+        started: "started";
+    }>;
+    outcome: z.ZodOptional<z.ZodString>;
+    elapsedMs: z.ZodOptional<z.ZodNumber>;
+    phase: z.ZodEnum<{
+        cleanup: "cleanup";
+        materialize: "materialize";
+        setup: "setup";
+        declaration: "declaration";
+    }>;
+    cwd: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    command: z.ZodOptional<z.ZodString>;
+    index: z.ZodOptional<z.ZodNumber>;
+    total: z.ZodOptional<z.ZodNumber>;
+    kind: z.ZodLiteral<"phase">;
+}, z.core.$strict>, z.ZodObject<{
+    stream: z.ZodEnum<{
+        stdout: "stdout";
+        stderr: "stderr";
+    }>;
+    text: z.ZodString;
+    phase: z.ZodEnum<{
+        cleanup: "cleanup";
+        materialize: "materialize";
+        setup: "setup";
+        declaration: "declaration";
+    }>;
+    cwd: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    command: z.ZodOptional<z.ZodString>;
+    index: z.ZodOptional<z.ZodNumber>;
+    total: z.ZodOptional<z.ZodNumber>;
+    kind: z.ZodLiteral<"output">;
+}, z.core.$strict>], "kind">;
+/** Attempt-local observations, never testimony, liveness, or recovery authority. */
+export type VerificationObservation = z.infer<typeof verificationObservationSchema>;

package/build/src/verification/observation.js

@@ -0,0 +1,29 @@
+import { z } from "zod";
+const phase = z.enum(["materialize", "setup", "declaration", "cleanup"]);
+const coordinate = {
+    phase,
+    cwd: z.string().optional(),
+    name: z.string().optional(),
+    command: z.string().optional(),
+    index: z.number().int().positive().optional(),
+    total: z.number().int().nonnegative().optional(),
+};
+export const verificationObservationSchema = z.discriminatedUnion("kind", [
+    z
+        .object({
+        kind: z.literal("phase"),
+        ...coordinate,
+        state: z.enum(["started", "finished"]),
+        outcome: z.string().optional(),
+        elapsedMs: z.number().nonnegative().optional(),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("output"),
+        ...coordinate,
+        stream: z.enum(["stdout", "stderr"]),
+        text: z.string(),
+    })
+        .strict(),
+]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/keiyaku",
-  "version": "4.5.19",
+  "version": "4.5.21",
   "workspaces": [
     "plugins/*"
   ],
@@ -39,6 +39,7 @@
     "node": ">=22.19.0"
   },
   "scripts": {
+    "release": "npm run test:release && npm version patch && npm publish",
     "build": "node --input-type=module -e \"import { rmSync } from 'node:fs'; rmSync('build', { recursive: true, force: true })\" && tsc -p tsconfig.json && npm run build --workspace @astrosheep/keiyaku-plugin-square && node scripts/copy-integrations.js && node scripts/build-windows-launcher.js && node --input-type=module -e \"import { chmodSync } from 'node:fs'; chmodSync('build/src/cli/index.js', 0o755)\"",
     "prepack": "node scripts/verify-package.js",
     "postpack": "node scripts/verify-package.js",
@@ -80,6 +81,7 @@
     "@agentclientprotocol/sdk": "^1.3.0",
     "@anthropic-ai/claude-agent-sdk": "^0.3.226",
     "@astrosheep/keiyaku-plugin-square": "0.1.5",
+    "@astrosheep/square": "^0.3.50",
     "@earendil-works/pi-coding-agent": "0.85.1",
     "@opencode-ai/sdk": "1.18.3",
     "cross-spawn": "^7.0.6",