@astrosheep/keiyaku 4.0.0 → 4.0.1

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

@@ -1,5 +1,5 @@
 import { type TaskId } from "./identity.js";
-import { type TaskWorld } from "./store.js";
+import type { WorldRoot } from "../world.js";
 import type { TaskRefusal, TaskRetry } from "./operations.js";
 type TaskDocumentChange = Readonly<{
     taskId: TaskId;
@@ -21,5 +21,5 @@ export type TaskCompositionResult = Readonly<{
     }>;
     draft: string;
 }>;
-export declare function composeTasks(world: TaskWorld, markdown: string, signal?: AbortSignal): Promise<TaskCompositionResult>;
+export declare function composeTasks(world: WorldRoot, markdown: string, signal?: AbortSignal): Promise<TaskCompositionResult>;
 export {};

package/build/src/task/compose.js

@@ -195,9 +195,9 @@ export async function composeTasks(world, markdown, signal) {
     if ("kind" in sketch)
         return { kind: "refused", refusal: sketch };
     const at = currentTimestamp();
-    const context = sketch.namespace ?? readNamespaceContext(world.root);
+    const context = sketch.namespace ?? readNamespaceContext(world);
     if (context === "malformed")
-        return { kind: "refused", refusal: { kind: "invalid-namespace-context", path: `${world.root}/.keiyaku/namespace/current` } };
+        return { kind: "refused", refusal: { kind: "invalid-namespace-context", path: `${world}/.keiyaku/namespace/current` } };
     const namespace = context === "absent" ? [] : context;
     const initial = readBoard(world);
     const planned = plan(sketch, initial.board, namespace, at);

package/build/src/task/context.js

@@ -1,6 +1,6 @@
 import { lstatSync, mkdirSync, readFileSync, } from "node:fs";
 import { join } from "node:path";
-import { replaceFileDurably } from "../coordination/durable-file.js";
+import { repairDerivedFile, replaceFileDurably } from "../coordination/durable-file.js";
 import { normalizeIdentityStem } from "../identity/normalize.js";
 function directory(root) { return join(root, ".keiyaku", "namespace"); }
 function currentPath(root) { return join(directory(root), "current"); }
@@ -38,12 +38,7 @@ export function installNamespaceContext(root, segments) {
     replaceFileDurably(currentPath(root), `${segments.join("/")}\n`);
 }
 function installIgnore(root) {
-    const ignore = ignorePath(root);
-    const stat = lstatSync(ignore, { throwIfNoEntry: false });
-    if (stat !== undefined && (!stat.isFile() || stat.isSymbolicLink()))
-        throw new Error(`namespace ignore is not a regular file: ${ignore}`);
-    if (stat === undefined || readFileSync(ignore, "utf8") !== "*\n")
-        replaceFileDurably(ignore, "*\n");
+    repairDerivedFile(ignorePath(root), "*\n");
 }
 export function repairNamespaceContext(root, segments) {
     const current = readNamespaceContext(root);

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

@@ -1,9 +1,10 @@
-import { type BlockedTaskRow, type TaskDetailFacts, type TaskDoctorIssue, type TaskRow, type TaskTreeNode } from "./board.js";
+import type { WorldRoot } from "../world.js";
+export type { WorldRoot } from "../world.js";
+import { type BlockedTaskRow, type TaskDetailFacts, type TaskDoctorIssue, type TaskRef, type TaskRow, type TaskTreeNode } from "./board.js";
 import { type TaskCompositionResult } from "./compose.js";
 import { TaskAuthorityCorruptionError, type TaskPriority, type TaskState } from "./document.js";
 import { type TaskId } from "./identity.js";
 import { type AddTaskDocumentInput, type AddTaskInput, type TaskBatchResult, type TaskMutationResult, type TaskOutcome, type TaskRefusal, type TaskRetry, type TaskUpdateResult, type TaskView, type UpdateTaskInput } from "./operations.js";
-import { type TaskWorld } from "./store.js";
 export type TaskDetail = Omit<TaskDetailFacts, "task"> & Readonly<{
     task: TaskView;
 }>;
@@ -14,12 +15,12 @@ export type TaskDoctorReport = Readonly<{
     issues: readonly TaskDoctorIssue[];
 }>;
 export type TaskDependencyTree = TaskOutcome<TaskTreeNode>;
-export type { AddTaskDocumentInput, AddTaskInput, BlockedTaskRow, TaskBatchResult, TaskCompositionResult, TaskDoctorIssue, TaskId, TaskMutationResult, TaskOutcome, TaskPriority, TaskRefusal, TaskRetry, TaskRow, TaskState, TaskUpdateResult, TaskView, UpdateTaskInput };
+export type { AddTaskDocumentInput, AddTaskInput, BlockedTaskRow, TaskBatchResult, TaskCompositionResult, TaskDoctorIssue, TaskId, TaskMutationResult, TaskOutcome, TaskPriority, TaskRef, TaskRefusal, TaskRetry, TaskRow, TaskState, TaskUpdateResult, TaskView, UpdateTaskInput };
 export { TaskAuthorityCorruptionError };
 declare class TaskHandle {
     readonly id: TaskId;
     private readonly world;
-    constructor(id: TaskId, world: TaskWorld);
+    constructor(id: TaskId, world: WorldRoot);
     read(): Promise<TaskDetail | null>;
     tree(input?: Readonly<{
         full?: boolean;
@@ -39,6 +40,7 @@ declare class TaskHandle {
         signal?: AbortSignal;
     }): Promise<TaskMutationResult>;
     done(input?: {
+        note?: string;
         signal?: AbortSignal;
     }): Promise<TaskMutationResult>;
     drop(input?: {
@@ -48,9 +50,9 @@ declare class TaskHandle {
 }
 export type Task = TaskHandle;
 declare class TasksHandle {
-    readonly root: string;
     private readonly world;
-    constructor(path?: string);
+    readonly root: WorldRoot;
+    constructor(world: WorldRoot);
     namespace(): Promise<TaskNamespaceResult>;
     setNamespace(input: Readonly<{
         namespace: readonly string[];
@@ -84,7 +86,5 @@ declare class TasksHandle {
 }
 export type Tasks = TasksHandle;
 export declare const Tasks: Readonly<{
-    at(input?: Readonly<{
-        path?: string;
-    }>): Tasks;
+    of(root: WorldRoot): Tasks;
 }>;

package/build/src/task/index.js

@@ -1,4 +1,3 @@
-import { resolveContextRoot } from "../context-root.js";
 import { buildTree, diagnoseBoard, projectDetailFacts } from "./board.js";
 import { composeTasks } from "./compose.js";
 import { TaskAuthorityCorruptionError } from "./document.js";
@@ -135,8 +134,8 @@ class TaskHandle {
     update(input) { return updateTask(this.world, this.id, updateInput(input)); }
     lifecycle(verb, input) {
         const value = record(input ?? {}, `${verb} input`);
-        closed(value, verb === "drop" ? ["note", "signal"] : ["signal"], `${verb} input`);
-        const note = verb === "drop" ? text(value.note, "note") : undefined;
+        closed(value, verb === "drop" || verb === "done" ? ["note", "signal"] : ["signal"], `${verb} input`);
+        const note = verb === "drop" || verb === "done" ? text(value.note, "note") : undefined;
         return lifecycleTask(this.world, this.id, verb, signal(value.signal), note);
     }
     start(input) { return this.lifecycle("start", input); }
@@ -147,12 +146,11 @@ class TaskHandle {
     drop(input) { return this.lifecycle("drop", input); }
 }
 class TasksHandle {
-    root;
     world;
-    constructor(path) {
-        const root = resolveContextRoot({ from: path ?? process.cwd(), marker: ".keiyaku" });
-        this.world = { root };
-        this.root = root;
+    root;
+    constructor(world) {
+        this.world = world;
+        this.root = world;
     }
     async namespace() { const value = currentNamespace(this.world); return "kind" in value ? { kind: "refused", refusal: value } : { kind: "accepted", value }; }
     async setNamespace(input) { const v = record(input, "setNamespace input"); closed(v, ["namespace"], "setNamespace input"); const ns = namespace(v.namespace); if (ns === undefined)
@@ -170,10 +168,15 @@ class TasksHandle {
         throw new TypeError("scope must be namespace or world"); return blockedTasks(this.world, v.scope); }
     async doctor() { return { issues: diagnoseBoard(readBoard(this.world).board) }; }
     batch(input) { const v = record(input, "batch input"); closed(v, ["verb", "ids", "note", "signal"], "batch input"); const verb = v.verb; if (verb !== "done" && verb !== "drop" && verb !== "hold")
-        throw new TypeError("batch verb is invalid"); const note = text(v.note, "note"); if (note !== undefined && verb !== "drop")
-        throw new TypeError("batch note is valid only for drop"); return batchTasks(this.world, verb, taskIds(v.ids, "ids") ?? [], signal(v.signal), note); }
+        throw new TypeError("batch verb is invalid"); const note = text(v.note, "note"); if (note !== undefined && verb !== "done" && verb !== "drop")
+        throw new TypeError("batch note is valid only for done or drop"); return batchTasks(this.world, verb, taskIds(v.ids, "ids") ?? [], signal(v.signal), note); }
     compose(input) { const v = record(input, "compose input"); closed(v, ["markdown", "signal"], "compose input"); const markdown = text(v.markdown, "markdown"); if (markdown === undefined)
         throw new TypeError("markdown is required"); return composeTasks(this.world, markdown, signal(v.signal)); }
 }
-export const Tasks = Object.freeze({ at(input) { if (input === undefined)
-        return new TasksHandle(); const value = record(input, "Tasks.at input"); closed(value, ["path"], "Tasks.at input"); return new TasksHandle(text(value.path, "path")); } });
+export const Tasks = Object.freeze({
+    of(root) {
+        if (typeof root !== "string")
+            throw new TypeError("Tasks.of root must be a WorldRoot");
+        return new TasksHandle(root);
+    },
+});

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

@@ -1,7 +1,7 @@
 import { type BlockedTaskRow, type TaskRow } from "./board.js";
 import { type TaskDocument, type TaskPriority, type TaskState } from "./document.js";
 import { type TaskId } from "./identity.js";
-import { type TaskWorld } from "./store.js";
+import type { WorldRoot } from "../world.js";
 export type TaskView = Readonly<TaskDocument & {
     namespace: readonly string[];
 }>;
@@ -102,14 +102,33 @@ export type UpdateTaskInput = Readonly<{
     signal?: AbortSignal;
 }>;
 export declare function taskView(document: TaskDocument): TaskView;
-export declare function addTask(world: TaskWorld, input: AddTaskInput): Promise<TaskMutationResult>;
-export declare function addTaskDocument(world: TaskWorld, input: AddTaskDocumentInput): Promise<TaskMutationResult>;
-export declare function updateTask(world: TaskWorld, id: TaskId, input: UpdateTaskInput): Promise<TaskUpdateResult>;
-export declare function lifecycleTask(world: TaskWorld, id: TaskId, verb: TaskLifecycleVerb, signal?: AbortSignal, note?: string): Promise<TaskMutationResult>;
-export declare function batchTasks(world: TaskWorld, verb: "done" | "drop" | "hold", ids: readonly TaskId[], signal?: AbortSignal, note?: string): Promise<TaskBatchResult>;
-export declare function settleTask(world: TaskWorld, id: TaskId, desired: "done" | "open-from-done"): Promise<SettledTaskResult>;
-export declare function listTasks(world: TaskWorld, selection: "active" | "closed" | "all", scope?: "namespace" | "world"): TaskOutcome<readonly TaskRow[]>;
-export declare function readyTasks(world: TaskWorld, scope?: "namespace" | "world"): TaskOutcome<readonly TaskRow[]>;
-export declare function blockedTasks(world: TaskWorld, scope?: "namespace" | "world"): TaskOutcome<readonly BlockedTaskRow[]>;
-export declare function setCurrentNamespace(world: TaskWorld, namespace: readonly string[]): void;
-export declare function currentNamespace(world: TaskWorld): readonly string[] | TaskRefusal;
+export declare function addTask(world: WorldRoot, input: AddTaskInput): Promise<TaskMutationResult>;
+export declare function addTaskDocument(world: WorldRoot, input: AddTaskDocumentInput): Promise<TaskMutationResult>;
+export declare function updateTask(world: WorldRoot, id: TaskId, input: UpdateTaskInput): Promise<TaskUpdateResult>;
+export declare function lifecycleTask(world: WorldRoot, id: TaskId, verb: TaskLifecycleVerb, signal?: AbortSignal, note?: string): Promise<TaskMutationResult>;
+export declare function batchTasks(world: WorldRoot, verb: "done" | "drop" | "hold", ids: readonly TaskId[], signal?: AbortSignal, note?: string): Promise<TaskBatchResult>;
+export declare function settleTask(world: WorldRoot, id: TaskId, desired: "done" | "open-from-done"): Promise<SettledTaskResult>;
+export declare function listTasks(world: WorldRoot, selection: "active" | "closed" | "all", scope?: "namespace" | "world"): TaskOutcome<readonly TaskRow[]>;
+export declare function readyTasks(world: WorldRoot, scope?: "namespace" | "world"): TaskOutcome<readonly TaskRow[]>;
+export declare function blockedTasks(world: WorldRoot, scope?: "namespace" | "world"): TaskOutcome<readonly BlockedTaskRow[]>;
+/** Internal composite observation from one complete Task board read. */
+export declare function observeTaskStatusRows(world: WorldRoot): (Readonly<{
+    id: TaskId;
+    title: string;
+    state: TaskState;
+    priority: TaskPriority;
+    disposition: import("./board.js").TaskDisposition;
+}> | {
+    blockers: readonly Readonly<{
+        id: TaskId;
+        title: string | null;
+        state: TaskState | "missing";
+    }>[];
+    id: TaskId;
+    title: string;
+    state: TaskState;
+    priority: TaskPriority;
+    disposition: import("./board.js").TaskDisposition;
+})[];
+export declare function setCurrentNamespace(world: WorldRoot, namespace: readonly string[]): void;
+export declare function currentNamespace(world: WorldRoot): readonly string[] | TaskRefusal;

package/build/src/task/operations.js

@@ -1,6 +1,6 @@
 import { documentDiff } from "../markdown/diff.js";
 import { installNamespaceContext, readNamespaceContext } from "./context.js";
-import { relationProblem, projectBlocked, projectReady, projectRows } from "./board.js";
+import { relationProblem, projectBlocked, projectReady, projectRows, projectStatusRows } from "./board.js";
 import { parseTaskCreationDocument, serializeTaskDocument } from "./document.js";
 import { allocateLocalId, deriveLocalStem, formatTaskId, parseTaskId, sameNamespace } from "./identity.js";
 import { authorityPath, readBoard, replaceAuthority, withTaskLocks, } from "./store.js";
@@ -12,8 +12,8 @@ function retry(reason) { return { kind: "retry", reason }; }
 function context(world, explicit) {
     if (explicit !== undefined)
         return explicit;
-    const current = readNamespaceContext(world.root);
-    return current === "malformed" ? { kind: "invalid-namespace-context", path: `${world.root}/.keiyaku/namespace/current` }
+    const current = readNamespaceContext(world);
+    return current === "malformed" ? { kind: "invalid-namespace-context", path: `${world}/.keiyaku/namespace/current` }
         : current === "absent" ? [] : current;
 }
 function occupied(board, namespace) {
@@ -187,7 +187,11 @@ export function blockedTasks(world, scope) {
         return { kind: "refused", refusal: selected };
     return { kind: "accepted", value: projectBlocked(readBoard(world).board, selected) };
 }
-export function setCurrentNamespace(world, namespace) { installNamespaceContext(world.root, namespace); }
+/** Internal composite observation from one complete Task board read. */
+export function observeTaskStatusRows(world) {
+    return projectStatusRows(readBoard(world).board, null);
+}
+export function setCurrentNamespace(world, namespace) { installNamespaceContext(world, namespace); }
 export function currentNamespace(world) {
     const selected = context(world);
     return selected;

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

@@ -1,22 +1,20 @@
+import type { WorldRoot } from "../world.js";
 import { type TaskId } from "./identity.js";
 import type { TaskBoard } from "./board.js";
-export type TaskWorld = Readonly<{
-    root: string;
-}>;
 export type BoardSnapshot = Readonly<{
     board: TaskBoard;
     bytes: ReadonlyMap<TaskId, Uint8Array>;
 }>;
-export declare function readBoard(world: TaskWorld): BoardSnapshot;
+export declare function readBoard(world: WorldRoot): BoardSnapshot;
 export declare function replaceAuthority(input: Readonly<{
     path: string;
     expected: Uint8Array | null;
     next: Uint8Array;
 }>): "replaced" | "concurrent-modification";
 export declare function withTaskLocks<T>(input: Readonly<{
-    world: TaskWorld;
+    world: WorldRoot;
     allocation: boolean;
     ids: readonly TaskId[];
     signal?: AbortSignal;
 }>, action: () => Promise<T>): Promise<T | "busy">;
-export declare function authorityPath(world: TaskWorld, id: TaskId): string;
+export declare function authorityPath(world: WorldRoot, id: TaskId): string;

package/build/src/task/store.js

@@ -4,7 +4,7 @@ import { dirname, relative, resolve, sep } from "node:path";
 import { acquireSqliteTransactionLock, SqliteTransactionLockError } from "../coordination/sqlite-transaction-lock.js";
 import { parseTaskDocument } from "./document.js";
 import { formatTaskId, parseTaskId, taskAuthorityPath } from "./identity.js";
-function tasksDirectory(world) { return resolve(world.root, ".keiyaku", "tasks"); }
+function tasksDirectory(world) { return resolve(world, ".keiyaku", "tasks"); }
 function authorityFiles(directory) {
     if (!existsSync(directory))
         return [];
@@ -88,11 +88,11 @@ export function replaceAuthority(input) {
 }
 function lockPath(world, id) {
     const coordinate = parseTaskId(id);
-    return resolve(world.root, ".keiyaku", "locks", "task", ...coordinate.namespace, `${coordinate.localId}.sqlite`);
+    return resolve(world, ".keiyaku", "locks", "task", ...coordinate.namespace, `${coordinate.localId}.sqlite`);
 }
 export async function withTaskLocks(input, action) {
     const paths = [
-        ...(input.allocation ? [resolve(input.world.root, ".keiyaku", "locks", "task-allocation.sqlite")] : []),
+        ...(input.allocation ? [resolve(input.world, ".keiyaku", "locks", "task-allocation.sqlite")] : []),
         ...[...new Set(input.ids)].sort((a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b))).map((id) => lockPath(input.world, id)),
     ];
     const held = [];

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

@@ -4,6 +4,7 @@ export type VerificationExecutor = "bash" | "zsh" | "pwsh";
 export type VerificationDeclaration = Readonly<{
     readonly executor: VerificationExecutor;
     readonly script: string;
+    readonly timeoutMs?: number;
 }>;
 export type VerificationDefinition = Readonly<{
     readonly segment: DocumentSegmentKey;

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

@@ -0,0 +1,49 @@
+import type { SnapshotId } from "../core/facts/types.js";
+import { type HookFailure } from "../git/hooks.js";
+import type { MaterializedScratchCandidate, WorktreeLeak } from "../git/scratch.js";
+import type { GitRepository } from "../git/repository.js";
+import type { Settings } from "../settings.js";
+import type { VerificationDeclaration } from "./declaration.js";
+type VerificationVerdict = "satisfied" | "unsatisfied";
+export type VerificationTerminalOutcome = Readonly<{
+    kind: "terminal";
+    verdict: VerificationVerdict;
+    summary?: string;
+}>;
+export type VerificationNonterminalOutcome = Readonly<{
+    kind: "unknown-exit";
+}> | Readonly<{
+    kind: "cancelled";
+}> | Readonly<{
+    kind: "spawn-error";
+    diagnostic: string;
+}>;
+export type VerificationExecutionStop = VerificationNonterminalOutcome | Readonly<{
+    kind: "candidate-unavailable" | "environment-failure";
+    diagnostic: string;
+}> | Readonly<{
+    kind: "environment-failure";
+    command: number;
+    detail: HookFailure;
+}>;
+export type VerificationExecution = Readonly<{
+    outcome: VerificationTerminalOutcome | VerificationExecutionStop;
+    cleanup?: Readonly<{
+        phase: "destroy";
+        command: number;
+        detail: HookFailure;
+    }>;
+    leak?: WorktreeLeak;
+}>;
+export type ExecuteVerificationInput = Readonly<{
+    repository: GitRepository;
+    candidate: SnapshotId;
+    declarations: readonly VerificationDeclaration[];
+    environment: NodeJS.ProcessEnv;
+    materializeScratchCandidate: (repository: GitRepository, candidate: SnapshotId) => MaterializedScratchCandidate;
+    projectSettings: (root: string) => Settings;
+    signal?: AbortSignal;
+}>;
+/** Execute one disposable Verification attempt over the exact integration snapshot. */
+export declare function executeVerification(input: ExecuteVerificationInput): Promise<VerificationExecution>;
+export {};

package/build/src/verification/execution.js

@@ -0,0 +1,104 @@
+import { runHookCommands, worktreeHooksFrom } from "../git/hooks.js";
+import { runProcess } from "../runtime/proc/run.js";
+const SUMMARY_BYTES = 32 * 1024;
+function argvFor(declaration) {
+    const args = declaration.executor === "pwsh" ? ["-Command", declaration.script] : ["-c", declaration.script];
+    return [declaration.executor, ...args];
+}
+function processDiagnostic(declaration, index, outcome) {
+    if (outcome.code === 0 && outcome.stdout.length === 0 && outcome.stderr.length === 0 && !outcome.truncated) {
+        return null;
+    }
+    return [
+        `[${index + 1} ${declaration.executor} exit ${outcome.code}${outcome.truncated ? " output-truncated" : ""}]`,
+        ...(outcome.stdout.length === 0 ? [] : [`stdout:\n${outcome.stdout}`]),
+        ...(outcome.stderr.length === 0 ? [] : [`stderr:\n${outcome.stderr}`]),
+    ].join("\n");
+}
+function appendSummary(current, diagnostic) {
+    if (diagnostic === null)
+        return current;
+    const combined = Buffer.from(current === undefined ? diagnostic : `${current}\n\n${diagnostic}`);
+    if (combined.length <= SUMMARY_BYTES)
+        return combined.toString("utf8");
+    const marker = Buffer.from("[earlier output truncated]\n");
+    let start = combined.length - (SUMMARY_BYTES - marker.length);
+    while (start < combined.length && (combined[start] & 0xc0) === 0x80)
+        start += 1;
+    return Buffer.concat([marker, combined.subarray(start)]).toString("utf8");
+}
+async function executeDeclarations(input) {
+    let verdict = "satisfied";
+    let summary;
+    for (const [index, declaration] of input.declarations.entries()) {
+        const outcome = await runProcess({
+            argv: argvFor(declaration),
+            cwd: input.cwd,
+            env: input.environment,
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
+            ...(declaration.timeoutMs === undefined ? {} : { timeoutMs: declaration.timeoutMs }),
+        });
+        if (outcome.kind === "timeout") {
+            verdict = "unsatisfied";
+            summary = appendSummary(summary, `[${index + 1} ${declaration.executor} timeout after ${declaration.timeoutMs}ms]`);
+            continue;
+        }
+        if (outcome.kind === "spawn-error" || outcome.kind === "unknown-exit" || outcome.kind === "cancelled")
+            return outcome;
+        if (outcome.code !== 0)
+            verdict = "unsatisfied";
+        summary = appendSummary(summary, processDiagnostic(declaration, index, outcome));
+    }
+    return { kind: "terminal", verdict, ...(summary === undefined ? {} : { summary }) };
+}
+/** Execute one disposable Verification attempt over the exact integration snapshot. */
+export async function executeVerification(input) {
+    let scratch;
+    try {
+        scratch = input.materializeScratchCandidate(input.repository, input.candidate);
+    }
+    catch (error) {
+        return { outcome: { kind: "candidate-unavailable", diagnostic: error instanceof Error ? error.message : String(error) } };
+    }
+    let outcome;
+    let cleanup;
+    let leak = null;
+    let destroy;
+    try {
+        try {
+            const hooks = worktreeHooksFrom({ settings: input.projectSettings(scratch.cwd) });
+            destroy = hooks.destroy;
+            const readiness = await runHookCommands(scratch.cwd, hooks.create, input.signal);
+            outcome = readiness.kind === "cancelled"
+                ? { kind: "cancelled" }
+                : readiness.kind === "failed"
+                    ? { kind: "environment-failure", command: readiness.command, detail: readiness.failure }
+                    : await executeDeclarations({
+                        declarations: input.declarations,
+                        cwd: scratch.cwd,
+                        environment: input.environment,
+                        ...(input.signal === undefined ? {} : { signal: input.signal }),
+                    });
+        }
+        catch (error) {
+            outcome = { kind: "environment-failure", diagnostic: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    finally {
+        if (destroy !== undefined) {
+            const result = await runHookCommands(scratch.cwd, destroy);
+            if (result.kind === "cancelled")
+                throw new Error("scratch destroy cancelled without a signal");
+            if (result.kind === "failed")
+                cleanup = { phase: "destroy", command: result.command, detail: result.failure };
+        }
+        leak = scratch.dispose();
+    }
+    if (outcome === undefined)
+        throw new Error("Verification ended without an outcome");
+    return {
+        outcome,
+        ...(cleanup === undefined ? {} : { cleanup }),
+        ...(leak === null ? {} : { leak }),
+    };
+}

package/build/src/world.d.ts

@@ -0,0 +1,13 @@
+declare const WORLD_BRAND: unique symbol;
+export type WorldRoot = string & {
+    readonly [WORLD_BRAND]: true;
+};
+export declare class WorldError extends Error {
+    readonly kind: "invalid-world" | "home-world" | "root-world";
+    constructor(kind: "invalid-world" | "home-world" | "root-world", message: string);
+}
+export declare const World: Readonly<{
+    locate(input: string): WorldRoot | null;
+    at(input: string): WorldRoot;
+}>;
+export {};

package/build/src/world.js

@@ -0,0 +1,103 @@
+import { existsSync, mkdirSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, parse, resolve } from "node:path";
+const WORLD_BRAND = Symbol("keiyaku.world");
+export class WorldError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.name = "WorldError";
+        this.kind = kind;
+    }
+}
+function homeRoot() {
+    try {
+        return realpathSync(resolve(homedir()));
+    }
+    catch {
+        return resolve(homedir());
+    }
+}
+function directory(input, label) {
+    if (typeof input !== "string" || input.trim().length === 0) {
+        throw new TypeError(`${label} must be a nonblank path`);
+    }
+    const path = resolve(input);
+    let real;
+    try {
+        real = realpathSync(path);
+    }
+    catch (error) {
+        throw new WorldError("invalid-world", `world path is not an existing directory: ${path}`);
+    }
+    try {
+        if (!statSync(real).isDirectory())
+            throw new Error("not a directory");
+    }
+    catch {
+        throw new WorldError("invalid-world", `world path is not a directory: ${real}`);
+    }
+    return real;
+}
+function brand(path) { return path; }
+function marker(root) { return join(root, ".keiyaku"); }
+function rejectReservedRoot(root) {
+    if (root === homeRoot()) {
+        throw new WorldError("home-world", "the user home directory cannot be a Keiyaku world");
+    }
+    if (root === parse(root).root) {
+        throw new WorldError("root-world", "the filesystem root cannot be a Keiyaku world");
+    }
+}
+function ensureMarker(root) {
+    const path = marker(root);
+    if (existsSync(path)) {
+        try {
+            if (!statSync(path).isDirectory())
+                throw new Error("not a directory");
+        }
+        catch {
+            throw new WorldError("invalid-world", `world marker is not a directory: ${path}`);
+        }
+        return;
+    }
+    mkdirSync(path, { recursive: true });
+}
+function exact(input) {
+    const root = directory(input, "world");
+    rejectReservedRoot(root);
+    ensureMarker(root);
+    return brand(root);
+}
+function locateInput(input) {
+    return directory(input, "world location");
+}
+export const World = Object.freeze({
+    locate(input) {
+        let candidate = locateInput(input);
+        const home = homeRoot();
+        for (;;) {
+            const filesystemRoot = parse(candidate).root;
+            if (candidate !== home && candidate !== filesystemRoot && existsSync(marker(candidate))) {
+                try {
+                    if (!statSync(marker(candidate)).isDirectory()) {
+                        throw new WorldError("invalid-world", `world marker is not a directory: ${marker(candidate)}`);
+                    }
+                }
+                catch (error) {
+                    if (error instanceof WorldError)
+                        throw error;
+                    throw new WorldError("invalid-world", `world marker is not a directory: ${marker(candidate)}`);
+                }
+                return brand(candidate);
+            }
+            const parent = dirname(candidate);
+            if (parent === candidate || candidate === filesystemRoot)
+                return null;
+            candidate = parent;
+        }
+    },
+    at(input) {
+        return exact(input);
+    },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/keiyaku",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "files": [
     "build"
   ],
@@ -34,10 +34,11 @@
   "scripts": {
     "build": "node --input-type=module -e \"import { rmSync } from 'node:fs'; rmSync('build', { recursive: true, force: true })\" && tsc -p tsconfig.json && node scripts/copy-integrations.js && node --input-type=module -e \"import { chmodSync } from 'node:fs'; chmodSync('build/src/cli/index.js', 0o755)\"",
     "review:model-impact": "node --import tsx scripts/model-change-impact.ts",
-    "test": "npm run test:architecture && npm run test:maintainability && npm run test:reachability && node --import tsx --test tests/**/*.test.ts tests/maintainability.test.js && npm run test:dogfood",
+    "test": "npm run test:architecture && npm run test:maintainability && npm run test:reachability && node --import tsx scripts/run-tests.mjs",
     "test:architecture": "node --import tsx scripts/check-architecture.ts",
-    "test:dogfood": "npm run build && node --import tsx --test tests/day1-shell-dogfood.dogfood.ts",
+    "test:e2e": "npm run build && node --import tsx --test tests/packaged-cli.e2e.ts",
     "test:maintainability": "node scripts/check-maintainability.js",
+    "test:focused": "node --import tsx --test --test-reporter=dot",
     "test:reachability": "knip --include files,dependencies,unlisted,unresolved,duplicates",
     "test:typecheck": "tsc -p tsconfig.json --noEmit"
   },
@@ -51,10 +52,12 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.226",
+    "@earendil-works/pi-coding-agent": "0.80.10",
+    "@opencode-ai/sdk": "1.18.3",
     "diff": "^8.0.4",
     "yaml": "^2.9.0"
   },
-  "description": "Keiyaku v4 is a clean implementation of an agent-facing contract workflow.",
+  "description": "Keiyaku is an agent-facing contract workflow.",
   "directories": {
     "doc": "docs",
     "test": "tests"