@astrosheep/keiyaku 4.5.7 → 4.5.9

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

@@ -1,5 +1,5 @@
-import { spawn } from "node:child_process";
 import { AuthorityCorruptionError } from "../core/facts/errors.js";
+import { spawnCancellableProcess } from "../runtime/proc/run.js";
 import { gitObjectId } from "./identity.js";
 import { parseTreeObject, validPath } from "./tree.js";
 import { GIT_FORMAT_BYTES, GIT_FORMAT_PATH, GIT_REF, readRef } from "./repository.js";
@@ -36,11 +36,18 @@ function streamCursor(stream) {
     };
     return { line, exact };
 }
+async function batchObjects(oids, object) {
+    const unique = [...new Set(oids)];
+    for (const oid of unique)
+        gitObjectId(oid, "Git object");
+    const entries = await Promise.all(unique.map(async (oid) => [oid, await object(oid)]));
+    return new Map(entries);
+}
 function batchChild(repository) {
-    return spawn(repository.gitPath, ["cat-file", "--batch"], {
+    return spawnCancellableProcess({
+        argv: [repository.gitPath, "cat-file", "--batch"],
         cwd: repository.effectiveCwd,
-        stdio: ["pipe", "pipe", "pipe"],
-        windowsHide: true,
+        ...(repository.signal === undefined ? {} : { signal: repository.signal }),
     });
 }
 function batchError(child, stderr, message, status) {
@@ -51,8 +58,18 @@ function batchError(child, stderr, message, status) {
         pid: child.pid ?? null,
     });
 }
+async function closeBatchProcess(process, child, closed, spawnError, stderr) {
+    if (!child.stdin.destroyed)
+        child.stdin.end();
+    const outcome = await Promise.race([closed, process.terminationFailure]);
+    await process.waitTermination();
+    if (spawnError !== null || outcome.code !== 0) {
+        throw batchError(child, stderr, process.cancelled() ? "git process cancelled" : "git cat-file --batch did not close cleanly", outcome.code);
+    }
+}
 function batchObjectReader(repository) {
-    const child = batchChild(repository);
+    const process = batchChild(repository);
+    const child = process.child;
     const cursor = streamCursor(child.stdout);
     const cache = new Map();
     const stderr = [];
@@ -101,9 +118,10 @@ function batchObjectReader(repository) {
         catch (error) {
             if (failure !== null)
                 throw failure;
-            child.kill();
+            await process.terminate(true);
             await closed;
-            failure = batchError(child, stderr, error instanceof Error ? error.message : String(error), child.exitCode);
+            await process.waitTermination();
+            failure = batchError(child, stderr, process.cancelled() ? "git process cancelled" : error instanceof Error ? error.message : String(error), process.cancelled() ? null : child.exitCode);
             throw failure;
         }
     };
@@ -116,23 +134,14 @@ function batchObjectReader(repository) {
         cache.set(oid, requested);
         return requested;
     };
-    const objects = async (oids) => {
-        const unique = [...new Set(oids)];
-        for (const oid of unique)
-            gitObjectId(oid, "Git object");
-        const entries = await Promise.all(unique.map(async (oid) => [oid, await object(oid)]));
-        return new Map(entries);
-    };
+    const objects = (oids) => batchObjects(oids, object);
     const close = async () => {
         await tail.catch(() => undefined);
-        if (failure !== null)
+        if (failure !== null) {
+            await process.waitTermination();
             return;
-        if (!child.stdin.destroyed)
-            child.stdin.end();
-        const outcome = await closed;
-        if (spawnError !== null || outcome.code !== 0) {
-            throw batchError(child, stderr, "git cat-file --batch did not close cleanly", outcome.code);
         }
+        await closeBatchProcess(process, child, closed, spawnError, stderr);
     };
     return { objects, close };
 }

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

@@ -4,6 +4,7 @@ import type { ContractId, ContractState, SnapshotId } from "../core/facts/types.
 import type { GitDecodeChannel } from "./read-observation.js";
 import { type TargetCheckoutEffect, type TargetCheckoutLag } from "./target-placement.js";
 import { type WorktreeHookLag, type WorktreeHooks } from "./hooks.js";
+import { type RefMigrationConflict } from "./ref-migration.js";
 import type { UnsealedBytes } from "./terminal-seal.js";
 export type Effect = Readonly<{
     kind: "worktree";
@@ -46,16 +47,21 @@ type WorktreeFollowRetained = Readonly<{
     tender: SnapshotId;
     head: SnapshotId;
     reason: "head-moved" | "head-attached" | "operation-in-progress" | "unsupported-parent-shape";
+    paths?: readonly string[];
 }>;
 export type ReconcileFailure = Readonly<{
     kind: "reconcile-failed";
     stage: "observation" | "effect";
     diagnostic: string;
 }>;
-export type ReconcileLag = WorktreeRetained | WorktreeFollowRetained | UnsealedBytes | TargetCheckoutLag | WorktreeHookLag | ReconcileFailure;
+export type ReconcileLag = WorktreeRetained | WorktreeFollowRetained | UnsealedBytes | TargetCheckoutLag | WorktreeHookLag | RefMigrationConflict | ReconcileFailure;
 export type ReconcileResult = Readonly<{
     effects: readonly Effect[];
     lag: readonly ReconcileLag[];
+    hookRuns?: readonly {
+        phase: "create" | "destroy";
+        name: string;
+    }[];
 }>;
 type ReconcileBatchItem = Readonly<{
     contract: ContractId;
@@ -72,8 +78,14 @@ export type WorktreeTopology = Readonly<{
 export type ReconcileAccumulation = Readonly<{
     effects: Effect[];
     lag: ReconcileLag[];
+    hookRuns: {
+        phase: "create" | "destroy";
+        name: string;
+    }[];
 }>;
 export declare function reconcile(input: ReconcileInput): Promise<GitReconcileObservation>;
+/** Reconcile one retained dependent worktree under its normal per-Contract lock. */
+export declare function reconcileDependentWorktree(repository: GitRepository, contractId: ContractId, path: string, target: SnapshotId): Promise<ReconcileResult>;
 export declare function reconcileObservationFailure(error: unknown): ReconcileResult;
 export declare function reconcileEffectFailure(error: unknown, prior?: ReconcileResult): ReconcileResult;
 type ReconcileBatchOptions = Readonly<{

package/build/src/git/reconcile.js

@@ -2,14 +2,15 @@ import { access, mkdir } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { acquireSqliteTransactionLock, } from "../coordination/sqlite-transaction-lock.js";
 import { AuthorityCorruptionError } from "../core/facts/errors.js";
-import { CANDIDATE_PIN_REF_NAMESPACE, commonGitDirectory, DELIVERY_REF_NAMESPACE, registeredWorktreePaths, worktreeGitDirectory, } from "./repository.js";
+import { CANDIDATE_PIN_REF_NAMESPACE, commonGitDirectory, DELIVERY_REF_NAMESPACE, registeredWorktreePaths, } from "./repository.js";
 import { runGit } from "./process.js";
 import { contractLocator, contractPhysicalName, gitObjectIdForSnapshot } from "./identity.js";
 import { observeContractAt } from "./observe.js";
 import { acquireTargetPlacementFence, recoverTargetPlacement, } from "./target-placement.js";
 import { runCreateHooks } from "./hooks.js";
-import { followManagedWorktree, worktreePath } from "./workspace.js";
+import { followDependentManagedWorktree, followManagedWorktree, worktreePath } from "./workspace.js";
 import { removeCollectableScratchWorktrees } from "./scratch.js";
+import { migrateContractCustodyRefs } from "./ref-migration.js";
 import { reconcileTerminalManagedWorktree, removeRef, updateRef } from "./terminal-reconcile.js";
 const pathExists = (path) => access(path).then(() => true, () => false);
 function deliveryRefFor(contract) {
@@ -31,8 +32,8 @@ async function acquireWorktreeTopology(repository) {
 function diagnostic(error) {
     return error instanceof Error ? error.message : String(error);
 }
-function complete(effects = [], lag = []) {
-    return { effects, lag };
+function complete(effects = [], lag = [], hookRuns = []) {
+    return hookRuns.length === 0 ? { effects, lag } : { effects, lag, hookRuns };
 }
 function failed(stage, error, effects = [], lag = []) {
     if (error instanceof AuthorityCorruptionError || error instanceof TypeError)
@@ -103,7 +104,7 @@ async function reconcileTargetCheckouts(repository, state) {
         result = failed("effect", releaseFailure, result.effects, result.lag);
     return result;
 }
-async function reconcileActiveManagedWorktree({ repository, hooks, retryHooks, place }, state, topology, { effects, lag }) {
+async function reconcileActiveManagedWorktree({ repository, hooks, retryHooks, place }, state, topology, { effects, lag, hookRuns }) {
     if (place === undefined)
         return complete(effects, [...lag, missingPlaceLag(repository)]);
     const path = worktreePath(repository, place);
@@ -131,29 +132,39 @@ async function reconcileActiveManagedWorktree({ repository, hooks, retryHooks, p
     else {
         effects.push(projection);
     }
-    const hookLag = await runCreateHooks(path, await worktreeGitDirectory(repository, path), hooks, retryHooks);
-    if (hookLag !== null)
-        lag.push(hookLag);
+    if (projection.action === "created" || retryHooks) {
+        const hookRun = await runCreateHooks(path, hooks);
+        hookRuns.push(...hookRun.runs.map((name) => ({ phase: "create", name })));
+        if (hookRun.lag !== null)
+            lag.push(hookRun.lag);
+    }
     effects.push(await (state.delivery
         ? await updateRef(repository, candidatePinRefFor(state.id), state.currentIntegration?.snapshot ?? state.delivery.data.integration.snapshot)
         : await removeRef(repository, candidatePinRefFor(state.id))));
-    return complete(effects, lag);
+    return complete(effects, lag, hookRuns);
 }
 async function reconcileWithTopology(input, state, topology) {
     const { repository } = input;
     const effects = [];
     const lag = [];
+    const hookRuns = [];
     try {
         await removeCollectableScratch(repository, topology, effects, lag);
         if (!state)
             return complete(effects, lag);
+        const migration = await migrateContractCustodyRefs(repository, state.id);
+        effects.push(...migration.effects);
+        lag.push(...migration.lag);
+        if (migration.lag.length > 0)
+            return complete(effects, lag);
         const targetCheckouts = await reconcileTargetCheckouts(repository, state);
         effects.push(...targetCheckouts.effects);
         lag.push(...targetCheckouts.lag);
         if (state.terminal) {
-            return await reconcileTerminalManagedWorktree(input, state, topology, { effects, lag }, { ref: deliveryRefFor(state.id), pin: candidatePinRefFor(state.id) });
+            return await reconcileTerminalManagedWorktree(input, state, topology, { effects, lag, hookRuns }, { ref: deliveryRefFor(state.id), pin: candidatePinRefFor(state.id) });
         }
-        return await reconcileActiveManagedWorktree(input, state, topology, { effects, lag });
+        const result = await reconcileActiveManagedWorktree(input, state, topology, { effects, lag, hookRuns });
+        return hookRuns.length === 0 ? result : { ...result, hookRuns };
     }
     catch (error) {
         return failed("effect", error, effects, lag);
@@ -206,6 +217,54 @@ export async function reconcile(input) {
         throw new Error("reconcile produced no observation");
     return observation;
 }
+/** Reconcile one retained dependent worktree under its normal per-Contract lock. */
+export async function reconcileDependentWorktree(repository, contractId, path, target) {
+    let held;
+    try {
+        held = await acquireSqliteTransactionLock({ path: reconcileLockPath(repository, contractId), mode: "immediate" });
+    }
+    catch (error) {
+        return failed("effect", error);
+    }
+    let result;
+    try {
+        const follow = await followDependentManagedWorktree(repository, path, target);
+        if (follow.kind === "followed") {
+            result = {
+                effects: [{ kind: "worktree", path, action: "followed", before: follow.before, after: follow.after }],
+                lag: [],
+            };
+        }
+        else if (follow.kind === "unchanged") {
+            result = { effects: [], lag: [] };
+        }
+        else {
+            result = {
+                effects: [{ kind: "worktree", path, action: "unchanged" }],
+                lag: [
+                    {
+                        kind: "worktree-follow-retained",
+                        path,
+                        tender: target,
+                        head: follow.head,
+                        reason: follow.reason,
+                        ...(follow.paths.length === 0 ? {} : { paths: follow.paths }),
+                    },
+                ],
+            };
+        }
+    }
+    catch (error) {
+        result = failed("effect", error, [{ kind: "worktree", path, action: "unchanged" }]);
+    }
+    try {
+        held.close();
+    }
+    catch (error) {
+        result = failed("effect", error, result.effects, result.lag);
+    }
+    return result;
+}
 export function reconcileObservationFailure(error) {
     return failed("observation", error);
 }

package/build/src/git/ref-migration.d.ts

@@ -0,0 +1,22 @@
+import type { ContractId } from "../core/facts/types.js";
+import { type GitRepository } from "./process.js";
+import { type GitOid } from "./repository.js";
+export type RefMigrationEffect = Readonly<{
+    kind: "ref";
+    name: string;
+    before: GitOid | null;
+    after: GitOid | null;
+    action: "created" | "removed";
+}>;
+export type RefMigrationConflict = Readonly<{
+    kind: "ref-migration-conflict";
+    legacyRef: string;
+    legacyOid: GitOid;
+    currentRef: string;
+    currentOid: GitOid;
+}>;
+export type RefMigrationResult = Readonly<{
+    effects: readonly RefMigrationEffect[];
+    lag: readonly RefMigrationConflict[];
+}>;
+export declare function migrateContractCustodyRefs(repository: GitRepository, contract: ContractId): Promise<RefMigrationResult>;

package/build/src/git/ref-migration.js

@@ -0,0 +1,55 @@
+import { contractPhysicalName } from "./identity.js";
+import { runGit } from "./process.js";
+import { CANDIDATE_PIN_REF_NAMESPACE, DELIVERY_REF_NAMESPACE, LEGACY_CANDIDATE_PIN_REF_NAMESPACE, LEGACY_DELIVERY_REF_NAMESPACE, readRef, } from "./repository.js";
+export async function migrateContractCustodyRefs(repository, contract) {
+    const leaf = contractPhysicalName(contract);
+    const pairs = [
+        {
+            legacy: `${LEGACY_DELIVERY_REF_NAMESPACE}/${leaf}`,
+            current: `${DELIVERY_REF_NAMESPACE}/${leaf}`,
+        },
+        {
+            legacy: `${LEGACY_CANDIDATE_PIN_REF_NAMESPACE}/${leaf}`,
+            current: `${CANDIDATE_PIN_REF_NAMESPACE}/${leaf}`,
+        },
+    ];
+    const observed = await Promise.all(pairs.map(async (pair) => {
+        const [legacyOid, currentOid] = await Promise.all([
+            readRef(repository, pair.legacy),
+            readRef(repository, pair.current),
+        ]);
+        return { ...pair, legacyOid, currentOid };
+    }));
+    const lag = observed.flatMap((pair) => pair.legacyOid !== null && pair.currentOid !== null && pair.currentOid !== pair.legacyOid
+        ? [
+            {
+                kind: "ref-migration-conflict",
+                legacyRef: pair.legacy,
+                legacyOid: pair.legacyOid,
+                currentRef: pair.current,
+                currentOid: pair.currentOid,
+            },
+        ]
+        : []);
+    if (lag.length > 0)
+        return { effects: [], lag };
+    const migrating = observed.filter((pair) => pair.legacyOid !== null);
+    if (migrating.length === 0)
+        return { effects: [], lag: [] };
+    const lines = ["start"];
+    const effects = [];
+    for (const pair of migrating) {
+        if (pair.currentOid === null) {
+            lines.push(`create ${pair.current} ${pair.legacyOid}`);
+            effects.push({ kind: "ref", name: pair.current, before: null, after: pair.legacyOid, action: "created" });
+        }
+        else {
+            lines.push(`verify ${pair.current} ${pair.currentOid}`);
+        }
+        lines.push(`delete ${pair.legacy} ${pair.legacyOid}`);
+        effects.push({ kind: "ref", name: pair.legacy, before: pair.legacyOid, after: null, action: "removed" });
+    }
+    lines.push("prepare", "commit", "");
+    await runGit(repository, ["update-ref", "--stdin", "--no-deref"], lines.join("\n"));
+    return { effects, lag: [] };
+}

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

@@ -2,12 +2,13 @@ import { type GitRepository } from "./process.js";
 import { type TreeChange, type TreeEntry } from "./tree.js";
 export type { TreeChange } from "./tree.js";
 export declare const GIT_REF = "refs/heads/keiyaku-state";
-export declare const DELIVERY_REF_NAMESPACE = "refs/heads/keiyaku-delivery";
-export declare const CANDIDATE_PIN_REF_NAMESPACE = "refs/heads/keiyaku-candidate";
-export declare const MIGRATION_DELIVERY_REF_NAMESPACE = "refs/keiyaku/delivery";
-export declare const MIGRATION_CANDIDATE_PIN_REF_NAMESPACE = "refs/keiyaku/candidate";
+export declare const DELIVERY_REF_NAMESPACE = "refs/keiyaku/delivery";
+export declare const CANDIDATE_PIN_REF_NAMESPACE = "refs/keiyaku/candidate";
+export declare const LEGACY_DELIVERY_REF_NAMESPACE = "refs/heads/keiyaku-delivery";
+export declare const LEGACY_CANDIDATE_PIN_REF_NAMESPACE = "refs/heads/keiyaku-candidate";
 export declare const GIT_FORMAT_PATH = "meta/format.json";
 export declare const GIT_FORMAT_BYTES = "{\"version\":4}\n";
+export declare const STATE_COMMIT_SUBJECT = "keiyaku authority - do not delete or rewrite";
 export declare function isKeiyakuOwnedRef(ref: string): boolean;
 export type GitOid = string;
 export type RefPublication = Readonly<{
@@ -54,14 +55,17 @@ export declare function readBlob(repository: GitRepository, oid: GitOid): Promis
 export declare function updateGitTree(repository: GitRepository, baseTree: GitOid | null, changes: ReadonlyMap<string, TreeChange>): Promise<GitOid>;
 /** Write a tree update from directory entries frozen with the admitted base tree. */
 export declare function updateGitTreeFromFrozenDirectories(repository: GitRepository, baseTree: GitOid | null, directories: ReadonlyMap<string, ReadonlyMap<string, TreeEntry>>, changes: ReadonlyMap<string, TreeChange>): Promise<GitOid>;
-export declare function writeCommit(input: Readonly<{
+type WriteCommitInput = Readonly<{
     repository: GitRepository;
     tree: GitOid;
     parent: GitOid | null;
     message?: string;
     actor?: string;
     at?: string;
-}>): Promise<GitOid>;
+}>;
+export declare function writeCommit(input: WriteCommitInput): Promise<GitOid>;
+/** Write a commit that will become the canonical keiyaku-state tip. */
+export declare function writeStateCommit(input: WriteCommitInput): Promise<GitOid>;
 export declare function updateRefsAtomically(repository: GitRepository, updates: readonly ({
     readonly ref: typeof GIT_REF;
     readonly newOid: GitOid;

package/build/src/git/repository.js

@@ -1,26 +1,28 @@
+/* eslint-disable max-lines */
 import { isAbsolute, resolve } from "node:path";
 import { AuthorityCorruptionError } from "../core/facts/errors.js";
 import { gitObjectId } from "./identity.js";
 import { GitPlumbingError, runGit, runGitWithEnvironment } from "./process.js";
 import { parseTreeObject, prepareTreeUpdate, treeUpdate, validPath, } from "./tree.js";
 export const GIT_REF = "refs/heads/keiyaku-state";
-export const DELIVERY_REF_NAMESPACE = "refs/heads/keiyaku-delivery";
-export const CANDIDATE_PIN_REF_NAMESPACE = "refs/heads/keiyaku-candidate";
-export const MIGRATION_DELIVERY_REF_NAMESPACE = "refs/keiyaku/delivery";
-export const MIGRATION_CANDIDATE_PIN_REF_NAMESPACE = "refs/keiyaku/candidate";
+export const DELIVERY_REF_NAMESPACE = "refs/keiyaku/delivery";
+export const CANDIDATE_PIN_REF_NAMESPACE = "refs/keiyaku/candidate";
+export const LEGACY_DELIVERY_REF_NAMESPACE = "refs/heads/keiyaku-delivery";
+export const LEGACY_CANDIDATE_PIN_REF_NAMESPACE = "refs/heads/keiyaku-candidate";
 export const GIT_FORMAT_PATH = "meta/format.json";
 const CURRENT_FORMAT_VERSION = 4;
 export const GIT_FORMAT_BYTES = `{"version":${CURRENT_FORMAT_VERSION}}\n`;
+export const STATE_COMMIT_SUBJECT = "keiyaku authority - do not delete or rewrite";
 export function isKeiyakuOwnedRef(ref) {
     return (ref === GIT_REF ||
         ref === DELIVERY_REF_NAMESPACE ||
         ref.startsWith(`${DELIVERY_REF_NAMESPACE}/`) ||
         ref === CANDIDATE_PIN_REF_NAMESPACE ||
         ref.startsWith(`${CANDIDATE_PIN_REF_NAMESPACE}/`) ||
-        ref === MIGRATION_DELIVERY_REF_NAMESPACE ||
-        ref.startsWith(`${MIGRATION_DELIVERY_REF_NAMESPACE}/`) ||
-        ref === MIGRATION_CANDIDATE_PIN_REF_NAMESPACE ||
-        ref.startsWith(`${MIGRATION_CANDIDATE_PIN_REF_NAMESPACE}/`));
+        ref === LEGACY_DELIVERY_REF_NAMESPACE ||
+        ref.startsWith(`${LEGACY_DELIVERY_REF_NAMESPACE}/`) ||
+        ref === LEGACY_CANDIDATE_PIN_REF_NAMESPACE ||
+        ref.startsWith(`${LEGACY_CANDIDATE_PIN_REF_NAMESPACE}/`));
 }
 export class NoGitWorldError extends Error {
     path;
@@ -380,6 +382,12 @@ export async function writeCommit(input) {
         ...(input.at === undefined ? {} : { at: input.at }),
     });
 }
+/** Write a commit that will become the canonical keiyaku-state tip. */
+export async function writeStateCommit(input) {
+    const detail = input.message;
+    const message = detail === undefined || detail.length === 0 ? STATE_COMMIT_SUBJECT : `${STATE_COMMIT_SUBJECT}\n\n${detail}`;
+    return await writeCommit({ ...input, message });
+}
 function refAssertionLine(assertion) {
     assertAssertionRef(assertion.ref);
     gitObjectId(assertion.oid, `expected oid for ${assertion.ref}`);

package/build/src/git/target-placement.d.ts

@@ -43,6 +43,7 @@ export type TargetPlacementPreparation = Readonly<{
     refusal: TargetPlacementRefusal;
 }>;
 export declare function observeTargetHead(repository: GitRepository, target: string): Promise<SnapshotId | null>;
+export declare function observedTreeEqualsCandidate(repository: GitRepository, observed: SnapshotId | null, candidate: SnapshotId): Promise<boolean>;
 export declare function acquireTargetPlacementFence(repository: GitRepository, target: string): Promise<HeldSqliteTransactionLock>;
 export type TargetedContractCoordinates = ContractState["coordinates"] & Readonly<{
     target: string;

package/build/src/git/target-placement.js

@@ -27,6 +27,11 @@ function literalPath(path) {
 async function commitTree(repository, snapshot) {
     return gitObjectId((await runGit(repository, ["show", "-s", "--format=%T", gitObjectIdForSnapshot(snapshot)])).toString("utf8").trim(), "commit tree");
 }
+export async function observedTreeEqualsCandidate(repository, observed, candidate) {
+    if (observed === null)
+        return false;
+    return (await commitTree(repository, observed)) === (await commitTree(repository, candidate));
+}
 function checkoutRefusal(contractId, target, path, reason, paths) {
     return { kind: "checkout-not-followable", contractId, target: target.target, path, reason, paths };
 }

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

@@ -9,6 +9,7 @@ export type TenderCaptureCoordinates = Readonly<{
     place?: string;
     workspacePath?: string;
     captureMergeState?: boolean;
+    /** Opt-in real-index UU refusal. Omit or false when authorized capture must read current worktree bytes. */
     rejectUnmerged?: boolean;
 }>;
 export type WorktreeMissingRefusal = Readonly<{

package/build/src/git/terminal-reconcile.d.ts

@@ -17,5 +17,5 @@ type TerminalCustodyRefs = Readonly<{
 }>;
 export declare function updateRef(repository: GitRepository, ref: string, desired: SnapshotId): Promise<Effect>;
 export declare function removeRef(repository: GitRepository, ref: string): Promise<Effect>;
-export declare function reconcileTerminalManagedWorktree({ repository, channel, hooks, retryHooks, retainTerminalWorktree, place }: TerminalReconcileInput, state: ContractState, topology: WorktreeTopology, acc: ReconcileAccumulation, { ref, pin }: TerminalCustodyRefs): Promise<ReconcileResult>;
+export declare function reconcileTerminalManagedWorktree({ repository, channel, hooks, retainTerminalWorktree, place }: TerminalReconcileInput, state: ContractState, topology: WorktreeTopology, acc: ReconcileAccumulation, { ref, pin }: TerminalCustodyRefs): Promise<ReconcileResult>;
 export {};

package/build/src/git/terminal-reconcile.js

@@ -1,5 +1,5 @@
 import { access } from "node:fs/promises";
-import { isKeiyakuOwnedRef, readRef, writeCommit, worktreeGitDirectory } from "./repository.js";
+import { isKeiyakuOwnedRef, readRef, writeCommit } from "./repository.js";
 import { gitObjectIdForSnapshot, mintSnapshotId } from "./identity.js";
 import { runDestroyHooks } from "./hooks.js";
 import { terminalSealExpectations as decodeTerminalSealExpectations, terminalSealSnapshots, observeTerminalWorkspace, } from "./terminal-seal.js";
@@ -9,10 +9,7 @@ const pathExists = (path) => access(path).then(() => true, () => false);
 async function removeTerminalWorktree(repository, topology, path) {
     const registered = topology.paths.has(path);
     if (!registered) {
-        return {
-            effect: { kind: "worktree", path, action: "unchanged" },
-            retained: await pathExists(path),
-        };
+        return { retained: await pathExists(path) };
     }
     if (!(await pathExists(path))) {
         await runGit(repository, ["worktree", "remove", path]);
@@ -105,20 +102,20 @@ async function snapshotCustodian(repository, snapshot) {
 function fromPrimaryWorktree(repository) {
     return { ...repository, effectiveCwd: repository.primaryWorktree };
 }
-function complete(effects = [], lag = []) {
-    return { effects, lag };
+function complete(effects = [], lag = [], hookRuns = []) {
+    return hookRuns.length === 0 ? { effects, lag } : { effects, lag, hookRuns };
 }
-function retainTerminalWorktree(path, retainedLag, { effects, lag }) {
+function retainTerminalWorktree(path, retainedLag, { effects, lag, hookRuns }) {
     effects.push({ kind: "worktree", path, action: "unchanged" });
     lag.push(retainedLag);
-    return complete(effects, lag);
+    return complete(effects, lag, hookRuns);
 }
 async function terminalSealExpectations(channel, state) {
     const snapshots = terminalSealSnapshots(state);
     const objects = await channel.readObjects(snapshots.map(gitObjectIdForSnapshot));
     return decodeTerminalSealExpectations(state, objects);
 }
-async function removeSealedTerminalWorktree({ repository, topology, path, state, expected, hooks, retryHooks, acc, }) {
+async function removeSealedTerminalWorktree({ repository, topology, path, state, expected, hooks, acc, }) {
     if (topology.paths.has(path) && (await pathExists(path))) {
         const terminal = state.terminal;
         if (terminal === null)
@@ -156,9 +153,10 @@ async function removeSealedTerminalWorktree({ repository, topology, path, state,
             }
             recovery = await recordRecovery(beforeWorkspace);
         }
-        const hookLag = await runDestroyHooks(path, await worktreeGitDirectory(repository, path), hooks, retryHooks);
-        if (hookLag !== null)
-            return retainTerminalWorktree(path, hookLag, acc);
+        const hookRun = await runDestroyHooks(path, hooks);
+        acc.hookRuns.push(...hookRun.runs.map((name) => ({ phase: "destroy", name })));
+        if (hookRun.lag !== null)
+            return retainTerminalWorktree(path, hookRun.lag, acc);
         const after = await observeTerminalWorkspace(repository, path, expected);
         const afterWorkspace = after.workspace;
         const afterHooks = after.unsealed;
@@ -180,7 +178,8 @@ async function removeSealedTerminalWorktree({ repository, topology, path, state,
     const removal = await removeTerminalWorktree(repository, topology, path);
     if (removal.retained)
         return retainTerminalWorktree(path, { kind: "worktree-retained", path }, acc);
-    acc.effects.push(removal.effect);
+    if (removal.effect !== undefined)
+        acc.effects.push(removal.effect);
     return null;
 }
 async function targetCustodyForClaimedIntegration(repository, state, integration) {
@@ -244,23 +243,27 @@ async function releaseTerminalCustody({ repository, state, resolveSeal, ref, pin
         }
     }
 }
-export async function reconcileTerminalManagedWorktree({ repository, channel, hooks, retryHooks, retainTerminalWorktree, place }, state, topology, acc, { ref, pin }) {
+export async function reconcileTerminalManagedWorktree({ repository, channel, hooks, retainTerminalWorktree, place }, state, topology, acc, { ref, pin }) {
     const primary = fromPrimaryWorktree(repository);
     const path = place === undefined ? undefined : worktreePath(repository, place);
     const resolveSeal = async () => await terminalSealExpectations(channel, state);
     if (path === undefined) {
         if (retainTerminalWorktree === true)
-            return complete(acc.effects, acc.lag);
+            return complete(acc.effects, acc.lag, acc.hookRuns);
         await releaseTerminalCustody({ repository: primary, state, resolveSeal, ref, pin, acc });
-        return complete(acc.effects, acc.lag);
+        return complete(acc.effects, acc.lag, acc.hookRuns);
     }
     const expected = await resolveSeal();
     acc.effects.push(await updateRef(primary, ref, state.delivery?.data.tenderSnapshot ?? state.coordinates.start));
     if (state.delivery !== null) {
         acc.effects.push(await updateRef(primary, pin, state.currentIntegration?.snapshot ?? state.delivery.data.integration.snapshot));
     }
-    if (retainTerminalWorktree === true)
+    if (retainTerminalWorktree === true) {
+        if (topology.paths.has(path) && (await pathExists(path))) {
+            acc.effects.push({ kind: "worktree", path, action: "unchanged" });
+        }
         return complete(acc.effects, acc.lag);
+    }
     const retained = await removeSealedTerminalWorktree({
         repository: primary,
         topology,
@@ -268,11 +271,10 @@ export async function reconcileTerminalManagedWorktree({ repository, channel, ho
         state,
         expected,
         hooks,
-        retryHooks,
         acc,
     });
     if (retained !== null)
         return retained;
     await releaseTerminalCustody({ repository: primary, state, resolveSeal: async () => expected, ref, pin, acc });
-    return complete(acc.effects, acc.lag);
+    return complete(acc.effects, acc.lag, acc.hookRuns);
 }

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

@@ -26,8 +26,22 @@ export type ManagedWorktreeFollow = Readonly<{
     head: SnapshotId;
     reason: "head-moved" | "head-attached" | "operation-in-progress" | "unsupported-parent-shape";
 }>;
+export type DependentWorktreeFollow = Readonly<{
+    kind: "followed";
+    before: SnapshotId;
+    after: SnapshotId;
+}> | Readonly<{
+    kind: "unchanged";
+}> | Readonly<{
+    kind: "retained";
+    head: SnapshotId;
+    reason: "head-moved" | "head-attached" | "operation-in-progress";
+    paths: readonly string[];
+}>;
 /** Follow an accepted tender only through the native index-and-HEAD transition. */
 export declare function followManagedWorktree(repository: GitRepository, workspace: string, tender: SnapshotId): Promise<ManagedWorktreeFollow>;
+/** Follow a dependency baseline only through a clean, detached fast-forward. */
+export declare function followDependentManagedWorktree(repository: GitRepository, workspace: string, target: SnapshotId): Promise<DependentWorktreeFollow>;
 export declare function withPrivateGitIndex<Value>(action: (environment: Readonly<{
     GIT_INDEX_FILE: string;
 }>) => Value | PromiseLike<Value>): Promise<Value>;