@astrosheep/keiyaku 4.5.11 → 4.5.13

package/build/src/core/verbs/abandon.d.ts

@@ -1,5 +1,5 @@
 import type { DecideInput, OfferDecision } from "../decide.js";
-import type { ActorId, ContractId } from "../facts/types.js";
+import { type ActorId, type ContractId } from "../facts/types.js";
 export type AbandonInput = Readonly<{
     contractId: ContractId;
     actor?: ActorId;
@@ -10,4 +10,5 @@ export type AbandonRefusal = Readonly<{
     kind: "contract-missing" | "terminal";
     contractId: ContractId;
 }>;
+export declare function decodeAbandonRefusal(value: unknown): AbandonRefusal;
 export declare function decideAbandon({ input, attempt, observation, }: DecideInput<AbandonInput>): OfferDecision<AbandonRefusal>;

package/build/src/core/verbs/abandon.js

@@ -1,4 +1,20 @@
 import { activeContract } from "../facts/observation.js";
+import { contractId } from "../facts/types.js";
+export function decodeAbandonRefusal(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new Error("malformed abandon refusal");
+    const object = value;
+    if (object.kind !== "contract-missing" && object.kind !== "terminal")
+        throw new Error("malformed abandon refusal");
+    if (Object.keys(object).some((key) => key !== "kind" && key !== "contractId"))
+        throw new Error("malformed abandon refusal");
+    try {
+        return { kind: object.kind, contractId: contractId(String(object.contractId)) };
+    }
+    catch {
+        throw new Error("malformed abandon refusal");
+    }
+}
 export function decideAbandon({ input, attempt, observation, }) {
     const id = input.contractId;
     const current = activeContract(observation, id);

package/build/src/core/verbs/amend.d.ts

@@ -1,5 +1,5 @@
 import type { DecideInput, OfferDecision, Preparation } from "../decide.js";
-import type { ActorId, AmendData, ContractId, ContractTerms } from "../facts/types.js";
+import { type ActorId, type AmendData, type ContractId, type ContractTerms } from "../facts/types.js";
 export type AmendInput<Failure = never> = Readonly<{
     contractId: ContractId;
     actor?: ActorId;
@@ -11,4 +11,5 @@ export type AmendRefusal = Readonly<{
     kind: "contract-missing" | "terminal" | "terms-moved" | "unknown-prerequisite" | "cyclic-prerequisite";
     contractId: ContractId;
 }>;
+export declare function decodeAmendRefusal(value: unknown): AmendRefusal;
 export declare function decideAmend<Failure>({ input, attempt, observation, }: DecideInput<AmendInput<Failure>>): OfferDecision<AmendRefusal | Failure>;

package/build/src/core/verbs/amend.js

@@ -1,5 +1,25 @@
 import { prerequisitesReach, samePrerequisites } from "../facts/eligibility.js";
 import { activeContract, prerequisiteStatus } from "../facts/observation.js";
+import { contractId, } from "../facts/types.js";
+export function decodeAmendRefusal(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new Error("malformed amend refusal");
+    const object = value;
+    if (object.kind !== "contract-missing" &&
+        object.kind !== "terminal" &&
+        object.kind !== "terms-moved" &&
+        object.kind !== "unknown-prerequisite" &&
+        object.kind !== "cyclic-prerequisite")
+        throw new Error("malformed amend refusal");
+    if (Object.keys(object).some((key) => key !== "kind" && key !== "contractId"))
+        throw new Error("malformed amend refusal");
+    try {
+        return { kind: object.kind, contractId: contractId(String(object.contractId)) };
+    }
+    catch {
+        throw new Error("malformed amend refusal");
+    }
+}
 export function decideAmend({ input, attempt, observation, }) {
     const id = input.contractId;
     const current = activeContract(observation, id);

package/build/src/core/verbs/arc.d.ts

@@ -1,5 +1,5 @@
 import type { DecideInput, OfferDecision } from "../decide.js";
-import type { ActorId, ArcData, ContractId } from "../facts/types.js";
+import { type ActorId, type ArcData, type ContractId } from "../facts/types.js";
 export type ArcInput = Readonly<{
     contractId: ContractId;
     actor?: ActorId;
@@ -10,4 +10,5 @@ export type ArcRefusal = Readonly<{
     kind: "contract-missing" | "terminal";
     contractId: ContractId;
 }>;
+export declare function decodeArcRefusal(value: unknown): ArcRefusal;
 export declare function decideArc({ input, attempt, observation }: DecideInput<ArcInput>): OfferDecision<ArcRefusal>;

package/build/src/core/verbs/arc.js

@@ -1,4 +1,20 @@
 import { activeContract } from "../facts/observation.js";
+import { contractId } from "../facts/types.js";
+export function decodeArcRefusal(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new Error("malformed arc refusal");
+    const object = value;
+    if (object.kind !== "contract-missing" && object.kind !== "terminal")
+        throw new Error("malformed arc refusal");
+    if (Object.keys(object).some((key) => key !== "kind" && key !== "contractId"))
+        throw new Error("malformed arc refusal");
+    try {
+        return { kind: object.kind, contractId: contractId(String(object.contractId)) };
+    }
+    catch {
+        throw new Error("malformed arc refusal");
+    }
+}
 export function decideArc({ input, attempt, observation }) {
     const id = input.contractId;
     const current = activeContract(observation, id);

package/build/src/core/verbs/attestation.d.ts

@@ -1,5 +1,5 @@
 import type { DecideInput, OfferDecision, Preparation } from "../decide.js";
-import type { ActorId, AttestationData, ContractId } from "../facts/types.js";
+import { type ActorId, type AttestationData, type ContractId } from "../facts/types.js";
 export type AttestationInput<Failure = never> = Readonly<{
     contractId: ContractId;
     actor?: ActorId;
@@ -10,4 +10,5 @@ export type AttestationRefusal = Readonly<{
     kind: "contract-missing" | "terminal";
     contractId: ContractId;
 }>;
+export declare function decodeAttestationRefusal(value: unknown): AttestationRefusal;
 export declare function decideAttestation<Failure>({ input, attempt, observation, }: DecideInput<AttestationInput<Failure>>): OfferDecision<AttestationRefusal | Failure>;

package/build/src/core/verbs/attestation.js

@@ -1,4 +1,20 @@
 import { activeContract } from "../facts/observation.js";
+import { contractId } from "../facts/types.js";
+export function decodeAttestationRefusal(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new Error("malformed attestation refusal");
+    const object = value;
+    if (object.kind !== "contract-missing" && object.kind !== "terminal")
+        throw new Error("malformed attestation refusal");
+    if (Object.keys(object).some((key) => key !== "kind" && key !== "contractId"))
+        throw new Error("malformed attestation refusal");
+    try {
+        return { kind: object.kind, contractId: contractId(String(object.contractId)) };
+    }
+    catch {
+        throw new Error("malformed attestation refusal");
+    }
+}
 export function decideAttestation({ input, attempt, observation, }) {
     const state = activeContract(observation, input.contractId);
     if ("kind" in state)

package/build/src/core/verbs/bind.d.ts

@@ -1,5 +1,5 @@
 import type { DecideInput, OfferDecision, Preparation } from "../decide.js";
-import type { ActorId, BindData, ContractId } from "../facts/types.js";
+import { type ActorId, type BindData, type ContractId } from "../facts/types.js";
 export type BindInput<Failure = never> = Readonly<{
     contractId: ContractId;
     actor?: ActorId;
@@ -10,4 +10,5 @@ export type BindRefusal = Readonly<{
     kind: "contract-exists" | "invalid-after" | "unknown-prerequisite";
     contractId: ContractId;
 }>;
+export declare function decodeBindRefusal(value: unknown): BindRefusal;
 export declare function decideBind<Failure>({ input, attempt, observation, }: DecideInput<BindInput<Failure>>): OfferDecision<BindRefusal | Failure>;

package/build/src/core/verbs/bind.js

@@ -1,4 +1,20 @@
 import { contractState, prerequisiteStatus } from "../facts/observation.js";
+import { contractId } from "../facts/types.js";
+export function decodeBindRefusal(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new Error("malformed bind refusal");
+    const object = value;
+    if (object.kind !== "contract-exists" && object.kind !== "invalid-after" && object.kind !== "unknown-prerequisite")
+        throw new Error("malformed bind refusal");
+    if (Object.keys(object).some((key) => key !== "kind" && key !== "contractId"))
+        throw new Error("malformed bind refusal");
+    try {
+        return { kind: object.kind, contractId: contractId(String(object.contractId)) };
+    }
+    catch {
+        throw new Error("malformed bind refusal");
+    }
+}
 export function decideBind({ input, attempt, observation, }) {
     const id = input.contractId;
     const current = contractState(observation, id);

package/build/src/core/verbs/deliver.d.ts

@@ -1,5 +1,5 @@
 import type { DecideInput, OfferDecision, StampedPreparation } from "../decide.js";
-import type { ActorId, ContractId, DeliverData } from "../facts/types.js";
+import { type ActorId, type ContractId, type DeliverData } from "../facts/types.js";
 export type DeliverInput<Failure = never> = Readonly<{
     contractId: ContractId;
     actor?: ActorId;
@@ -10,4 +10,5 @@ export type DeliverRefusal = Readonly<{
     kind: "contract-missing" | "terminal" | "document-moved";
     contractId: ContractId;
 }>;
+export declare function decodeDeliverRefusal(value: unknown): DeliverRefusal;
 export declare function decideDeliver<Failure>({ input, attempt, observation, }: DecideInput<DeliverInput<Failure>>): OfferDecision<DeliverRefusal | Failure>;

package/build/src/core/verbs/deliver.js

@@ -1,4 +1,20 @@
 import { activeContract, documentIsCurrent } from "../facts/observation.js";
+import { contractId } from "../facts/types.js";
+export function decodeDeliverRefusal(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new Error("malformed deliver refusal");
+    const object = value;
+    if (object.kind !== "contract-missing" && object.kind !== "terminal" && object.kind !== "document-moved")
+        throw new Error("malformed deliver refusal");
+    if (Object.keys(object).some((key) => key !== "kind" && key !== "contractId"))
+        throw new Error("malformed deliver refusal");
+    try {
+        return { kind: object.kind, contractId: contractId(String(object.contractId)) };
+    }
+    catch {
+        throw new Error("malformed deliver refusal");
+    }
+}
 export function decideDeliver({ input, attempt, observation, }) {
     const state = activeContract(observation, input.contractId);
     if ("kind" in state)

package/build/src/core/verbs/placement.d.ts

@@ -1,5 +1,5 @@
 import { type GateReport } from "../facts/gate.js";
-import type { ActorId, ContractId } from "../facts/types.js";
+import { type ActorId, type ContractId } from "../facts/types.js";
 import type { DecideInput, OfferDecision } from "../decide.js";
 type PlacementInput = Readonly<{
     contractId: ContractId;
@@ -22,5 +22,6 @@ export type PlacementRefusal = Readonly<{
     contractId: ContractId;
     unmet: readonly UnmetPrerequisite[];
 }>;
+export declare function decodePlacementRefusal(value: unknown): PlacementRefusal;
 export declare function decidePlacement({ input, attempt, observation, }: DecideInput<PlacementInput>): OfferDecision<PlacementRefusal>;
 export {};

package/build/src/core/verbs/placement.js

@@ -1,5 +1,62 @@
-import { gateReports } from "../facts/gate.js";
+import { decodeGateReport, gateReports } from "../facts/gate.js";
 import { activeContract, contractState } from "../facts/observation.js";
+import { contractId } from "../facts/types.js";
+export function decodePlacementRefusal(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new Error("malformed placement refusal");
+    const object = value;
+    if (object.kind === "contract-missing" || object.kind === "delivery-missing" || object.kind === "terminal") {
+        if (Object.keys(object).some((key) => key !== "kind" && key !== "contractId"))
+            throw new Error("malformed placement refusal");
+        try {
+            return { kind: object.kind, contractId: contractId(String(object.contractId)) };
+        }
+        catch {
+            throw new Error("malformed placement refusal");
+        }
+    }
+    if (object.kind === "gates-unsatisfied") {
+        if (Object.keys(object).some((key) => key !== "kind" && key !== "contractId" && key !== "unmet"))
+            throw new Error("malformed placement refusal");
+        if (!Array.isArray(object.unmet))
+            throw new Error("malformed placement refusal");
+        try {
+            return {
+                kind: "gates-unsatisfied",
+                contractId: contractId(String(object.contractId)),
+                unmet: object.unmet.map(decodeGateReport),
+            };
+        }
+        catch {
+            throw new Error("malformed placement refusal");
+        }
+    }
+    if (object.kind !== "prerequisites-unsatisfied")
+        throw new Error("malformed placement refusal");
+    if (Object.keys(object).some((key) => key !== "kind" && key !== "contractId" && key !== "unmet"))
+        throw new Error("malformed placement refusal");
+    if (!Array.isArray(object.unmet))
+        throw new Error("malformed placement refusal");
+    try {
+        return {
+            kind: "prerequisites-unsatisfied",
+            contractId: contractId(String(object.contractId)),
+            unmet: object.unmet.map((item) => {
+                if (item === null || typeof item !== "object" || Array.isArray(item))
+                    throw new Error("malformed placement refusal");
+                const unmet = item;
+                if (Object.keys(unmet).some((key) => key !== "contractId" && key !== "state"))
+                    throw new Error("malformed placement refusal");
+                if (unmet.state !== "missing" && unmet.state !== "active" && unmet.state !== "abandoned")
+                    throw new Error("malformed placement refusal");
+                return { contractId: contractId(String(unmet.contractId)), state: unmet.state };
+            }),
+        };
+    }
+    catch {
+        throw new Error("malformed placement refusal");
+    }
+}
 function unmetPrerequisites(prerequisites, observation) {
     const unmet = [];
     for (const contractId of prerequisites) {

package/build/src/dispatch/association.d.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+export declare const dispatchAssociationSchema: z.ZodUnion<readonly [z.ZodObject<{
+    kind: z.ZodLiteral<"none">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"associated">;
+    contractId: z.ZodPipe<z.ZodString, z.ZodTransform<import("../core/facts/types.js").ContractId, string>>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"failed">;
+    diagnostic: z.ZodString;
+}, z.core.$strict>]>;
+export type DispatchAssociation = z.infer<typeof dispatchAssociationSchema>;
+export declare const NO_DISPATCH_ASSOCIATION: DispatchAssociation;
+export declare function parseDispatchAssociation(value: unknown): DispatchAssociation;

package/build/src/dispatch/association.js

@@ -0,0 +1,20 @@
+import { contractId } from "../core/facts/types.js";
+import { z } from "zod";
+const contractIdSchema = z.string().transform((value, context) => {
+    try {
+        return contractId(value);
+    }
+    catch {
+        context.addIssue({ code: "custom", message: "expected ContractId" });
+        return z.NEVER;
+    }
+});
+export const dispatchAssociationSchema = z.union([
+    z.object({ kind: z.literal("none") }).strict(),
+    z.object({ kind: z.literal("associated"), contractId: contractIdSchema }).strict(),
+    z.object({ kind: z.literal("failed"), diagnostic: z.string() }).strict(),
+]);
+export const NO_DISPATCH_ASSOCIATION = { kind: "none" };
+export function parseDispatchAssociation(value) {
+    return dispatchAssociationSchema.parse(value);
+}

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

@@ -1,7 +1,9 @@
 import { type ContractId } from "../core/facts/types.js";
 import { type AkuId } from "../akuma/identity.js";
+import { type PrivateStateSeatCloseLag } from "../git/private-state-seat.js";
 import type { GitRepository } from "../git/process.js";
 import { type GitReadObservation } from "../git/read-observation.js";
+import { type DispatchAssociation } from "./association.js";
 export type Dispatch = Readonly<{
     akuId: AkuId;
     contractId: ContractId;
@@ -17,6 +19,7 @@ export type DispatchFailure = Readonly<{
 export type DispatchPublication = Readonly<{
     kind: "dispatched";
     dispatch: Dispatch;
+    seatClose?: readonly PrivateStateSeatCloseLag[];
 }> | Readonly<{
     kind: "failed";
     failure: DispatchFailure;
@@ -29,3 +32,6 @@ export declare function publishDispatch(input: Readonly<{
     akuId: AkuId;
     contractId: ContractId;
 }>): Promise<DispatchPublication>;
+export { dispatchAssociationSchema, NO_DISPATCH_ASSOCIATION, parseDispatchAssociation, type DispatchAssociation, } from "./association.js";
+/** Read-only Dispatch association projection for one Akuma identity. */
+export declare function observeDispatchAssociation(repository: GitRepository | undefined, akuId: AkuId): Promise<DispatchAssociation>;

package/build/src/dispatch/index.js

@@ -2,9 +2,10 @@ import { createHash } from "node:crypto";
 import { AuthorityCorruptionError } from "../core/facts/errors.js";
 import { contractId } from "../core/facts/types.js";
 import { parseAkuId } from "../akuma/identity.js";
-import { confirmPrivateStatePublication, withPrivateStatePublicationSeat } from "../git/private-state-seat.js";
+import { appendPrivateStateSeatClose, confirmPrivateStatePublication, mergePrivateStateSeatClose, withPrivateStatePublicationSeat, } from "../git/private-state-seat.js";
 import { GIT_FORMAT_BYTES, GIT_FORMAT_PATH, GIT_REF, readBlob, readGitPaths, updateGitTree, updateRefsAtomically, writeBlob, writeStateCommit, } from "../git/repository.js";
 import { withGitDecodeChannel, withGitReadObservation } from "../git/read-observation.js";
+import { NO_DISPATCH_ASSOCIATION } from "./association.js";
 const DISPATCH_ROOT = "dispatch";
 const DISPATCH_PREFIX = `${DISPATCH_ROOT}/`;
 const DISPATCH_SUFFIX = ".json";
@@ -118,12 +119,19 @@ async function observedPublication(repository, akuId, owner) {
 function diagnostic(error) {
     return error instanceof Error ? error.message : String(error);
 }
+function dispatchPublicationWithSeatClose(outcome) {
+    return mergePrivateStateSeatClose(outcome, (value, closeLag) => {
+        if (value.kind !== "dispatched")
+            throw new Error(closeLag.diagnostic);
+        return { ...value, seatClose: appendPrivateStateSeatClose(value.seatClose, closeLag) };
+    });
+}
 export async function publishDispatch(input) {
     const akuId = parseAkuId(input.akuId).id;
     const owner = contractId(input.contractId);
     const intended = { akuId, contractId: owner, dispatchedAt: new Date().toISOString() };
     const path = pathFor(akuId);
-    return await withPrivateStatePublicationSeat(input.repository, async (seat) => {
+    return dispatchPublicationWithSeatClose(await withPrivateStatePublicationSeat(input.repository, async (seat) => {
         const snapshot = await readGitPaths(input.repository, [path]);
         const current = await dispatchFromSnapshot(input.repository, snapshot, akuId);
         if (current !== null) {
@@ -176,5 +184,21 @@ export async function publishDispatch(input) {
             kind: "failed",
             failure: { kind: "publication-failed", diagnostic: "Dispatch publication outcome is unknown" },
         };
-    });
+    }));
+}
+export { dispatchAssociationSchema, NO_DISPATCH_ASSOCIATION, parseDispatchAssociation, } from "./association.js";
+function associationDiagnostic(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** Read-only Dispatch association projection for one Akuma identity. */
+export async function observeDispatchAssociation(repository, akuId) {
+    if (repository === undefined)
+        return NO_DISPATCH_ASSOCIATION;
+    try {
+        const dispatch = await readDispatch(repository, akuId);
+        return dispatch === null ? NO_DISPATCH_ASSOCIATION : { kind: "associated", contractId: dispatch.contractId };
+    }
+    catch (error) {
+        return { kind: "failed", diagnostic: associationDiagnostic(error) };
+    }
 }

package/build/src/git/hooks.d.ts

@@ -1,3 +1,4 @@
+import { type Settings } from "../settings.js";
 export type HookCommand = Readonly<{
     name: string;
     argv: readonly string[];
@@ -30,6 +31,13 @@ export type WorktreeHookLag = Readonly<{
     failure: HookFailure;
 }>;
 export type HookPhase = "create" | "destroy";
+export type WorktreeHooksFromInput = Readonly<{
+    settings: Settings;
+}>;
+export declare function worktreeHooksFrom(input: WorktreeHooksFromInput): WorktreeHooks;
+export declare function normalizedWorktreeHooks(value: unknown): WorktreeHooks;
+export declare const EMPTY_WORKTREE_HOOKS: WorktreeHooks;
+export declare function worktreeHooksOption(value: unknown): WorktreeHooks;
 export type HookCommandRun = Readonly<{
     kind: "ok";
 }> | Readonly<{
@@ -40,7 +48,7 @@ export type HookCommandRun = Readonly<{
     failure: HookFailure;
 }>;
 /** Execute an ordered command list without lifecycle state. Scratch owns this policy. */
-export declare function runHookCommands(worktree: string, commands: readonly HookCommand[], signal?: AbortSignal): Promise<HookCommandRun>;
+export declare function runHookCommands(worktree: string, commands: readonly HookCommand[], signal?: AbortSignal, environment?: NodeJS.ProcessEnv): Promise<HookCommandRun>;
 export type HookPhaseRun = Readonly<{
     lag: WorktreeHookLag | null;
     runs: readonly string[];

package/build/src/git/hooks.js

@@ -1,4 +1,81 @@
 import { runProcess } from "../runtime/proc/run.js";
+import { SettingsError } from "../settings.js";
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function namespaceFailure(view) {
+    if (view.kind !== "failed")
+        throw new Error("settings namespace failure expected");
+    throw new SettingsError(view.failures.map((failure) => `${failure.scope}: ${failure.diagnostic}`).join("; "));
+}
+function command(value, coordinate, ErrorType) {
+    if (!record(value))
+        throw new ErrorType(`${coordinate} must be an object`);
+    for (const key of Object.keys(value)) {
+        if (key !== "name" && key !== "argv" && key !== "timeoutMs")
+            throw new ErrorType(`${coordinate} has unknown field: ${key}`);
+    }
+    if (typeof value.name !== "string" || value.name.trim().length === 0)
+        throw new ErrorType(`${coordinate}.name must be nonblank`);
+    if (!Array.isArray(value.argv) || value.argv.length === 0 || !value.argv.every((item) => typeof item === "string")) {
+        throw new ErrorType(`${coordinate}.argv must be a nonempty string array`);
+    }
+    if (value.argv[0].trim().length === 0)
+        throw new ErrorType(`${coordinate}.argv[0] must be nonblank`);
+    if (!Number.isSafeInteger(value.timeoutMs) ||
+        value.timeoutMs < 1 ||
+        value.timeoutMs > 2_147_483_647) {
+        throw new ErrorType(`${coordinate}.timeoutMs must be an integer from 1 through 2147483647`);
+    }
+    return Object.freeze({
+        name: value.name.trim(),
+        argv: Object.freeze([...value.argv]),
+        timeoutMs: value.timeoutMs,
+    });
+}
+function commands(value, coordinate, ErrorType) {
+    if (!Array.isArray(value))
+        throw new ErrorType(`${coordinate} must be an array`);
+    return Object.freeze(value.map((item, index) => command(item, `${coordinate}[${index}]`, ErrorType)));
+}
+export function worktreeHooksFrom(input) {
+    if (!record(input))
+        throw new TypeError("worktreeHooksFrom input must be an object");
+    const view = input.settings.namespace("worktree");
+    if (view.kind === "failed")
+        namespaceFailure(view);
+    for (const entry of view.entries) {
+        if (entry.name !== "create" && entry.name !== "destroy") {
+            throw new SettingsError(`worktree has unknown entry: ${entry.name}`);
+        }
+    }
+    const selected = (phase) => {
+        const entry = view.entries.find((item) => item.name === phase);
+        if (entry === undefined)
+            return Object.freeze([]);
+        return commands(entry.value, `worktree.${phase}`, SettingsError);
+    };
+    return Object.freeze({ create: selected("create"), destroy: selected("destroy") });
+}
+export function normalizedWorktreeHooks(value) {
+    if (!record(value))
+        throw new TypeError("hooks must be an object");
+    for (const key of Object.keys(value)) {
+        if (key !== "create" && key !== "destroy")
+            throw new TypeError(`hooks has unknown field: ${key}`);
+    }
+    return Object.freeze({
+        create: commands(value.create, "hooks.create", TypeError),
+        destroy: commands(value.destroy, "hooks.destroy", TypeError),
+    });
+}
+export const EMPTY_WORKTREE_HOOKS = Object.freeze({
+    create: Object.freeze([]),
+    destroy: Object.freeze([]),
+});
+export function worktreeHooksOption(value) {
+    return value === undefined ? EMPTY_WORKTREE_HOOKS : normalizedWorktreeHooks(value);
+}
 function failedOutcome(outcome) {
     if (outcome.kind === "terminal") {
         return outcome.code === 0
@@ -14,13 +91,14 @@ function failedOutcome(outcome) {
     return outcome;
 }
 /** Execute an ordered command list without lifecycle state. Scratch owns this policy. */
-export async function runHookCommands(worktree, commands, signal) {
+export async function runHookCommands(worktree, commands, signal, environment) {
     for (const [command, value] of commands.entries()) {
         const outcome = await runProcess({
             argv: value.argv,
             timeoutMs: value.timeoutMs,
             cwd: worktree,
             ...(signal === undefined ? {} : { signal }),
+            ...(environment === undefined ? {} : { env: environment }),
         });
         if (outcome.kind === "cancelled")
             return outcome;

package/build/src/git/nuke.d.ts

@@ -1,3 +1,4 @@
 import type { WorldRoot } from "../world.js";
 import { type GitRepository } from "./process.js";
-export declare function nukeGit(world: WorldRoot, gitPath?: string, options?: Readonly<Pick<GitRepository, "onPrivateStateSeatContention">>): Promise<void>;
+import { type PrivateStateSeatOutcome } from "./private-state-seat.js";
+export declare function nukeGit(world: WorldRoot, gitPath?: string, options?: Readonly<Pick<GitRepository, "onPrivateStateSeatContention" | "onPrivateStateSeatClose">>): Promise<PrivateStateSeatOutcome<void>>;

package/build/src/git/nuke.js

@@ -2,8 +2,8 @@ import { access, lstat, realpath, rm } from "node:fs/promises";
 import { isAbsolute, relative, sep } from "node:path";
 import { nukeEmptyPlaceAuthority, readPlaceRegister, releaseManagedWorktrees, withPlaceAuthorityFence, } from "../workspace-place.js";
 import { GitPlumbingError, runGit } from "./process.js";
-import { confirmPrivateStatePublication, withPrivateStatePublicationSeat } from "./private-state-seat.js";
-import { CANDIDATE_PIN_REF_NAMESPACE, DELIVERY_REF_NAMESPACE, GIT_REF, LEGACY_CANDIDATE_PIN_REF_NAMESPACE, LEGACY_DELIVERY_REF_NAMESPACE, NoGitWorldError, readRef, registeredWorktrees, repositoryAt, worktreeGitDirectory, } from "./repository.js";
+import { confirmPrivateStatePublication, withPrivateStatePublicationSeat, } from "./private-state-seat.js";
+import { CANDIDATE_PIN_REF_NAMESPACE, DELIVERY_REF_NAMESPACE, GIT_REF, NoGitWorldError, readRef, registeredWorktrees, repositoryAt, worktreeGitDirectory, } from "./repository.js";
 import { worktreePath } from "./workspace.js";
 async function managedCustody(repository) {
     const register = await readPlaceRegister(repository);
@@ -117,12 +117,7 @@ async function deleteObservedStateRef(repository, expectedOid, seat) {
     throw new Error("state-ref deletion outcome is unknown");
 }
 async function removeOwnedRefs(repository) {
-    const roots = [
-        DELIVERY_REF_NAMESPACE,
-        CANDIDATE_PIN_REF_NAMESPACE,
-        LEGACY_DELIVERY_REF_NAMESPACE,
-        LEGACY_CANDIDATE_PIN_REF_NAMESPACE,
-    ];
+    const roots = [DELIVERY_REF_NAMESPACE, CANDIDATE_PIN_REF_NAMESPACE];
     for (const root of roots) {
         const refs = (await runGit(repository, ["for-each-ref", "--format=%(refname)", root]))
             .toString("utf8")
@@ -142,12 +137,12 @@ export async function nukeGit(world, gitPath = "git", options) {
     }
     catch (error) {
         if (error instanceof NoGitWorldError)
-            return;
+            return { value: undefined };
         throw error;
     }
-    await withPlaceAuthorityFence(repository, async (placeFence) => {
+    return await withPlaceAuthorityFence(repository, async (placeFence) => {
         const custody = await managedCustody(repository);
-        await withPrivateStatePublicationSeat(repository, async (seat) => {
+        return await withPrivateStatePublicationSeat(repository, async (seat) => {
             const state = await readRef(repository, GIT_REF);
             if (state !== null)
                 await deleteObservedStateRef(repository, state, seat);

package/build/src/git/private-state-seat.d.ts

@@ -1,12 +1,37 @@
 import type { GitRepository } from "./process.js";
 declare const privateStateSeat: unique symbol;
+/** Timed-out wait for the private-state publication seat. The holder and lock are unchanged. */
+export declare class GitPrivateStateSeatContentionError extends Error {
+    readonly reason: "timeout";
+    constructor(message: string, options?: ErrorOptions);
+}
 /** Proves an admission's private-root observation was made while the shared seat was held. */
 export type PrivateStatePublicationSeat = Readonly<{
     readonly [privateStateSeat]: true;
 }>;
+/** Post-confirmation failure to release the private-state publication seat. */
+export type PrivateStateSeatCloseLag = Readonly<{
+    kind: "private-state-seat-close-failed";
+    diagnostic: string;
+}>;
+/** Action result plus any confirmed-publication seat-close lag. */
+export type PrivateStateSeatOutcome<T> = Readonly<{
+    value: T;
+    closeLag?: PrivateStateSeatCloseLag;
+}>;
 /** Record a known or exact-read-back-proven private-root publication. */
 export declare function confirmPrivateStatePublication(seat: PrivateStatePublicationSeat): void;
 export declare function privateStatePublicationSeatPath(repository: GitRepository): string;
+export declare function privateStateSeatCloseLag(error: unknown): PrivateStateSeatCloseLag;
+export declare function concatenatePrivateStateSeatClose(current: readonly PrivateStateSeatCloseLag[] | undefined, next: readonly PrivateStateSeatCloseLag[] | undefined): readonly PrivateStateSeatCloseLag[] | undefined;
+export declare function appendPrivateStateSeatClose(current: readonly PrivateStateSeatCloseLag[] | undefined, closeLag: PrivateStateSeatCloseLag): readonly PrivateStateSeatCloseLag[];
+/** Unwrap a seat outcome that has no typed lag surface; confirmed close lag throws. */
+export declare function requireClosedPrivateStateSeat<T>(outcome: PrivateStateSeatOutcome<T>): T;
+/** Unwrap a seat outcome through an owner-typed merge of confirmed close lag. */
+export declare function mergePrivateStateSeatClose<T>(outcome: PrivateStateSeatOutcome<T>, merge: (value: T, closeLag: PrivateStateSeatCloseLag) => T): T;
+export declare function isPrivateStateSeatContention(error: unknown): error is GitPrivateStateSeatContentionError;
 /** Serialize cooperating writers of the one private Git state root. */
-export declare function withPrivateStatePublicationSeat<T>(repository: GitRepository, action: (seat: PrivateStatePublicationSeat) => T | Promise<T>): Promise<T>;
+export declare function withPrivateStatePublicationSeat<T>(repository: GitRepository, action: (seat: PrivateStatePublicationSeat) => T | Promise<T>, options?: Readonly<{
+    timeoutMs?: number;
+}>): Promise<PrivateStateSeatOutcome<T>>;
 export {};