@astrosheep/keiyaku 2.9.2 → 2.9.4

package/build/core/projection/projection-wait.js

@@ -0,0 +1,278 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { foldPublicProjectionActivity } from "./projection-activity.js";
+import { readGenerationEvents, isProjectionId, projectionRoot, } from "./projection-core.js";
+import { readProjectionIdentity } from "./projection-identity.js";
+import { RESPONSE_ARTIFACT_ID_RE } from "../response-artifact-id.js";
+import { PROJECTION_ADOPTION_TIMEOUT_MS } from "./generation/projection-generation-launcher.js";
+import { observeProjectionLifeSnapshot } from "./projection-life-observer.js";
+import { selectCurrentGeneration } from "./projection-life-protocol.js";
+import { readProjectionTellCounts } from "./tell/store.js";
+import { projectTerminalFailure, } from "./projection-terminal-failure.js";
+import { invalidActivityEventDiagnostic, selectValidStoredAgentEvents, } from "../stored-agent-event.js";
+/** Return the commission-bound projection IDs visible at one admission instant. */
+export async function snapshotCommissionProjectionIds(cwd, commissionId) {
+    const root = await projectionRoot(cwd);
+    let akumas;
+    try {
+        akumas = fs.readdirSync(root).sort();
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    const ids = [];
+    for (const akuma of akumas) {
+        if (akuma.startsWith("."))
+            continue;
+        const akumaDirectory = path.join(root, akuma);
+        try {
+            if (!fs.lstatSync(akumaDirectory).isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        let projections;
+        try {
+            projections = fs.readdirSync(akumaDirectory).sort();
+        }
+        catch {
+            continue;
+        }
+        for (const hex of projections) {
+            const id = `${akuma}/${hex}`;
+            if (!isProjectionId(id))
+                continue;
+            const directory = path.join(akumaDirectory, hex);
+            try {
+                if (!fs.lstatSync(directory).isDirectory())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            let pact;
+            try {
+                pact = readProjectionIdentity(directory);
+            }
+            catch {
+                // A commission snapshot admits only identities that can prove their
+                // binding. Missing or corrupt unrelated storage is not such proof.
+                continue;
+            }
+            if (pact.binding.kind === "commission" && pact.binding.commissionId === commissionId)
+                ids.push(id);
+        }
+    }
+    return ids;
+}
+const WAIT_POLL_MS = 100;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function waitingTellCount(projectionDirectory) {
+    const counts = readProjectionTellCounts(projectionDirectory);
+    return counts.inbox + counts.inflight + counts.submitted + counts.delivered;
+}
+function latestValidEventAgeMs(events, nowMs) {
+    let latest;
+    for (const event of events) {
+        const atMs = Date.parse(event.at);
+        if (!Number.isFinite(atMs))
+            continue;
+        if (latest === undefined || atMs > latest)
+            latest = atMs;
+    }
+    return latest === undefined ? undefined : Math.max(0, nowMs - latest);
+}
+function adoptionAgeMs(current, nowMs) {
+    const adoptedAt = current?.adoption?.facts.adoptedAt;
+    if (typeof adoptedAt !== "string")
+        return undefined;
+    const adoptedAtMs = Date.parse(adoptedAt);
+    return Number.isFinite(adoptedAtMs)
+        ? Math.max(0, nowMs - adoptedAtMs)
+        : undefined;
+}
+function relativeEventLedgerFile(executionId) {
+    return `${executionId}.events.jsonl`;
+}
+function timestampFact(current, nowMs) {
+    const facts = current.verdict?.facts;
+    for (const key of ["completedAt", "failedAt", "dismissedAt", "killedAt"]) {
+        const value = facts?.[key];
+        if (typeof value === "string" && Number.isFinite(Date.parse(value)))
+            return value;
+    }
+    return new Date(nowMs).toISOString();
+}
+function verdictFromCurrent(current, nowMs) {
+    if (!current.verdict)
+        return undefined;
+    const state = current.verdict.facts.state;
+    if (typeof state !== "string")
+        return undefined;
+    const terminalFailure = projectTerminalFailure(state, current.verdict.facts);
+    return {
+        state: state,
+        at: timestampFact(current, nowMs),
+        ...(terminalFailure ? { terminalFailure } : {}),
+    };
+}
+function outcomeText(current) {
+    if (current.verdict?.facts.state !== "completed")
+        return undefined;
+    const finalMessage = current.verdict?.facts.finalMessage;
+    if (typeof finalMessage === "string" && finalMessage.trim())
+        return finalMessage;
+    return undefined;
+}
+function buildSnapshot(input) {
+    const { projectionDirectory, pact, phase, current, events, malformedEvents, nowMs } = input;
+    const anchorAt = current?.verdict ? timestampFact(current, nowMs) : new Date(nowMs).toISOString();
+    const anchorMs = Date.parse(anchorAt);
+    const mintedAtMs = Date.parse(pact.mintedAt);
+    const activityAgeMs = latestValidEventAgeMs(events, nowMs)
+        ?? adoptionAgeMs(current, nowMs);
+    const invalidActivity = invalidActivityEventDiagnostic(malformedEvents);
+    const artifactId = current?.verdict?.facts.artifactId;
+    const responsePath = current?.verdict?.facts.responsePath;
+    const completed = current?.verdict?.facts.state === "completed";
+    return {
+        phase,
+        observedAtMs: Number.isFinite(anchorMs) ? anchorMs : nowMs,
+        durationMs: Number.isFinite(mintedAtMs) && Number.isFinite(anchorMs)
+            ? Math.max(0, anchorMs - mintedAtMs)
+            : 0,
+        ...(activityAgeMs !== undefined ? { activityAgeMs } : {}),
+        tellsWaiting: waitingTellCount(projectionDirectory),
+        activity: foldPublicProjectionActivity(events),
+        ...(invalidActivity ? { eventDiagnostics: [invalidActivity] } : {}),
+        workspaceRoot: pact.workspaceRoot,
+        ...(current ? {
+            executionId: current.launch.executionId,
+            eventLedgerFile: relativeEventLedgerFile(current.launch.executionId),
+        } : {}),
+        ...(completed && typeof responsePath === "string" && responsePath.trim() ? { responsePath } : {}),
+        ...(completed && typeof artifactId === "string" && RESPONSE_ARTIFACT_ID_RE.test(artifactId) ? { artifactId } : {}),
+    };
+}
+export async function waitForProjection(input) {
+    const now = input.now ?? Date.now;
+    let pact;
+    try {
+        pact = readProjectionIdentity(input.projectionDirectory);
+    }
+    catch (error) {
+        return {
+            state: "unknown",
+            diagnostic: `projection identity could not be observed: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    const deadline = input.deadlineMs
+        ?? (input.timeoutMs === undefined ? undefined : now() + input.timeoutMs);
+    for (;;) {
+        input.signal?.throwIfAborted();
+        const observedAtMs = now();
+        const observation = observeProjectionLifeSnapshot(input.projectionDirectory, {
+            nowMs: observedAtMs,
+            startupTimeoutMs: PROJECTION_ADOPTION_TIMEOUT_MS,
+        });
+        const current = observation.records
+            ? selectCurrentGeneration(observation.records)
+            : null;
+        const life = observation.life;
+        const verdict = current ? verdictFromCurrent(current, observedAtMs) : undefined;
+        const terminal = verdict !== undefined;
+        const terminalAtMs = verdict === undefined ? undefined : Date.parse(verdict.at);
+        const terminalWithinDeadline = terminal && (input.deadlineMs === undefined
+            || (typeof terminalAtMs === "number" && Number.isFinite(terminalAtMs) && terminalAtMs < input.deadlineMs));
+        if (terminalWithinDeadline || (deadline !== undefined && observedAtMs >= deadline)) {
+            const stored = current
+                ? readGenerationEvents(input.projectionDirectory, current.launch.executionId)
+                : [];
+            const { events, malformed } = selectValidStoredAgentEvents(stored);
+            const snapshot = buildSnapshot({
+                projectionDirectory: input.projectionDirectory,
+                pact,
+                phase: life.phase,
+                current,
+                events,
+                malformedEvents: malformed,
+                nowMs: observedAtMs,
+            });
+            if (terminalWithinDeadline && current) {
+                const text = outcomeText(current);
+                return {
+                    state: "terminal",
+                    pact,
+                    verdict,
+                    snapshot,
+                    ...(text ? { outcomeText: text } : {}),
+                };
+            }
+            return {
+                state: "timeout",
+                pact,
+                snapshot,
+                ...(terminal ? { terminalSnapshot: true } : {}),
+            };
+        }
+        const waitMs = deadline === undefined
+            ? WAIT_POLL_MS
+            : Math.max(0, Math.min(WAIT_POLL_MS, deadline - observedAtMs));
+        await sleep(waitMs);
+    }
+}
+/**
+ * Observe a fixed projection set. Admission owns the set snapshot; this reader
+ * never discovers or adds a projection while it is waiting.
+ */
+export async function waitForProjectionSet(input) {
+    const controller = new AbortController();
+    const abort = () => controller.abort(input.signal?.reason);
+    if (input.signal?.aborted)
+        abort();
+    input.signal?.addEventListener("abort", abort, { once: true });
+    const members = [...input.projections].sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+    const now = input.now ?? Date.now;
+    const deadlineMs = input.timeoutMs === undefined ? undefined : now() + input.timeoutMs;
+    try {
+        const waits = members.map((member, index) => waitForProjection({
+            projectionDirectory: member.projectionDirectory,
+            ...(deadlineMs === undefined ? {} : { deadlineMs }),
+            now,
+            signal: controller.signal,
+        }).then((result) => ({ index, id: member.id, result }), (error) => ({ index, id: member.id, error })));
+        if (input.selection === "all") {
+            const settled = await Promise.all(waits);
+            for (const item of settled) {
+                if ("error" in item)
+                    throw item.error;
+            }
+            return {
+                selection: "all",
+                results: settled.map((item) => ({ id: item.id, result: item.result })),
+            };
+        }
+        const pending = new Set(waits.keys());
+        const observed = [];
+        while (pending.size > 0) {
+            const next = await Promise.race([...pending].map((index) => waits[index]));
+            pending.delete(next.index);
+            if ("error" in next)
+                throw next.error;
+            if (next.result.state === "terminal") {
+                controller.abort();
+                return { selection: "any", selectedId: next.id, results: [{ id: next.id, result: next.result }] };
+            }
+            observed.push({ id: next.id, result: next.result });
+        }
+        return { selection: "any", results: observed.sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0) };
+    }
+    finally {
+        input.signal?.removeEventListener("abort", abort);
+    }
+}

package/build/core/projection/projection-wake.js

@@ -0,0 +1,203 @@
+import { FlowError } from "../../flow-error.js";
+import { parseResolvedAkumaLaunchSnapshot } from "../../agents/launch-snapshot/model.js";
+import { isRecoverableSessionEnvelope } from "../../agents/harness/index.js";
+import { ProjectionStateError } from "../atomic-publish.js";
+import { applyContinuationEffort, snapshotPendingTells, } from "./generation/projection-generation-continuation.js";
+import { createProjectionExecutionId } from "./generation/projection-generation-identity.js";
+import { PROJECTION_ADOPTION_POLL_MS, PROJECTION_ADOPTION_TIMEOUT_MS, startProjectionGeneration, } from "./generation/projection-generation-launcher.js";
+import { openProjectionGenerationStore, openProjectionGenerationStoreReadOnly, } from "./generation/store.js";
+import { observeProjectionLife } from "./projection-life-observer.js";
+import { observeProjectionRunnerLock } from "./projection-runner-lock.js";
+import { setTimeout as delay } from "node:timers/promises";
+function readCurrentGeneration(projectionDirectory) {
+    const store = openProjectionGenerationStoreReadOnly(projectionDirectory);
+    try {
+        return store.readCurrentGeneration();
+    }
+    finally {
+        store.close();
+    }
+}
+function successorFacts(current, snapshot, nowMs, requireContinuation) {
+    const verdictFacts = current.verdict?.facts;
+    const originalInputs = current.launch.facts.inputs;
+    const inputs = originalInputs
+        && typeof originalInputs === "object"
+        && !Array.isArray(originalInputs)
+        ? originalInputs
+        : {};
+    const session = verdictFacts?.session ?? inputs.session;
+    const launchSnapshot = parseResolvedAkumaLaunchSnapshot(inputs.launchSnapshot);
+    const recoverableSession = isRecoverableSessionEnvelope(launchSnapshot.provider.name, session);
+    if (requireContinuation && !recoverableSession) {
+        throw new FlowError("PROJECTION_WAKE_FAILED", "The tell was saved, but the successor could not be started because its provider session is not recoverable.");
+    }
+    const { sourceArtifactId: _sourceArtifactId, ...inheritedInputs } = inputs;
+    const resumePath = typeof verdictFacts?.responsePath === "string"
+        ? verdictFacts.responsePath
+        : typeof inputs.resumePath === "string"
+            ? inputs.resumePath
+            : undefined;
+    const continuedInputs = {
+        ...inheritedInputs,
+        ...(recoverableSession ? {
+            session,
+            ...(resumePath ? { resumePath } : {}),
+        } : {}),
+    };
+    const { tellFence: _oldFence, ...inherited } = current.launch.facts;
+    return {
+        ...inherited,
+        createdAt: new Date(nowMs).toISOString(),
+        launchedBy: "tell-wake",
+        parentExecutionId: current.launch.executionId,
+        tellFence: snapshot.tellIds,
+        inputs: applyContinuationEffort(continuedInputs, snapshot.effort),
+    };
+}
+export function assertTellEffortSupported(projectionDirectory, effort) {
+    if (!effort)
+        return;
+    const current = readCurrentGeneration(projectionDirectory);
+    if (!current)
+        throw new ProjectionStateError("projection has no immutable generation launch");
+    const inputs = current.launch.facts.inputs;
+    if (!inputs || typeof inputs !== "object" || Array.isArray(inputs)) {
+        throw new ProjectionStateError("generation launch inputs are missing");
+    }
+    let launchSnapshot;
+    try {
+        launchSnapshot = parseResolvedAkumaLaunchSnapshot(inputs.launchSnapshot);
+    }
+    catch (error) {
+        throw new ProjectionStateError("generation launch has an invalid immutable launchSnapshot", { cause: error });
+    }
+    if (launchSnapshot.akuma.model === undefined) {
+        throw new FlowError("INVALID_EFFORT_OVERRIDE", `Effort '${effort}' requires an explicit model.`);
+    }
+    const effortOptions = launchSnapshot.akuma.effortOptions;
+    if (effortOptions === undefined)
+        return;
+    if (!effortOptions.includes(effort)) {
+        throw new FlowError("INVALID_EFFORT_OVERRIDE", `Effort '${effort}' is not permitted; legal values: ${effortOptions.join(", ")}.`);
+    }
+}
+async function startCommittedSuccessor(projectionDirectory, projectionId, executionId, startGeneration) {
+    const started = await startGeneration(projectionDirectory, executionId);
+    if (started.status === "adopted")
+        return "woken";
+    throw new FlowError("PROJECTION_WAKE_FAILED", `The tell was saved for '${projectionId}', but its successor could not be started.`, {
+        facts: {
+            kind: "projection_wake_failure",
+            projectionId,
+            cause: started.cause,
+            tellRetained: true,
+        },
+    });
+}
+function sessionWakeFailure(projectionId, cause) {
+    return new FlowError("PROJECTION_WAKE_FAILED", `The tell was saved for '${projectionId}', but its successor could not be started.`, {
+        cause,
+        facts: {
+            kind: "projection_wake_failure",
+            projectionId,
+            cause: "session_unrecoverable",
+            tellRetained: true,
+        },
+    });
+}
+export async function tellProjection(projectionDirectory, projectionId, effort, dependencies = {}) {
+    const startGeneration = dependencies.startGeneration ?? startProjectionGeneration;
+    const sleep = dependencies.sleep ?? ((milliseconds) => delay(milliseconds));
+    const observationStartedAt = Date.now();
+    for (;;) {
+        const nowMs = Date.now();
+        const life = observeProjectionLife(projectionDirectory, {
+            nowMs,
+            startupTimeoutMs: PROJECTION_ADOPTION_TIMEOUT_MS,
+        });
+        if (life.phase === "active")
+            return "active";
+        if (life.phase === "minting" || life.phase === "quiescent") {
+            if (life.phase === "quiescent" && nowMs - observationStartedAt >= PROJECTION_ADOPTION_TIMEOUT_MS) {
+                throw sessionWakeFailure(projectionId, new Error("projection has no generation continuation"));
+            }
+            await sleep(PROJECTION_ADOPTION_POLL_MS);
+            continue;
+        }
+        if (life.phase === "unknown") {
+            return "pending";
+        }
+        const current = readCurrentGeneration(projectionDirectory);
+        if (!current)
+            return "pending";
+        if (current.killIntent && !current.verdict)
+            return "pending";
+        const snapshot = snapshotPendingTells(projectionDirectory);
+        const successorExecutionId = createProjectionExecutionId(nowMs);
+        let facts;
+        try {
+            facts = successorFacts(current, { ...snapshot, ...(effort ? { effort } : {}) }, nowMs, life.phase !== "startup-timeout");
+        }
+        catch (error) {
+            if (error instanceof FlowError && error.code === "PROJECTION_WAKE_FAILED") {
+                throw sessionWakeFailure(projectionId, error);
+            }
+            throw error;
+        }
+        const store = openProjectionGenerationStore(projectionDirectory);
+        try {
+            if (life.phase === "startup-timeout") {
+                const transition = store.supersedeStartupTimeout({
+                    executionId: current.launch.executionId,
+                    observedAtMs: nowMs,
+                    startupTimeoutMs: PROJECTION_ADOPTION_TIMEOUT_MS,
+                    diagnostic: { detail: "runner did not adopt before startup timeout" },
+                    successorExecutionId,
+                    successorFacts: facts,
+                });
+                if (transition.status === "committed") {
+                    return await startCommittedSuccessor(projectionDirectory, projectionId, successorExecutionId, startGeneration);
+                }
+                if (transition.reason === "kill-requested")
+                    return "pending";
+                await sleep(PROJECTION_ADOPTION_POLL_MS);
+                continue;
+            }
+            if (life.phase === "lost" && !current.verdict) {
+                const lock = observeProjectionRunnerLock(projectionDirectory);
+                if (lock.state !== "released")
+                    return lock.state === "held" ? "active" : "pending";
+                const transition = store.replaceDeadRunner({
+                    executionId: current.launch.executionId,
+                    releasedLockEvidence: { observedAt: new Date(nowMs).toISOString() },
+                    successorExecutionId,
+                    successorFacts: facts,
+                });
+                if (transition.status === "committed") {
+                    return await startCommittedSuccessor(projectionDirectory, projectionId, successorExecutionId, startGeneration);
+                }
+                if (transition.reason === "kill-requested")
+                    return "pending";
+                await sleep(PROJECTION_ADOPTION_POLL_MS);
+                continue;
+            }
+            if (!["done", "failed", "lost", "dismissed", "killed"].includes(life.phase)) {
+                return "pending";
+            }
+            const transition = store.launchIfSettled({
+                executionId: successorExecutionId,
+                facts,
+            });
+            if (transition.status === "committed") {
+                return await startCommittedSuccessor(projectionDirectory, projectionId, successorExecutionId, startGeneration);
+            }
+            if (transition.reason === "kill-requested")
+                return "pending";
+            await sleep(PROJECTION_ADOPTION_POLL_MS);
+        }
+        finally {
+            store.close();
+        }
+    }
+}

package/build/core/provider-loader-ports.js

@@ -0,0 +1,4 @@
+import { getProviderRegistration, } from "../agents/providers/registry.js";
+export function attachProviderLoaderPorts(terms, ports) {
+    return getProviderRegistration(terms.provider).attachLoader(terms, ports);
+}

package/build/core/ref-log.js

@@ -1,10 +1,13 @@
-import { createGit, errorContainsAnyPattern, MISSING_HEAD_PATTERNS, wrapGitError } from "../git/core.js";
+import { createGit, errorContainsAnyPattern, MISSING_HEAD_PATTERNS, parseRevListOutput, wrapGitError } from "../git/core.js";
 const EMPTY_TREE_HASH = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
 const MISSING_REF_SENTINEL = "0".repeat(40);
-async function resolveRefHead(cwd, ref) {
+/** Resolve a ref log head, or null when the ref is missing. */
+export async function resolveRefLogHead(cwd, ref, options = {}) {
     const git = createGit(cwd);
+    const peel = options.peel ?? "commit";
+    const target = peel === "commit" ? `${ref}^{commit}` : ref;
     try {
-        return (await git.raw(["rev-parse", "--verify", `${ref}^{commit}`])).trim();
+        return (await git.raw(["rev-parse", "--verify", target])).trim();
     }
     catch (error) {
         if (errorContainsAnyPattern(error, MISSING_HEAD_PATTERNS))
@@ -12,7 +15,8 @@ async function resolveRefHead(cwd, ref) {
         throw wrapGitError(`rev-parse ${ref}`, error, cwd);
     }
 }
-async function readCommitMessage(cwd, commit) {
+/** Read the raw commit message bytes used by ref-log parsers (`show %B`). */
+export async function readRefLogCommitMessage(cwd, commit) {
     const git = createGit(cwd);
     try {
         return await git.raw(["show", "-s", "--format=%B", commit]);
@@ -21,71 +25,92 @@ async function readCommitMessage(cwd, commit) {
         throw wrapGitError(`show commit message ${commit}`, error, cwd);
     }
 }
-async function readRefLogAt(cwd, ref, head, parse) {
+/**
+ * List commits reachable from `head` oldest-first.
+ * `errorLabel` is the ref or range name used in wrapGitError text.
+ */
+export async function listRefLogCommits(cwd, head, errorLabel = head) {
     const git = createGit(cwd);
-    let output;
     try {
-        output = await git.raw(["rev-list", "--reverse", head]);
+        return parseRevListOutput(await git.raw(["rev-list", "--reverse", head]));
     }
     catch (error) {
-        throw wrapGitError(`rev-list ${ref}`, error, cwd);
-    }
-    const commits = output
-        .trim()
-        .split("\n")
-        .map((line) => line.trim())
-        .filter(Boolean);
-    const entries = [];
-    for (const commit of commits) {
-        entries.push(parse(await readCommitMessage(cwd, commit)));
+        throw wrapGitError(`rev-list ${errorLabel}`, error, cwd);
     }
-    return entries;
 }
-async function createRefLogCommit(cwd, subject, entry, parentHead) {
+/**
+ * Create an empty-tree commit for a ref log entry.
+ * Callers own subject/body byte layout so message formats stay domain-local.
+ */
+export async function createRefLogCommit(cwd, input) {
     const git = createGit(cwd);
     const args = ["commit-tree", EMPTY_TREE_HASH];
-    if (parentHead)
-        args.push("-p", parentHead);
-    args.push("-m", subject, "-m", JSON.stringify(entry, null, 2));
+    if (input.parentHead)
+        args.push("-p", input.parentHead);
+    args.push("-m", input.subject, "-m", input.body);
     try {
         return (await git.raw(args)).trim();
     }
     catch (error) {
-        throw wrapGitError(`commit-tree ${subject}`, error, cwd);
+        throw wrapGitError(`commit-tree ${input.errorLabel ?? input.subject}`, error, cwd);
+    }
+}
+/**
+ * Compare-and-swap a ref to `newHead`.
+ * Returns false on CAS failure; callers own re-resolve / degrade policy.
+ */
+export async function casUpdateRefLog(cwd, ref, newHead, expectedOld) {
+    const git = createGit(cwd);
+    const oldValue = expectedOld ?? MISSING_REF_SENTINEL;
+    try {
+        await git.raw(["update-ref", ref, newHead, oldValue]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readRefLogAt(cwd, ref, head, parse) {
+    const commits = await listRefLogCommits(cwd, head, ref);
+    const entries = [];
+    for (const commit of commits) {
+        entries.push(parse(await readRefLogCommitMessage(cwd, commit)));
     }
+    return entries;
 }
 export async function readRefLog(cwd, ref, parse) {
-    const head = await resolveRefHead(cwd, ref);
+    const head = await resolveRefLogHead(cwd, ref);
     if (!head)
         return [];
     return readRefLogAt(cwd, ref, head, parse);
 }
 export async function appendRefLogWithRetry(cwd, ref, subjectFor, parse, build, options = {}) {
     const maxRetries = options.maxRetries ?? 3;
-    let currentHead = await resolveRefHead(cwd, ref);
+    let currentHead = await resolveRefLogHead(cwd, ref);
     const startedMissing = currentHead === null;
     for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
         const entries = currentHead ? await readRefLogAt(cwd, ref, currentHead, parse) : [];
         const entry = await build(entries);
         if (entry === null)
             return { ok: false, reason: "aborted", currentHead };
-        const newHead = await createRefLogCommit(cwd, subjectFor(entry), entry, currentHead);
-        const oldValue = currentHead ?? MISSING_REF_SENTINEL;
-        const git = createGit(cwd);
-        try {
-            await git.raw(["update-ref", ref, newHead, oldValue]);
+        const newHead = await createRefLogCommit(cwd, {
+            subject: subjectFor(entry),
+            body: JSON.stringify(entry, null, 2),
+            parentHead: currentHead,
+        });
+        const casOk = await casUpdateRefLog(cwd, ref, newHead, currentHead);
+        if (casOk)
             return { ok: true, head: newHead };
+        // Intentional degrade: re-resolve after CAS loss; missing-ref mid-flight is sticky
+        // when the ref existed at start (do not resurrect).
+        const resolved = await resolveRefLogHead(cwd, ref);
+        if (resolved === null) {
+            if (!startedMissing)
+                return { ok: false, reason: "missing-ref" };
+            currentHead = null;
         }
-        catch {
-            const resolved = await resolveRefHead(cwd, ref);
-            if (resolved === null) {
-                if (!startedMissing)
-                    return { ok: false, reason: "missing-ref" };
-                currentHead = null;
-            }
-            else {
-                currentHead = resolved;
-            }
+        else {
+            currentHead = resolved;
         }
     }
     if (currentHead === null)