@astrosheep/keiyaku 4.5.7 → 4.5.8

package/build/src/contract-worktree.js

@@ -3,94 +3,18 @@ import { join } from "node:path";
 import { acquireSqliteTransactionLock } from "./coordination/sqlite-transaction-lock.js";
 import { repairDerivedFile } from "./coordination/durable-file.js";
 import { contractId } from "./core/facts/types.js";
+import { CONTRACT_DELIVERER_SKILL, CONTRACT_REVIEWER_SKILL, renderContractAppointment, renderContractGuidance, } from "./contract-guidance.js";
 import { worktreeGitDirectory, worktreeRoot } from "./git/repository.js";
 import { GitPlumbingError, runGit } from "./git/process.js";
 import { worktreePath } from "./git/workspace.js";
 import { appointmentFor, placeRegisterPath } from "./workspace-place.js";
 const IGNORE_BYTES = ".gitignore\nKEIYAKU.md\n";
 const PRIMARY_IGNORE_BYTES = "*\n!settings.json\n!tasks/\n!tasks/**\n";
-const APPOINTMENT_DESCRIPTION = "This is a read-only projection. Do not edit manually.";
-function appointmentBytes(contract) {
-    return `---\ncontract: ${contract}\ndescription: ${APPOINTMENT_DESCRIPTION}\n---\n`;
-}
-function renderArc(arc) {
-    return [
-        "## Arc",
-        "",
-        "### Sequence",
-        "",
-        String(arc.seq),
-        "",
-        "### Title",
-        "",
-        arc.title.trimEnd(),
-        "",
-        "### Objective",
-        "",
-        arc.objective.trimEnd(),
-        "",
-        "### Brief",
-        "",
-        arc.brief.trimEnd(),
-    ].join("\n");
-}
-const FULFILLMENT = [
-    "## Fulfillment",
-    "",
-    "### Appointment",
-    "",
-    "Each commission names exactly one seat: Deliverer or Reviewer.",
-    "If no seat was named, stop and ask the caller. Never infer it.",
-    "",
-    "### Worktree",
-    "",
-    "This file is a derived view of the journal-authoritative Contract. Never edit it to change the Contract.",
-    "Treat the directory containing `.keiyaku/KEIYAKU.md` as the Contract worktree root.",
-    "Read the complete Contract before acting and keep work inside that worktree.",
-    "",
-    "### Deliverer",
-    "",
-    "Re-read this file on each wake-up; it may have been updated between sessions.",
-    "Implement and verify the Objective under the Design, Region, and Criteria in this Contract.",
-    "Region is a rough intent, not a hard boundary — natural ripple outside it is fine and not a blocker.",
-    "When an Arc is active, stay within that current chapter.",
-    "If you discover a contradiction with this Contract or an unclosed point in its terms,",
-    "stop and report it before continuing.",
-    "",
-    "For work requiring three or more steps, prefer `keiyaku task -C <worktree>` to organize and manage Tasks.",
-    "Promptly update progress for Tasks already present in the current worktree.",
-    "",
-    "Deliver from this worktree. A clean worktree delivers HEAD; uncommitted work",
-    "needs `deliver --include-dirty`, which captures the final non-ignored tree and",
-    "stages or commits nothing. If deliver reports a conflict, run",
-    "`deliver --materialize-conflict`, resolve the conflicted files, stage them,",
-    "and deliver again; while the merge stays uncommitted that continuation uses",
-    "`--include-dirty`. Unresolved paths always refuse.",
-    "",
-    "### Reviewer",
-    "",
-    "Re-read this file on each wake-up; it may have been updated between sessions.",
-    "Review the complete current worktree snapshot against this Contract. Do not modify it.",
-    "Understand the original intent behind the Objective, not just its literal text.",
-    "Region is a rough intent, not a hard boundary — natural ripple outside it is not a blocker.",
-    "Compare each Criterion individually against the delivered work.",
-    "Consolidate findings by root cause — group symptoms that share an underlying issue",
-    "rather than listing each occurrence separately.",
-    "Dig to the architectural or structural root; flag it directly rather than routing around it.",
-    "If you discover a contradiction within the Contract or an unclosed point in its terms,",
-    "report it as a finding.",
-    "Report covered Criteria, findings, and missing evidence.",
-].join("\n");
-export function renderContractGuidance(state) {
-    return [
-        appointmentBytes(state.id).trimEnd(),
-        state.terms.document.bytes.trimEnd(),
-        ...(state.currentArc === undefined ? [] : [renderArc(state.currentArc.data)]),
-        FULFILLMENT,
-    ]
-        .join("\n\n")
-        .concat("\n");
-}
+const SEAT_IGNORE_BYTES = ".gitignore\nSKILL.md\n";
+const SEAT_SKILLS = [
+    ["keiyaku-deliver", CONTRACT_DELIVERER_SKILL],
+    ["keiyaku-review", CONTRACT_REVIEWER_SKILL],
+];
 async function isTracked(repository, relativePath) {
     try {
         await runGit(repository, ["ls-files", "--error-unmatch", "--", relativePath]);
@@ -145,7 +69,7 @@ export async function releaseContractWorktree(repository, contract) {
     const appointment = await readContractAppointment(repository);
     if (appointment.kind !== "appointed" || appointment.contract !== contract)
         return;
-    if ((await readFile(appointment.path, "utf8")) !== appointmentBytes(contract))
+    if ((await readFile(appointment.path, "utf8")) !== renderContractAppointment(contract))
         return;
     try {
         await unlink(appointment.path);
@@ -169,6 +93,23 @@ async function repair(repository, worktree, relativePath, bytes) {
     }
     return { kind: "contract-file", path, action };
 }
+async function isKeiyakuSeatLeaf(worktree, seat) {
+    const sentinel = join(worktree, ".agents", "skills", seat, ".gitignore");
+    const stat = await lstat(sentinel).catch((error) => error.code === "ENOENT" ? undefined : Promise.reject(error));
+    return stat?.isFile() === true && !stat.isSymbolicLink() && (await readFile(sentinel, "utf8")) === SEAT_IGNORE_BYTES;
+}
+async function materializeSeatSkill(repository, worktree, seat, bytes) {
+    const leaf = `.agents/skills/${seat}`;
+    const skill = `${leaf}/SKILL.md`;
+    const skillPath = join(worktree, skill);
+    const skillExists = await lstat(skillPath).catch((error) => error.code === "ENOENT" ? false : Promise.reject(error));
+    if (!(await isKeiyakuSeatLeaf(worktree, seat)) && skillExists)
+        return [];
+    return [
+        await repair(repository, worktree, `${leaf}/.gitignore`, SEAT_IGNORE_BYTES),
+        await repair(repository, worktree, skill, bytes),
+    ];
+}
 async function materialize(repository, worktree, guidance) {
     const effects = [];
     const failed = (target, path, error) => ({
@@ -218,6 +159,14 @@ async function materialize(repository, worktree, guidance) {
             return failed(worktree, join(worktree, relativePath), error);
         }
     }
+    for (const [seat, bytes] of SEAT_SKILLS) {
+        try {
+            effects.push(...(await materializeSeatSkill(scoped, worktree, seat, bytes)));
+        }
+        catch (error) {
+            return failed(worktree, join(worktree, ".agents", "skills", seat), error);
+        }
+    }
     return { effects, lag: [] };
 }
 export async function projectContractWorktree(repository, state, register, _onConflict) {

package/build/src/coordination/sqlite-transaction-lock.d.ts

@@ -11,6 +11,7 @@ export declare function acquireSqliteTransactionLock(input: {
     mode: SqliteTransactionLockMode;
     timeoutMs?: number;
     signal?: AbortSignal;
+    onContended?: () => void;
 }): Promise<HeldSqliteTransactionLock>;
 export declare function tryAcquireSqliteTransactionLock(input: {
     path: string;

package/build/src/coordination/sqlite-transaction-lock.js

@@ -119,6 +119,7 @@ export async function acquireSqliteTransactionLock(input) {
     }
     const started = performance.now();
     let cap = INITIAL_RETRY_MS;
+    let contended = false;
     for (;;) {
         input.signal?.throwIfAborted();
         try {
@@ -127,6 +128,10 @@ export async function acquireSqliteTransactionLock(input) {
         catch (error) {
             if (!isBusy(error))
                 throw error;
+            if (!contended) {
+                contended = true;
+                input.onContended?.();
+            }
             const elapsed = performance.now() - started;
             if (input.timeoutMs !== undefined && elapsed >= input.timeoutMs) {
                 throw new SqliteTransactionLockError(`SQLite lock timed out after ${input.timeoutMs}ms: ${input.path}`, "timeout", { cause: error });

package/build/src/core/facts/codec.d.ts

@@ -1,3 +1,5 @@
 import type { JournalEntry } from "./types.js";
+/** Validate one in-memory journal value with the persisted-fact authority. */
+export declare function decodeJournalEntry(value: unknown): JournalEntry;
 export declare function encodeEntry(entry: JournalEntry): string;
 export declare function decodeJournal(journal: string): JournalEntry[];

package/build/src/core/facts/codec.js

@@ -235,6 +235,10 @@ function validateEntry(value) {
     }
     return entry;
 }
+/** Validate one in-memory journal value with the persisted-fact authority. */
+export function decodeJournalEntry(value) {
+    return validateEntry(value);
+}
 function canonicalValue(value) {
     if (value === null)
         return "null";

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

@@ -1,3 +1,4 @@
+import { type GateReport } from "../facts/gate.js";
 import type { ActorId, ContractId } from "../facts/types.js";
 import type { DecideInput, OfferDecision } from "../decide.js";
 type PlacementInput = Readonly<{
@@ -10,8 +11,12 @@ export type UnmetPrerequisite = Readonly<{
     state: "missing" | "active" | "abandoned";
 }>;
 export type PlacementRefusal = Readonly<{
-    kind: "contract-missing" | "delivery-missing" | "terminal" | "gates-unsatisfied";
+    kind: "contract-missing" | "delivery-missing" | "terminal";
     contractId: ContractId;
+}> | Readonly<{
+    kind: "gates-unsatisfied";
+    contractId: ContractId;
+    unmet: readonly GateReport[];
 }> | Readonly<{
     kind: "prerequisites-unsatisfied";
     contractId: ContractId;

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

@@ -1,4 +1,4 @@
-import { gatesSatisfied } from "../facts/gate.js";
+import { gateReports } from "../facts/gate.js";
 import { activeContract, contractState } from "../facts/observation.js";
 function unmetPrerequisites(prerequisites, observation) {
     const unmet = [];
@@ -30,8 +30,10 @@ export function decidePlacement({ input, attempt, observation, }) {
     if (unmet.length > 0) {
         return { kind: "refused", refusal: { kind: "prerequisites-unsatisfied", contractId: id, unmet } };
     }
-    if (!gatesSatisfied(current)) {
-        return { kind: "refused", refusal: { kind: "gates-unsatisfied", contractId: id } };
+    const gates = gateReports(current);
+    if (!gates.satisfied) {
+        const unmetGates = gates.reports.filter((report) => report.current.kind !== "attested" || report.current.verdict !== "satisfied");
+        return { kind: "refused", refusal: { kind: "gates-unsatisfied", contractId: id, unmet: unmetGates } };
     }
     const claimed = {
         v: 1,

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

@@ -10,8 +10,6 @@ export type Dispatch = Readonly<{
 export type DispatchFailure = Readonly<{
     kind: "conflict";
     current: Dispatch;
-}> | Readonly<{
-    kind: "contention";
 }> | Readonly<{
     kind: "publication-failed";
     diagnostic: string;

package/build/src/dispatch/index.js

@@ -1,15 +1,13 @@
 import { createHash } from "node:crypto";
-import { join } from "node:path";
 import { AuthorityCorruptionError } from "../core/facts/errors.js";
 import { contractId } from "../core/facts/types.js";
 import { parseAkuId } from "../akuma/identity.js";
-import { acquireSqliteTransactionLock } from "../coordination/sqlite-transaction-lock.js";
-import { GIT_FORMAT_BYTES, GIT_FORMAT_PATH, GIT_REF, readBlob, readGitPaths, updateGitTree, updateRefsAtomically, writeBlob, writeCommit, } from "../git/repository.js";
+import { confirmPrivateStatePublication, 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";
 const DISPATCH_ROOT = "dispatch";
 const DISPATCH_PREFIX = `${DISPATCH_ROOT}/`;
 const DISPATCH_SUFFIX = ".json";
-const MAX_ATTEMPTS = 3;
 function pathFor(akuId) {
     return `${DISPATCH_PREFIX}${createHash("sha256").update(akuId).digest("hex")}${DISPATCH_SUFFIX}`;
 }
@@ -125,57 +123,58 @@ export async function publishDispatch(input) {
     const owner = contractId(input.contractId);
     const intended = { akuId, contractId: owner, dispatchedAt: new Date().toISOString() };
     const path = pathFor(akuId);
-    const held = await acquireSqliteTransactionLock({
-        path: join(input.repository.commonDirectory, "keiyaku", "locks", "dispatch.sqlite"),
-        mode: "immediate",
-    });
-    try {
-        for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt += 1) {
-            const snapshot = await readGitPaths(input.repository, [path]);
-            const current = await dispatchFromSnapshot(input.repository, snapshot, akuId);
-            if (current !== null) {
-                return current.contractId === owner
-                    ? { kind: "dispatched", dispatch: current }
-                    : { kind: "failed", failure: { kind: "conflict", current } };
-            }
-            const changes = new Map();
-            if (snapshot.commit === null) {
-                changes.set(GIT_FORMAT_PATH, { oid: await writeBlob(input.repository, GIT_FORMAT_BYTES) });
-            }
-            changes.set(path, { oid: await writeBlob(input.repository, bytesFor(intended)) });
-            const tree = await updateGitTree(input.repository, snapshot.tree, changes);
-            const commit = await writeCommit({
-                repository: input.repository,
-                tree,
-                parent: snapshot.commit,
-                message: `dispatch ${akuId}`,
-                at: intended.dispatchedAt,
-            });
-            const publication = await updateRefsAtomically(input.repository, [
-                {
-                    ref: GIT_REF,
-                    newOid: commit,
-                    expectedOid: snapshot.commit,
-                },
-            ]);
-            if (publication.kind === "published")
-                return { kind: "dispatched", dispatch: intended };
-            const observed = await observedPublication(input.repository, akuId, owner);
-            if (observed !== null)
-                return observed;
-            if (publication.kind === "non-published") {
-                const fresh = await readGitPaths(input.repository, [path]);
-                if (fresh.commit === snapshot.commit) {
-                    return {
-                        kind: "failed",
-                        failure: { kind: "publication-failed", diagnostic: diagnostic(publication.error) },
-                    };
-                }
+    return await withPrivateStatePublicationSeat(input.repository, async (seat) => {
+        const snapshot = await readGitPaths(input.repository, [path]);
+        const current = await dispatchFromSnapshot(input.repository, snapshot, akuId);
+        if (current !== null) {
+            if (current.contractId === owner)
+                confirmPrivateStatePublication(seat);
+            return current.contractId === owner
+                ? { kind: "dispatched", dispatch: current }
+                : { kind: "failed", failure: { kind: "conflict", current } };
+        }
+        const changes = new Map();
+        if (snapshot.commit === null) {
+            changes.set(GIT_FORMAT_PATH, { oid: await writeBlob(input.repository, GIT_FORMAT_BYTES) });
+        }
+        changes.set(path, { oid: await writeBlob(input.repository, bytesFor(intended)) });
+        const tree = await updateGitTree(input.repository, snapshot.tree, changes);
+        const commit = await writeStateCommit({
+            repository: input.repository,
+            tree,
+            parent: snapshot.commit,
+            message: `dispatch ${akuId}`,
+            at: intended.dispatchedAt,
+        });
+        const publication = await updateRefsAtomically(input.repository, [
+            {
+                ref: GIT_REF,
+                newOid: commit,
+                expectedOid: snapshot.commit,
+            },
+        ]);
+        if (publication.kind === "published") {
+            confirmPrivateStatePublication(seat);
+            return { kind: "dispatched", dispatch: intended };
+        }
+        const observed = await observedPublication(input.repository, akuId, owner);
+        if (observed !== null) {
+            if (observed.kind === "dispatched")
+                confirmPrivateStatePublication(seat);
+            return observed;
+        }
+        if (publication.kind === "non-published") {
+            const fresh = await readGitPaths(input.repository, [path]);
+            if (fresh.commit === snapshot.commit) {
+                return {
+                    kind: "failed",
+                    failure: { kind: "publication-failed", diagnostic: diagnostic(publication.error) },
+                };
             }
         }
-        return { kind: "failed", failure: { kind: "contention" } };
-    }
-    finally {
-        held.close();
-    }
+        return {
+            kind: "failed",
+            failure: { kind: "publication-failed", diagnostic: "Dispatch publication outcome is unknown" },
+        };
+    });
 }

package/build/src/git/admission.js

@@ -1,5 +1,5 @@
 import { decodeJournal, encodeEntry } from "../core/facts/codec.js";
-import { GIT_FORMAT_BYTES, GIT_FORMAT_PATH, GIT_REF, updateGitTreeFromFrozenDirectories, updateRefsAtomically, writeBlob, writeCommit, } from "./repository.js";
+import { GIT_FORMAT_BYTES, GIT_FORMAT_PATH, GIT_REF, updateGitTreeFromFrozenDirectories, updateRefsAtomically, writeBlob, writeStateCommit, } from "./repository.js";
 import { contractJournalPath, contractJournalPaths, gitObjectIdForSnapshot, mintContractHead, mintSnapshotId, } from "./identity.js";
 import { validPath } from "./tree.js";
 const CONTRACT_JOURNAL_PATH = /^contracts\/(?:active|terminal)\/[0-9a-f]{2}\/[0-9a-f]{2}\/[0-9a-f]{60}\.jsonl$/u;
@@ -86,7 +86,7 @@ async function buildOffer(repository, admission, appends, companions) {
 async function publishOffer(repository, admission, target, changes, assertions) {
     const { snapshot } = admission;
     const gitTree = await updateGitTreeFromFrozenDirectories(repository, snapshot.tree, admission.treeDirectories, changes);
-    const gitCommit = mintSnapshotId(await writeCommit({
+    const gitCommit = mintSnapshotId(await writeStateCommit({
         repository,
         tree: gitTree,
         parent: snapshot.commit,

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

@@ -1,4 +1,5 @@
 export type HookCommand = Readonly<{
+    name: string;
     argv: readonly string[];
     timeoutMs: number;
 }>;
@@ -25,18 +26,10 @@ export type WorktreeHookLag = Readonly<{
     phase: HookPhase;
     path: string;
     command: number;
+    name: string;
     failure: HookFailure;
 }>;
-type HookPhase = "create" | "destroy";
-export declare function hookMarkerPath(administrationDirectory: string): string;
-export type WorktreeHookMarkerObservation = Readonly<{
-    kind: "absent" | "pending" | "ok";
-}> | Readonly<{
-    kind: "failed";
-    diagnostic: string;
-}>;
-/** Read the durable hook marker without executing commands or taking locks. */
-export declare function observeWorktreeHookMarker(administrationDirectory: string): Promise<WorktreeHookMarkerObservation>;
+export type HookPhase = "create" | "destroy";
 export type HookCommandRun = Readonly<{
     kind: "ok";
 }> | Readonly<{
@@ -48,8 +41,9 @@ export type HookCommandRun = Readonly<{
 }>;
 /** 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>;
-/** Remove validated Keiyaku hook state after its worktree has been reset. */
-export declare function nukeWorktreeHookResidue(administrationDirectory: string): Promise<void>;
-export declare function runCreateHooks(worktree: string, administrationDirectory: string, hooks: WorktreeHooks, retryHooks: boolean): Promise<WorktreeHookLag | null>;
-export declare function runDestroyHooks(worktree: string, administrationDirectory: string, hooks: WorktreeHooks, retryHooks: boolean): Promise<WorktreeHookLag | null>;
-export {};
+export type HookPhaseRun = Readonly<{
+    lag: WorktreeHookLag | null;
+    runs: readonly string[];
+}>;
+export declare function runCreateHooks(worktree: string, hooks: WorktreeHooks): Promise<HookPhaseRun>;
+export declare function runDestroyHooks(worktree: string, hooks: WorktreeHooks): Promise<HookPhaseRun>;