knodin 0.8.6 → 0.9.0

package/dist/src/tools/knodin-tools.js

@@ -24,6 +24,7 @@ import { diagnoseFailure, } from "../failure-diagnosis.js";
 import { decorateGraphQueryResult, inspectGraphQueryHealth } from "../graph-query-health.js";
 import { inspectRepositoryIntegrationStatus } from "../init.js";
 import { attachLifecycleHealth, attachRepairLifecycle } from "../lifecycle-health.js";
+import { readManagerUpdateState, readUpdateJournal, updateAttention } from "../manager-update.js";
 import { listMirrors } from "../mirror.js";
 import { compressOutput, compressOutputFile, deleteOutputArtifact, readOutputArtifact, } from "../output-compression.js";
 import { appendTelemetryRecord, clearTelemetry, countOutputTokens, exportTelemetry, measureOutput, readTelemetryRecords, telemetryStatus, writeTelemetryReport, } from "../output-telemetry.js";
@@ -35,7 +36,8 @@ import { discoverRepositories, initializeRepositories, inventoryRepository, sear
 import { applyResponseBudget } from "../response-budget.js";
 import { loadSharedIndexConfig } from "../shared-index/config.js";
 import { EMPTY_OVERLAY, readSharedIndexProvenance, readSharedRestoreAttempt, } from "../shared-index/provenance.js";
-import { configuredRepositoryInitMemoryLimitBytes, enrichSystemRelationships, incorporateSystemQueryEvidence, indexModeForPath, loadSystemConfiguration, queryConfiguredSystem, systemMembershipsForPath, validateSystemHealth, } from "../system-config.js";
+import { configuredRepositoryInitMemoryLimitBytes, enrichSystemRelationships, incorporateSystemQueryEvidence, indexModeForPath, loadSystemConfiguration, queryConfiguredSystem, RELATIONSHIP_TYPES, systemMembershipsForPath, validateSystemHealth, } from "../system-config.js";
+import { applySystemPlan, planSystemImport, planSystemLink, planSystemRelate, planSystemUnlink, planSystemUnrelate, } from "../system-management.js";
 import { trustedUpdateStatus } from "../update-policy.js";
 import { waitForFresh } from "../wait-for-fresh.js";
 import { inspectWorktrees, reconcileWorktrees, removeManagedWorktree, } from "../worktree-lifecycle.js";
@@ -157,6 +159,13 @@ const GRAPH_INDEPENDENT_QUERY_PATTERNS = new Set([
     "lsp_implementations",
     "file_metrics",
 ]);
+const BATCH_QUERY_PATTERNS = new Set([
+    "callers_of",
+    "callees_of",
+    "imports_of",
+    "importers_of",
+    "file_summary",
+]);
 function buildDocumentedKnodinTools() {
     return [
         {
@@ -317,7 +326,7 @@ function buildDocumentedKnodinTools() {
                     },
                     from: {
                         type: "string",
-                        description: "review: older ref of an explicit revision pair; requires `to`.",
+                        description: "review: older ref of a revision pair; system relate/unrelate: source component id.",
                     },
                     toRevision: {
                         type: "string",
@@ -494,9 +503,36 @@ function buildDocumentedKnodinTools() {
                     },
                     systemAction: {
                         type: "string",
-                        enum: ["list", "show", "validate", "query"],
-                        description: "system only: list configured systems, show or validate one system, or query its declared relationships.",
+                        enum: [
+                            "list",
+                            "show",
+                            "validate",
+                            "query",
+                            "link",
+                            "relate",
+                            "unlink",
+                            "unrelate",
+                            "import",
+                        ],
                     },
+                    planDigest: {
+                        type: "string",
+                        description: "system writes: digest returned by the approved preview",
+                    },
+                    repositories: { type: "array", items: { type: "string" } },
+                    scope: { type: "string", enum: ["personal", "team"] },
+                    distributed: { type: "boolean" },
+                    repositoryIds: {
+                        type: "object",
+                        additionalProperties: { type: "string" },
+                    },
+                    components: {
+                        type: "object",
+                        additionalProperties: { type: "object" },
+                    },
+                    evidence: { type: "string" },
+                    relationshipType: { type: "string", enum: RELATIONSHIP_TYPES },
+                    requireComplete: { type: "boolean" },
                     repositoryAction: {
                         type: "string",
                         enum: ["discover", "init", "status", "doctor", "search"],
@@ -731,14 +767,14 @@ const RESPONSE_DEFAULTS = {
     "diagnostics:archive": { bytes: 65_536, tokens: 16_384, items: 100 },
     default: { bytes: 65_536, tokens: 16_384, items: 100 },
 };
-async function populateRepositoryDiagnoses(records, repositories, configRoot) {
+async function populateRepositoryDiagnoses(records, repositories) {
     repositories.length = 0;
     for (const record of records) {
         try {
             const graph = attachLifecycleHealth(record.path, await engine.status(record.path, { audit: "deep" }));
             const repository = await inventoryRepository(record, {
                 status: async () => graph,
-                systemMemberships: (target) => systemMembershipsForPath(loadSystemConfiguration(configRoot), target),
+                systemMemberships: (target) => systemMembershipsForPath(loadSystemConfiguration(target), target),
             });
             repositories.push({
                 ...repository,
@@ -770,12 +806,11 @@ async function handleRepositoriesOperation(options) {
     };
     const inventory = async () => {
         const discovery = await discoverRepositories(discoveryRoots, discoveryOptions);
-        const systemConfig = loadSystemConfiguration(discoveryRoots[0] ?? repo);
         const repositories = [];
         for (const record of discovery.repositories) {
             repositories.push(await inventoryRepository(record, {
                 status: async (target) => attachLifecycleHealth(target, await engine.status(target, { audit: "cached" })),
-                systemMemberships: (target) => systemMembershipsForPath(systemConfig, target),
+                systemMemberships: (target) => systemMembershipsForPath(loadSystemConfiguration(target), target),
             }));
         }
         return { discovery, repositories };
@@ -792,8 +827,12 @@ async function handleRepositoriesOperation(options) {
             worktrees: linkedWorktrees,
             dryRun,
             manifestPath,
-            indexMode: (target) => indexModeForPath(systemConfig, target),
-            isolatedInitialize: (target) => runRepositoryInitializationProcess({ repository: target, command, memoryLimitBytes }),
+            indexMode: (target) => indexModeForPath(loadSystemConfiguration(target), target),
+            isolatedInitialize: (target) => runRepositoryInitializationProcess({
+                repository: target,
+                command,
+                memoryLimitBytes,
+            }),
         });
         const { repositories } = await inventory();
         return bounded({ schemaVersion: 1, ...summary, repositories }, "repositories:init");
@@ -801,7 +840,6 @@ async function handleRepositoriesOperation(options) {
     if (repositoryAction === "search") {
         if (!query?.trim())
             throw new Error("knodin repositories search requires a non-empty `query`");
-        const systemConfig = loadSystemConfiguration(discoveryRoots[0] ?? repo);
         return searchRepositories(discoveryRoots, query, {
             ...discoveryOptions,
             include,
@@ -817,12 +855,12 @@ async function handleRepositoriesOperation(options) {
                 includeSource: true,
                 federate: false,
             }),
-            systemMemberships: (target) => systemMembershipsForPath(systemConfig, target),
+            systemMemberships: (target) => systemMembershipsForPath(loadSystemConfiguration(target), target),
         });
     }
     const { discovery, repositories } = await inventory();
     if (repositoryAction === "doctor")
-        await populateRepositoryDiagnoses(discovery.repositories, repositories, discoveryRoots[0] ?? repo);
+        await populateRepositoryDiagnoses(discovery.repositories, repositories);
     return bounded({
         schemaVersion: 1,
         linkedWorktrees: discoveryOptions.linkedWorktrees,
@@ -833,7 +871,67 @@ async function handleRepositoriesOperation(options) {
     }, `repositories:${repositoryAction}`);
 }
 async function handleSystemOperation(options) {
-    const { systemAction, symbol, repo, allowPartial, bounded } = options;
+    const { systemAction, symbol, repo, bounded } = options;
+    if (["link", "relate", "unlink", "unrelate", "import"].includes(systemAction)) {
+        if (systemAction !== "import" && !symbol)
+            throw new Error(`knodin system ${systemAction} requires \`symbol\``);
+        const systemId = symbol ?? "";
+        let plan;
+        if (systemAction === "import") {
+            if (!options.manifestPath)
+                throw new Error("system import requires manifestPath");
+            plan = planSystemImport({
+                manifestPath: options.manifestPath,
+                scope: options.scope,
+                repoPath: repo,
+            });
+        }
+        else if (systemAction === "link")
+            plan = planSystemLink({
+                systemId,
+                repositories: options.repositories ?? [],
+                scope: options.scope,
+                distributed: options.distributed,
+                repositoryIds: options.repositoryIds,
+                components: options.components,
+            });
+        else if (systemAction === "relate") {
+            if (!options.relationshipType || !options.from || !options.to || !options.evidence)
+                throw new Error("system relate requires relationshipType, from, to, and evidence");
+            plan = planSystemRelate({
+                systemId,
+                type: options.relationshipType,
+                from: options.from,
+                to: options.to,
+                evidence: options.evidence,
+                repoPath: repo,
+            });
+        }
+        else if (systemAction === "unlink")
+            plan = planSystemUnlink({
+                systemId,
+                repositories: options.repositories,
+                repoPath: repo,
+            });
+        else {
+            if (!options.relationshipType || !options.from || !options.to)
+                throw new Error("system unrelate requires relationshipType, from, and to");
+            plan = planSystemUnrelate({
+                systemId,
+                type: options.relationshipType,
+                from: options.from,
+                to: options.to,
+                repoPath: repo,
+            });
+        }
+        if (options.apply === true) {
+            if (!options.planDigest)
+                throw new Error("system writes require planDigest from an approved preview");
+            if (options.planDigest !== plan.planDigest)
+                throw new Error("system plan changed after preview; preview again");
+        }
+        return bounded(options.apply === true ? applySystemPlan(plan) : plan, `system:${systemAction}`);
+    }
     const config = await enrichSystemRelationships(loadSystemConfiguration(repo));
     if (systemAction === "list") {
         return bounded({
@@ -859,7 +957,7 @@ async function handleSystemOperation(options) {
     const validation = await validateSystemHealth(config, symbol, async (target) => attachLifecycleHealth(target, await engine.status(target, { audit: "cached" })), repo);
     if (systemAction === "validate")
         return bounded({ systemId: symbol, ...validation }, "system:validate");
-    return bounded(queryConfiguredSystem(config, symbol, allowPartial === true, validation), "system:query");
+    return bounded(queryConfiguredSystem(config, symbol, options.requireComplete === true, validation), "system:query");
 }
 async function handlePullRequestsOperation(options) {
     const { repo, engine, limit, prNumber, prState, branches, auditRange, auditBase, auditHead, expectedLogin, } = options;
@@ -1296,7 +1394,7 @@ async function handleDiagnosticsOperation(repo, args, bounded) {
 async function dispatchKnodinTool(args) {
     const startedAt = performance.now();
     const parsedArgs = (args ?? {});
-    const { operation, symbol, base, diffScope, from, toRevision, reviewFiles, query, pattern, to, limit, depth, impactMode, direction, relationKinds, minConfidence, includeTests, includeDataFlow, flowVariable, apply, force, detailLevel, prNumber, prState, branches, auditRange, auditBase, auditHead, expectedLogin, worktreeAction, worktreePath, telemetryAction, telemetryRetentionDays, task, changedFiles, repoPath, section, systemAction, repositoryAction, roots, linkedWorktrees, cursor, allowPartial, dryRun, manifestPath, identity, file, kind, toIdentity, toFile, toKind, byteBudget, tokenBudget, itemBudget, includeSource, languages, extensions, kinds, path, architectureFacets, testScope, offset, minLines, minComplexity, topN, sort, packAction, format, include, exclude, filePolicies, alreadyPresent, chatFiles, lineNumbers, includeTree, outputPath, artifactPath, startLine, endLine, regex, regexFlags, gitDiffScope, gitLog, statusAudit, timeoutMs, client, repairPlan, persistTelemetry, } = parsedArgs;
+    const { operation, symbol, base, diffScope, from, toRevision, reviewFiles, query, pattern, queries, to, limit, depth, impactMode, direction, relationKinds, minConfidence, includeTests, includeDataFlow, flowVariable, apply, force, detailLevel, prNumber, prState, branches, auditRange, auditBase, auditHead, expectedLogin, worktreeAction, worktreePath, telemetryAction, telemetryRetentionDays, task, changedFiles, repoPath, section, systemAction, repositories, scope, distributed, repositoryIds, components, evidence, relationshipType, requireComplete, repositoryAction, roots, linkedWorktrees, cursor, allowPartial, dryRun, manifestPath, planDigest, identity, file, kind, toIdentity, toFile, toKind, byteBudget, tokenBudget, itemBudget, includeSource, languages, extensions, kinds, path, architectureFacets, testScope, offset, minLines, minComplexity, topN, sort, packAction, format, include, exclude, filePolicies, alreadyPresent, chatFiles, lineNumbers, includeTree, outputPath, artifactPath, startLine, endLine, regex, regexFlags, gitDiffScope, gitLog, statusAudit, timeoutMs, client, repairPlan, persistTelemetry, } = parsedArgs;
     const repo = repoPath ?? process.cwd();
     const selector = {
         identity: expandCompactIdentity(identity),
@@ -1389,7 +1487,10 @@ async function dispatchKnodinTool(args) {
             "search",
         ].includes(rootOperation);
         const enriched = includeSharedIndex && result && typeof result === "object" && !Array.isArray(result)
-            ? { ...result, sharedIndex: sharedIndexEnvelope() }
+            ? {
+                ...result,
+                sharedIndex: sharedIndexEnvelope(),
+            }
             : result;
         const key = `${op}${minimal ? ":minimal" : ""}`;
         const output = applyResponseBudget(enriched, op, budget, RESPONSE_DEFAULTS[key] ?? RESPONSE_DEFAULTS.default);
@@ -1447,11 +1548,16 @@ async function dispatchKnodinTool(args) {
             return engine.status(repo, { audit: statusAudit }).then((result) => bounded({
                 ...attachLifecycleHealth(repo, result),
                 integration: inspectRepositoryIntegrationStatus(repo),
-                update: trustedUpdateStatus({
-                    currentVersion: result.version,
-                    installMethod: "unknown",
-                    env: process.env,
-                }),
+                update: {
+                    ...trustedUpdateStatus({
+                        currentVersion: result.version,
+                        installMethod: "unknown",
+                        env: process.env,
+                    }),
+                    managerState: readManagerUpdateState(),
+                    attention: updateAttention(readManagerUpdateState()),
+                    journal: readUpdateJournal(),
+                },
             }, "status"));
         case "wait":
             return bounded(await waitForFresh(engine, repo, timeoutMs), "wait");
@@ -1519,6 +1625,19 @@ async function dispatchKnodinTool(args) {
                 symbol,
                 repo,
                 allowPartial,
+                apply,
+                repositories,
+                scope,
+                distributed,
+                repositoryIds,
+                components,
+                relationshipType,
+                from,
+                to,
+                evidence,
+                requireComplete,
+                manifestPath,
+                planDigest,
                 bounded,
             });
         }
@@ -1626,6 +1745,39 @@ async function dispatchKnodinTool(args) {
                 expectedLogin,
             }), "prs");
         }
+        case "query_batch": {
+            if (!process.env.KNODIN_UPDATE_VERIFICATION_TOKEN)
+                throw new Error("knodin query_batch is restricted to the isolated update verifier");
+            if (!Array.isArray(queries) || queries.length < 1 || queries.length > 32)
+                throw new Error("knodin query_batch requires 1-32 `queries`");
+            for (const item of queries) {
+                if (!item ||
+                    typeof item.symbol !== "string" ||
+                    item.symbol.length === 0 ||
+                    !BATCH_QUERY_PATTERNS.has(item.pattern))
+                    throw new Error("knodin query_batch accepts only non-empty callers/callees/imports/importers/file-summary queries");
+            }
+            const queryHealth = await inspectGatewayGraphHealth(repo);
+            if (!queryHealth.available)
+                return bounded(queryHealth, "query_batch");
+            const outputs = [];
+            for (const item of queries) {
+                outputs.push({
+                    pattern: item.pattern,
+                    symbol: item.symbol,
+                    output: await engine.query(item.pattern, item.symbol, repo, undefined, Math.min(limit ?? itemBudget ?? 100, itemBudget ?? 1000)),
+                });
+            }
+            const verifiedQueryHealth = await inspectGatewayGraphHealth(repo);
+            if (!verifiedQueryHealth.available)
+                return bounded(verifiedQueryHealth, "query_batch");
+            return bounded({
+                results: outputs.map((item) => ({
+                    ...item,
+                    output: decorateGraphQueryResult(item.output, verifiedQueryHealth.state, verifiedQueryHealth.graph.freshness),
+                })),
+            }, "query_batch");
+        }
         case "query": {
             if (!pattern)
                 throw new Error("knodin query requires `pattern`");

package/dist/src/update-ceremony.js

@@ -40,7 +40,7 @@ export function validateRootCeremonyManifest(value) {
         manifest.productionActivation !== false)
         throw new Error("invalid fail-closed ceremony header");
     if (!Array.isArray(manifest.custodians) ||
-        manifest.custodians.length < 3 ||
+        manifest.custodians.length < 1 ||
         new Set(manifest.custodians.map((c) => c.id)).size !== manifest.custodians.length ||
         manifest.custodians.some((c) => {
             exactKeys(c, c.role === "root-signer"
@@ -54,7 +54,7 @@ export function validateRootCeremonyManifest(value) {
                         !Array.isArray(c.recoveryKeyIds) ||
                         c.recoveryKeyIds.some((id) => !SHA256.test(id)))));
         }))
-        throw new Error("at least three distinct named custodians are required");
+        throw new Error("at least one named maintainer custodian is required");
     const roles = ["root", "targets", "snapshot", "timestamp"];
     exactKeys(manifest.roleKeyIds, roles, "roleKeyIds");
     exactKeys(manifest.thresholds, roles, "thresholds");
@@ -68,14 +68,11 @@ export function validateRootCeremonyManifest(value) {
             throw new Error("role keys must be valid and disjoint");
         for (const id of ids)
             all.add(id);
-        if (!Number.isInteger(threshold) ||
-            threshold < (role === "root" || role === "targets" ? 2 : 1) ||
-            threshold > ids.length)
+        if (!Number.isInteger(threshold) || threshold < 1 || threshold > ids.length)
             throw new Error(`invalid ${role} threshold`);
     }
-    if (manifest.custodians.filter((c) => c.role === "root-signer").length < manifest.thresholds.root ||
-        !manifest.custodians.some((c) => c.role === "recovery"))
-        throw new Error("custodian roles do not satisfy threshold and recovery separation");
+    if (manifest.custodians.filter((c) => c.role === "root-signer").length < manifest.thresholds.root)
+        throw new Error("maintainer custodians do not satisfy the root threshold");
     const assigned = manifest.custodians
         .filter((c) => c.role === "root-signer")
         .map((c) => c.publicKeyId)
@@ -85,15 +82,9 @@ export function validateRootCeremonyManifest(value) {
     if (assigned.join("\0") !== [...manifest.roleKeyIds.root].sort(compareBytes).join("\0"))
         throw new Error("root signer assignments must exactly match root role keys");
     const recovery = manifest.custodians.filter((c) => c.role === "recovery");
-    if (recovery.length < manifest.thresholds.root ||
-        new Set(recovery.map((c) => c.evidenceId)).size !== recovery.length ||
-        recovery.some((c) => !c.recoveryKeyIds?.length ||
-            new Set(c.recoveryKeyIds).size !== c.recoveryKeyIds.length ||
-            c.recoveryKeyIds.length >= manifest.thresholds.root))
-        throw new Error("recovery sets must preserve root threshold independence");
-    const recovered = new Set(recovery.flatMap((c) => c.recoveryKeyIds ?? []));
-    if (manifest.roleKeyIds.root.some((id) => !recovered.has(id)))
-        throw new Error("recovery assignments must cover every root role key");
+    if (new Set(recovery.map((c) => c.evidenceId)).size !== recovery.length ||
+        recovery.some((c) => !c.recoveryKeyIds?.length || new Set(c.recoveryKeyIds).size !== c.recoveryKeyIds.length))
+        throw new Error("recovery assignments must be unique and non-empty when declared");
     return manifest;
 }
 export function validateRootPinReviewReceipt(value, manifest) {
@@ -115,20 +106,21 @@ export function validateRootPinReviewReceipt(value, manifest) {
         receipt.ceremonyId !== manifest.ceremonyId ||
         !SHA256.test(receipt.rootEnvelopeSha256) ||
         !ID.test(receipt.reviewerId) ||
-        manifest.custodians.some((c) => c.id === receipt.reviewerId) ||
         receipt.decision !== "approved" ||
-        receipt.authentication !== "rehearsal-unsigned" ||
+        (manifest.purpose === "rehearsal"
+            ? receipt.authentication !== "rehearsal-unsigned" ||
+                manifest.custodians.some((c) => c.id === receipt.reviewerId)
+            : receipt.authentication !== "maintainer-attested" ||
+                !manifest.custodians.some((c) => c.id === receipt.reviewerId)) ||
         receipt.productionActivation !== false ||
         !Number.isFinite(Date.parse(receipt.reviewedAt)) ||
         new Date(receipt.reviewedAt).toISOString() !== receipt.reviewedAt)
-        throw new Error("invalid or non-independent pin-review receipt");
+        throw new Error("invalid root-pin attestation receipt");
     return receipt;
 }
 export function preparePublicRootImport(envelope, pin, manifestValue, receiptValue, now = new Date()) {
     rejectPrivateMaterial(envelope, "rootEnvelope");
     const manifest = validateRootCeremonyManifest(manifestValue);
-    if (manifest.purpose === "production")
-        throw new Error("production import requires externally authenticated review and remains blocked");
     const receipt = validateRootPinReviewReceipt(receiptValue, manifest);
     if (Date.parse(receipt.reviewedAt) > now.getTime())
         throw new Error("pin-review receipt cannot be future-dated");
@@ -156,7 +148,11 @@ export function preparePublicRootImport(envelope, pin, manifestValue, receiptVal
     }
     const digest = createHash("sha256").update(canonicalizeUpdateMetadata(envelope)).digest("hex");
     if (pin !== digest || receipt.rootEnvelopeSha256 !== digest)
-        throw new Error("root envelope, pin, and independent review receipt disagree");
+        throw new Error("root envelope, pin, and maintainer attestation disagree");
     verifyUpdateRootChain(envelope, pin, [], now);
-    return { rootEnvelope: envelope, rootEnvelopeSha256: digest, productionActivation: false };
+    return {
+        rootEnvelope: envelope,
+        rootEnvelopeSha256: digest,
+        productionActivation: false,
+    };
 }

package/dist/src/update-coordination.js

@@ -0,0 +1,158 @@
+import { execFileSync } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { readUpdateJournal } from "./manager-update.js";
+function coordinationRoot(stateHome) {
+    const root = stateHome ?? process.env.XDG_STATE_HOME ?? path.join(os.homedir(), ".local", "state");
+    return path.join(root, "knodin", "coordination");
+}
+function processStartToken(pid) {
+    try {
+        if (process.platform === "win32") {
+            return execFileSync("powershell.exe", ["-NoProfile", "-Command", `(Get-Process -Id ${pid}).StartTime.ToUniversalTime().Ticks`], { encoding: "utf8", timeout: 2_000 }).trim();
+        }
+        return execFileSync("ps", ["-o", "lstart=", "-p", String(pid)], {
+            encoding: "utf8",
+            timeout: 2_000,
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+function readLease(file) {
+    try {
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 64 * 1024)
+            return null;
+        const value = JSON.parse(fs.readFileSync(file, "utf8"));
+        return value.schemaVersion === 1 && typeof value.nonce === "string" ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+function live(record) {
+    return Boolean(record && processStartToken(record.pid) === record.processStartToken);
+}
+function writeExclusive(file, record) {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const descriptor = fs.openSync(file, "wx", 0o600);
+    try {
+        fs.writeFileSync(descriptor, `${JSON.stringify(record)}\n`, "utf8");
+        fs.fsyncSync(descriptor);
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+}
+function releaseOwned(file, nonce) {
+    const current = readLease(file);
+    if (current?.nonce !== nonce)
+        return;
+    try {
+        fs.unlinkSync(file);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+function updateLeaseFile(stateHome) {
+    return path.join(coordinationRoot(stateHome), "update.lock");
+}
+function lifecycleDirectory(stateHome) {
+    return path.join(coordinationRoot(stateHome), "lifecycle");
+}
+function tokenHash(token) {
+    return createHash("sha256").update(token).digest("hex");
+}
+function activeLifecycleLeases(stateHome) {
+    const directory = lifecycleDirectory(stateHome);
+    let names = [];
+    try {
+        names = fs.readdirSync(directory).slice(0, 4096);
+    }
+    catch {
+        return [];
+    }
+    const active = [];
+    for (const name of names) {
+        const file = path.join(directory, name);
+        const record = readLease(file);
+        if (live(record))
+            active.push(record);
+        else
+            releaseOwned(file, record?.nonce ?? "");
+    }
+    return active;
+}
+export function acquireLifecycleCoordination(options) {
+    const updateFile = updateLeaseFile(options.stateHome);
+    const update = readLease(updateFile);
+    if (live(update)) {
+        const permitted = options.verificationToken &&
+            update?.verificationTokenHash === tokenHash(options.verificationToken);
+        if (!permitted)
+            throw new Error("an executable update is active; retry lifecycle work after it completes");
+    }
+    else if (update) {
+        const journal = readUpdateJournal(options.stateHome);
+        if (journal && !["candidate-verified", "rollback-verified"].includes(journal.state)) {
+            throw new Error(`an interrupted update is ${journal.state}; run \`knodin update status\` to recover it`);
+        }
+        releaseOwned(updateFile, update.nonce);
+    }
+    const nonce = randomUUID();
+    const record = {
+        schemaVersion: 1,
+        kind: "lifecycle",
+        nonce,
+        pid: process.pid,
+        processStartToken: processStartToken(process.pid) ?? "unavailable",
+        command: options.command,
+        repository: fs.realpathSync(options.repository),
+        startedAt: new Date().toISOString(),
+    };
+    const file = path.join(lifecycleDirectory(options.stateHome), `${process.pid}-${nonce}.json`);
+    writeExclusive(file, record);
+    return { record, release: () => releaseOwned(file, nonce) };
+}
+export function acquireExclusiveUpdateCoordination(options) {
+    const active = activeLifecycleLeases(options.stateHome);
+    if (active.length > 0) {
+        throw new Error(`executable replacement deferred while ${active.length} lifecycle operation(s) are active`);
+    }
+    const file = updateLeaseFile(options.stateHome);
+    const existing = readLease(file);
+    if (live(existing))
+        throw new Error("another executable update is active");
+    if (existing) {
+        const journal = readUpdateJournal(options.stateHome);
+        if (journal &&
+            !["candidate-verified", "rollback-verified"].includes(journal.state) &&
+            !options.recovery) {
+            throw new Error(`interrupted update recovery required from journal state ${journal.state}`);
+        }
+        releaseOwned(file, existing.nonce);
+    }
+    const nonce = randomUUID();
+    const record = {
+        schemaVersion: 1,
+        kind: "update",
+        nonce,
+        pid: process.pid,
+        processStartToken: processStartToken(process.pid) ?? "unavailable",
+        command: "update",
+        startedAt: new Date().toISOString(),
+        verificationTokenHash: tokenHash(options.verificationToken),
+    };
+    writeExclusive(file, record);
+    return { record, release: () => releaseOwned(file, nonce) };
+}
+export function coordinationStatus(stateHome) {
+    const update = readLease(updateLeaseFile(stateHome));
+    return { update: live(update) ? update : null, lifecycle: activeLifecycleLeases(stateHome) };
+}