@martinloop/mcp 0.7.0 → 0.8.0

package/dist/vendor/core/index.js

@@ -16,6 +16,7 @@ import { verifierActuallyPassed, } from "./verified-handoff.js";
 export { DEFAULT_AGENT_EXECUTION_INTENT, DEFAULT_PROVIDER_EXECUTION_TIMEOUT_MS, GOVERNED_AUTONOMOUS_BOUNDARY, normalizeProviderExecutionTimeoutMs } from "../contracts/index.js";
 export { classifyFailure, computeEvidenceVector, evaluatePatchDecision, evaluateCostGovernor, evaluateBudgetPreflight, inferExit, nextPolicyPhase, policyPhaseToLifecycleState, scorePatchDecision, selectRecoveryRecipe, evaluateVerificationLeash, evaluateFilesystemLeash, evaluateChangeApprovalLeash, evaluateSecretLeash, resolveExecutionProfile, redactSecretsFromText, buildRepoGroundingIndex, loadOrBuildRepoGroundingIndex, queryRepoGroundingIndex, scanPatchForGroundingViolations, captureRollbackBoundary, listAttemptChangedFilesSinceBoundary, restoreRollbackBoundary };
 export { buildContextGraphSnapshot, queryContextGraph } from "./context-graph.js";
+export { ExternalOutcomeContractError, ExternalOutcomePolicyError, hashExternalOutcomeContract, verifyExternalOutcomes, writeExternalOutcomeEvidence, } from "./external-outcome.js";
 export { createLocalIdentityAuthority, hasIdentityScope, issueIdentityToken, verifyIdentityToken } from "./identity.js";
 export { compileExecutionPolicy } from "./policy-compiler.js";
 export { assessTrajectory, decideCircuitBreak } from "./trajectory.js";
@@ -401,6 +402,34 @@ export async function runMartin(input) {
             }
         }
     }
+    let parentAbortObserved = false;
+    function observeParentAbort() {
+        if (parentAbortObserved || input.signal === undefined)
+            return;
+        parentAbortObserved = true;
+        const reason = input.signal.reason instanceof Error
+            ? input.signal.reason.message
+            : typeof input.signal.reason === "string"
+                ? input.signal.reason
+                : "parent cancelled governed child run";
+        const parentSignal = {
+            kind: "human_interrupt",
+            schemaVersion: "exit-signal/1",
+            runId: loop.loopId,
+            reason: `Parent cancellation: ${reason}`,
+            requestedAt: now(),
+            requestedBy: "parent_swarm"
+        };
+        observeSignals([parentSignal]);
+        activeAttemptController?.abort(input.signal.reason ?? parentSignal);
+    }
+    if (input.signal?.aborted)
+        observeParentAbort();
+    else if (input.signal) {
+        input.signal.addEventListener("abort", observeParentAbort, { once: true });
+        if (input.signal.aborted)
+            observeParentAbort();
+    }
     function queueControlDiagnostic(code, details) {
         if (!input.store)
             return;
@@ -443,6 +472,7 @@ export async function runMartin(input) {
         // snapshot. Draining alone leaves a window for new writes during signing.
         disposeSignalMonitor();
         runController.abort();
+        input.signal?.removeEventListener("abort", observeParentAbort);
         await Promise.all(pendingControlWrites.splice(0));
     }
     // Snapshot of the current run state for eight-exit evaluation
@@ -753,6 +783,7 @@ export async function runMartin(input) {
                         ? { definitionOfDonePreSatisfied: loop.task.definitionOfDonePreSatisfied }
                         : {}),
                     ...(loop.task.repoRoot ? { repoRoot: loop.task.repoRoot } : {}),
+                    ...(input.store?.runsRoot ? { runsRoot: input.store.runsRoot } : {}),
                     ...(loop.task.allowedPaths ? { allowedPaths: loop.task.allowedPaths } : {}),
                     ...(loop.task.deniedPaths ? { deniedPaths: loop.task.deniedPaths } : {}),
                     ...(loop.task.acceptanceCriteria ? { acceptanceCriteria: loop.task.acceptanceCriteria } : {}),
@@ -766,9 +797,13 @@ export async function runMartin(input) {
                     focus: distilled.focus,
                     remainingBudgetUsd: distilled.constraints.remainingBudgetUsd,
                     remainingIterations: distilled.constraints.remainingIterations,
-                    remainingTokens: distilled.constraints.remainingTokens
+                    remainingTokens: distilled.constraints.remainingTokens,
+                    ...(input.verificationExecutionOwner
+                        ? { verificationExecutionOwner: input.verificationExecutionOwner }
+                        : {})
                 },
-                previousAttempts: loop.attempts
+                previousAttempts: loop.attempts,
+                ...(input.observedUsageGovernor ? { observedUsageGovernor: input.observedUsageGovernor } : {})
             };
             const tracksWorkspaceMutations = request.context.repoRoot !== undefined &&
                 executingAdapter.metadata.capabilities?.workspaceMutations !== false;
@@ -996,7 +1031,8 @@ export async function runMartin(input) {
                 repoRoot: request.context.repoRoot,
                 changedFiles,
                 allowedPaths: request.context.allowedPaths,
-                deniedPaths: request.context.deniedPaths
+                deniedPaths: request.context.deniedPaths,
+                mutationMode: request.context.mutationMode
             });
             if (!filesystemDecision.allowed) {
                 const patchDecision = evaluatePatchDecision({
@@ -1412,6 +1448,7 @@ export async function runMartin(input) {
             clearTimeout(wallTimer);
         disposeSignalMonitor();
         runController.abort();
+        input.signal?.removeEventListener("abort", observeParentAbort);
         activeAttemptController?.abort();
         // Flush any diagnostic ledger writes queued from signal callbacks
         await Promise.all(pendingControlWrites);
@@ -1581,6 +1618,9 @@ function resolveChangedFiles(result, repoRoot, rollbackBoundary) {
     return listAttemptChangedFilesSinceBoundary({ repoRoot, boundary: rollbackBoundary });
 }
 function buildPatchDiff(result, changedFiles) {
+    if (result.execution?.patch) {
+        return result.execution.patch;
+    }
     // Use structured diff stats to build a minimal diff header if no raw diff is available
     if (result.execution?.changedFiles?.length) {
         // Build a synthetic diff header from changed file list
@@ -1663,7 +1703,11 @@ function resolveExpectedVerifierBinding(request) {
     return {
         runId: request.loopId,
         workspaceId: request.workspaceId,
+        attemptId: request.attemptId,
         cwd: request.context.repoRoot ?? process.cwd(),
+        ...(request.context.runsRoot ? { runsRoot: request.context.runsRoot } : {}),
+        ...(request.context.executionProfile ? { executionProfile: request.context.executionProfile } : {}),
+        ...(request.context.allowedNetworkDomains?.length ? { allowedNetworkDomains: [...request.context.allowedNetworkDomains] } : {}),
         commands,
     };
 }
@@ -1806,3 +1850,9 @@ export { createDefaultExitPolicy, evaluateExitPolicy, hashProgressState, toLegac
 export { SignalDiagnosticError, createFileExitSignalSource, exitSignalPath, readAllExitSignals, readExitSignal, startExitSignalMonitor, writeExitSignal } from "./exit-signal.js";
 // ─── R4 Delivery ─────────────────────────────────────────────────────────────
 export { cacheMessage, fetchSelectedMessage, getCliInstalledVersion, getMcpInstalledVersion, isCooldownExpired, isDismissed, isNewerVersion, loadDeliveryRecord, parseMessageSelectionResponse, recordDismissed, recordShown, resolveDefaultLedgerPath, saveDeliveryRecord, } from "./delivery/index.js";
+export { completeDeterministicDemoSwarmRun, createSwarmBudgetLedger, extendSwarmBudgetLease, releaseSwarmBudgetLease, reserveSwarmBudgetLease, selectNextSwarmBatch, settleSwarmBudgetLease, tasksHaveScopeCollision, validateSwarmTaskGraph, runParentSwarmPipeline } from "./swarm/index.js";
+export { readSwarmOperationalState } from "./swarm/operational-reader.js";
+export { readSwarmReceiptProjection, verifySwarmReceiptProjection, } from "./swarm/receipt-projection.js";
+export { buildSwarmShareProjection, readSwarmDossier, verifySwarmEvidence, } from "./swarm/evidence-projection.js";
+export { buildSwarmHostedEnvelope } from "./swarm/hosted-export.js";
+export { assertSwarmPathIdentifier } from "./swarm/workspaces.js";

package/dist/vendor/core/leash.d.ts

@@ -32,6 +32,7 @@ export declare function evaluateFilesystemLeash(input: {
     changedFiles: string[];
     allowedPaths?: string[];
     deniedPaths?: string[];
+    mutationMode?: "edit" | "read_only" | "verify_only";
 }): SafetyLeashDecision;
 export declare function evaluateSecretLeash(input: {
     values: string[];

package/dist/vendor/core/leash.js

@@ -52,6 +52,11 @@ function commandContainsDestructiveRemoval(command) {
     return false;
 }
 const SECRET_PATTERNS = [
+    {
+        kind: "secret_value",
+        pattern: /\bBearer\s+[A-Za-z0-9._~+/=-]{12,}\b/giu,
+        replacement: "Bearer [REDACTED_SECRET]"
+    },
     {
         kind: "secret_value",
         pattern: /\bOPENAI_API_KEY\s*=\s*[^\s"'`]+/giu,
@@ -196,6 +201,14 @@ export function evaluateFilesystemLeash(input) {
         if (!file) {
             continue;
         }
+        if (input.mutationMode === "read_only") {
+            violations.push({
+                kind: "path_not_allowed",
+                file,
+                message: `Read-only execution changed a file: ${file}`
+            });
+            continue;
+        }
         if ((input.deniedPaths ?? []).some((pattern) => matchesPathPattern(file, pattern))) {
             violations.push({
                 kind: "path_denied",

package/dist/vendor/core/persistence/integrity.d.ts

@@ -37,3 +37,7 @@ export declare function verifyReceiptIntegrityFromFiles(input: {
     ledgerPath: string;
 }): Promise<ReceiptIntegritySummary>;
 export declare function resolveReceiptIntegrityPath(runsRoot: string, runId: string): string;
+export declare function ensurePrivateIntegrityKey(runsRoot: string, keyFileName: string): Promise<[string, string] | undefined>;
+export declare function readPrivateIntegrityKey(runsRoot: string, keyFileName: string): Promise<string>;
+export declare function resolvePrivateIntegrityKeyPath(runsRoot: string, keyFileName: string): string;
+export declare function createPrivateIntegrityHmac(key: string, material: unknown): string;

package/dist/vendor/core/persistence/integrity.js

@@ -1,5 +1,5 @@
 import { createHash, createHmac, randomBytes } from "node:crypto";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { lstat, mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 const RECEIPT_INTEGRITY_SCHEMA_VERSION = "martin.receipt-integrity.v1";
@@ -208,10 +208,17 @@ function buildReceiptIntegrityChain(entries) {
     });
 }
 function createReceiptIntegritySignature(key, material) {
-    return createHmac("sha256", key).update(JSON.stringify(material)).digest("hex");
+    return createPrivateIntegrityHmac(key, material);
 }
 async function ensureReceiptIntegrityKey(runsRoot, runId) {
-    const keyPath = resolveReceiptIntegrityKeyPath(runsRoot, runId);
+    return ensurePrivateIntegrityKey(runsRoot, `${runId}.key`);
+}
+export async function ensurePrivateIntegrityKey(runsRoot, keyFileName) {
+    const keyPath = resolvePrivateIntegrityKeyPath(runsRoot, keyFileName);
+    const existingStat = await lstat(keyPath).catch(() => undefined);
+    if (existingStat?.isSymbolicLink() || (existingStat && !existingStat.isFile())) {
+        return undefined;
+    }
     const existing = await readFile(keyPath, "utf8").catch(() => null);
     if (existing) {
         const trimmed = existing.trim();
@@ -231,12 +238,18 @@ async function ensureReceiptIntegrityKey(runsRoot, runId) {
     return [generated, sha256(generated).slice(0, 16)];
 }
 async function readReceiptIntegrityKey(runsRoot, runId) {
-    const raw = await readFile(resolveReceiptIntegrityKeyPath(runsRoot, runId), "utf8");
+    return readPrivateIntegrityKey(runsRoot, `${runId}.key`);
+}
+export async function readPrivateIntegrityKey(runsRoot, keyFileName) {
+    const raw = await readFile(resolvePrivateIntegrityKeyPath(runsRoot, keyFileName), "utf8");
     return raw.trim();
 }
-function resolveReceiptIntegrityKeyPath(runsRoot, runId) {
+export function resolvePrivateIntegrityKeyPath(runsRoot, keyFileName) {
     const rootHash = sha256(runsRoot).slice(0, 16);
-    return join(resolveReceiptIntegrityRoot(), rootHash, `${runId}.key`);
+    return join(resolveReceiptIntegrityRoot(), rootHash, keyFileName);
+}
+export function createPrivateIntegrityHmac(key, material) {
+    return createHmac("sha256", key).update(JSON.stringify(material)).digest("hex");
 }
 function serializeStoredJson(value) {
     return `${JSON.stringify(value, null, 2)}\n`;

package/dist/vendor/core/persistence/swarm-integrity.d.ts

@@ -0,0 +1,63 @@
+declare const SWARM_RECEIPT_INTEGRITY_SCHEMA_VERSION: "martin.swarm-receipt-integrity.v1";
+export interface SwarmReceiptIntegrityArtifact {
+    path: string;
+    sha256: string;
+    bytes: number;
+}
+export interface StoredSwarmReceiptIntegrityMaterial {
+    schemaVersion: typeof SWARM_RECEIPT_INTEGRITY_SCHEMA_VERSION;
+    swarmId: string;
+    planHash: string;
+    receiptSchemaVersion: string;
+    receiptSha256: string;
+    evidenceIndexSha256: string;
+    eventChainHead: string;
+    rootBindingSha256: string;
+    keyId: string;
+    signedAt: string;
+    taskVerificationState: "passed" | "failed" | "unknown";
+    artifacts: SwarmReceiptIntegrityArtifact[];
+    signatureHmacSha256: string;
+}
+export interface SwarmReceiptIntegritySummary {
+    state: "verified" | "material_missing" | "tamper_detected";
+    taskVerificationState?: "passed" | "failed" | "unknown";
+    keyId?: string;
+    signedAt?: string;
+    receiptSha256?: string;
+    evidenceIndexSha256?: string;
+    eventChainHead?: string;
+    reason?: string;
+}
+export interface SwarmReceiptSealCommitBase {
+    schemaVersion: "martin.swarm-receipt-seal.v1";
+    swarmId: string;
+    planHash: string;
+    receiptSha256: string;
+    evidenceIndexSha256: string;
+    integrityMaterialSha256: string;
+    committedAt: string;
+}
+export declare function authenticateSwarmReceiptSealCommit(input: {
+    runsRoot: string;
+    swarmId: string;
+    commit: SwarmReceiptSealCommitBase;
+}): Promise<string>;
+export declare function verifySwarmReceiptSealCommitAuthentication(input: {
+    runsRoot: string;
+    swarmId: string;
+    commit: SwarmReceiptSealCommitBase & {
+        commitHmacSha256?: string;
+    };
+}): Promise<boolean>;
+export declare function writeSwarmReceiptIntegrityMaterial(input: {
+    runsRoot: string;
+    swarmId: string;
+    signedAt?: string;
+}): Promise<StoredSwarmReceiptIntegrityMaterial | undefined>;
+export declare function verifySwarmReceiptIntegrityFromFiles(input: {
+    runsRoot: string;
+    swarmId: string;
+}): Promise<SwarmReceiptIntegritySummary>;
+export declare function resolveSwarmReceiptIntegrityPath(runsRoot: string, swarmId: string): string;
+export {};

package/dist/vendor/core/persistence/swarm-integrity.js

@@ -0,0 +1,309 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import { lstat, open, readFile, realpath } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { verifyParentSwarmReceipt } from "../swarm/parent-receipt.js";
+import { assertSwarmPathIdentifier } from "../swarm/workspaces.js";
+import { createPrivateIntegrityHmac, ensurePrivateIntegrityKey, readPrivateIntegrityKey } from "./integrity.js";
+const SWARM_RECEIPT_INTEGRITY_SCHEMA_VERSION = "martin.swarm-receipt-integrity.v1";
+export async function authenticateSwarmReceiptSealCommit(input) {
+    const runsRoot = await realpath(resolve(input.runsRoot));
+    const key = await readPrivateIntegrityKey(runsRoot, keyFileName(input.swarmId));
+    if (!key)
+        throw new Error("SWARM_SEAL_KEY_UNAVAILABLE");
+    return createPrivateIntegrityHmac(key, sealAuthenticationBase(runsRoot, input.commit));
+}
+export async function verifySwarmReceiptSealCommitAuthentication(input) {
+    const runsRoot = await realpath(resolve(input.runsRoot));
+    const key = await readPrivateIntegrityKey(runsRoot, keyFileName(input.swarmId));
+    if (!key || typeof input.commit.commitHmacSha256 !== "string")
+        return false;
+    const { commitHmacSha256, ...commit } = input.commit;
+    const expected = createPrivateIntegrityHmac(key, sealAuthenticationBase(runsRoot, commit));
+    return constantTimeHexEqual(commitHmacSha256, expected);
+}
+export async function writeSwarmReceiptIntegrityMaterial(input) {
+    const bundle = await resolveCanonicalSwarmIntegrityBundle(input.runsRoot, input.swarmId);
+    const receipt = parseParentReceipt(bundle.receiptRaw);
+    const evidenceIndex = parseEvidenceIndex(bundle.indexRaw);
+    validateArtifactIdentities(input.swarmId, receipt, evidenceIndex, bundle.indexRaw, bundle.eventsRaw);
+    const keyMaterial = await ensurePrivateIntegrityKey(bundle.runsRoot, keyFileName(input.swarmId));
+    if (!keyMaterial)
+        return undefined;
+    const [key, keyId] = keyMaterial;
+    const artifacts = canonicalArtifactManifest(bundle);
+    const base = {
+        schemaVersion: SWARM_RECEIPT_INTEGRITY_SCHEMA_VERSION,
+        swarmId: input.swarmId,
+        planHash: receipt.planHash,
+        receiptSchemaVersion: receipt.schemaVersion,
+        receiptSha256: receipt.receiptSha256,
+        evidenceIndexSha256: sha256(bundle.indexRaw),
+        eventChainHead: sha256(bundle.eventsRaw),
+        rootBindingSha256: sha256(bundle.runsRoot),
+        keyId,
+        signedAt: input.signedAt ?? new Date().toISOString(),
+        taskVerificationState: receipt.taskVerificationState,
+        artifacts
+    };
+    const material = {
+        ...base,
+        signatureHmacSha256: createPrivateIntegrityHmac(key, base)
+    };
+    await writeExactOnce(bundle.integrityPath, serializeJson(material));
+    return material;
+}
+export async function verifySwarmReceiptIntegrityFromFiles(input) {
+    let bundle;
+    try {
+        bundle = await resolveCanonicalSwarmIntegrityBundle(input.runsRoot, input.swarmId);
+    }
+    catch {
+        return { state: "material_missing", reason: "canonical_swarm_bundle_missing" };
+    }
+    const [materialRaw, key] = await Promise.all([
+        readFile(bundle.integrityPath, "utf8").catch(() => null),
+        readPrivateIntegrityKey(bundle.runsRoot, keyFileName(input.swarmId)).catch(() => null)
+    ]);
+    if (!materialRaw || !key) {
+        return { state: "material_missing", reason: "swarm_receipt_integrity_material_incomplete" };
+    }
+    let material;
+    let receipt;
+    let evidenceIndex;
+    try {
+        material = JSON.parse(materialRaw);
+        receipt = parseParentReceipt(bundle.receiptRaw);
+        evidenceIndex = parseEvidenceIndex(bundle.indexRaw);
+        validateArtifactIdentities(input.swarmId, receipt, evidenceIndex, bundle.indexRaw, bundle.eventsRaw);
+    }
+    catch {
+        return { state: "tamper_detected", reason: "malformed_integrity_or_artifact_material" };
+    }
+    const actualArtifacts = canonicalArtifactManifest(bundle);
+    if (!validMaterialShape(material) || !sameManifest(material.artifacts, actualArtifacts)) {
+        return tamper(material, "artifact_manifest_mismatch");
+    }
+    if (material.rootBindingSha256 !== sha256(bundle.runsRoot)) {
+        return tamper(material, "root_binding_mismatch");
+    }
+    if (material.swarmId !== input.swarmId
+        || material.planHash !== receipt.planHash
+        || material.receiptSchemaVersion !== receipt.schemaVersion
+        || material.receiptSha256 !== receipt.receiptSha256
+        || material.evidenceIndexSha256 !== sha256(bundle.indexRaw)
+        || material.eventChainHead !== sha256(bundle.eventsRaw)
+        || material.taskVerificationState !== receipt.taskVerificationState) {
+        return tamper(material, "canonical_binding_mismatch");
+    }
+    const { signatureHmacSha256, ...base } = material;
+    const expected = createPrivateIntegrityHmac(key, base);
+    if (!constantTimeHexEqual(signatureHmacSha256, expected)) {
+        return tamper(material, "signature_mismatch");
+    }
+    return {
+        state: "verified",
+        taskVerificationState: receipt.taskVerificationState,
+        keyId: material.keyId,
+        signedAt: material.signedAt,
+        receiptSha256: material.receiptSha256,
+        evidenceIndexSha256: material.evidenceIndexSha256,
+        eventChainHead: material.eventChainHead
+    };
+}
+export function resolveSwarmReceiptIntegrityPath(runsRoot, swarmId) {
+    assertSwarmPathIdentifier(swarmId, "swarm ID");
+    return join(runsRoot, "_swarms", swarmId, "evidence", "swarm-receipt-integrity.json");
+}
+async function resolveCanonicalSwarmIntegrityBundle(runsRootInput, swarmId) {
+    assertSwarmPathIdentifier(swarmId, "swarm ID");
+    const runsRoot = await realpath(resolve(runsRootInput));
+    const swarmsRoot = await resolveExactDirectory(runsRoot, join(runsRoot, "_swarms"));
+    assertContained(runsRoot, swarmsRoot);
+    const swarmRoot = await resolveExactDirectory(swarmsRoot, join(swarmsRoot, swarmId));
+    assertContained(swarmsRoot, swarmRoot);
+    const evidenceRoot = await resolveExactDirectory(swarmRoot, join(swarmRoot, "evidence"));
+    assertContained(swarmRoot, evidenceRoot);
+    const receiptPath = await resolveExactRegularFile(evidenceRoot, join(evidenceRoot, "parent-receipt.json"));
+    const indexPath = await resolveExactRegularFile(evidenceRoot, join(evidenceRoot, "evidence-index.json"));
+    const eventsPath = await resolveExactRegularFile(swarmRoot, join(swarmRoot, "events.jsonl"));
+    assertContained(evidenceRoot, receiptPath);
+    assertContained(evidenceRoot, indexPath);
+    assertContained(swarmRoot, eventsPath);
+    const [receiptRaw, indexRaw, eventsRaw] = await Promise.all([
+        readFile(receiptPath, "utf8"),
+        readFile(indexPath, "utf8"),
+        readFile(eventsPath, "utf8")
+    ]);
+    return {
+        runsRoot,
+        swarmRoot,
+        evidenceRoot,
+        integrityPath: join(evidenceRoot, "swarm-receipt-integrity.json"),
+        receiptRaw,
+        indexRaw,
+        eventsRaw
+    };
+}
+function canonicalArtifactManifest(bundle) {
+    return [
+        { path: "evidence/evidence-index.json", sha256: sha256(bundle.indexRaw), bytes: Buffer.byteLength(bundle.indexRaw) },
+        { path: "evidence/parent-receipt.json", sha256: sha256(bundle.receiptRaw), bytes: Buffer.byteLength(bundle.receiptRaw) }
+    ];
+}
+function parseParentReceipt(raw) {
+    const receipt = JSON.parse(raw);
+    if (verifyParentSwarmReceipt(receipt).ok !== true) {
+        throw new Error("INVALID_PARENT_SWARM_RECEIPT");
+    }
+    return receipt;
+}
+function parseEvidenceIndex(raw) {
+    const value = JSON.parse(raw);
+    if (!isRecord(value) || value.schemaVersion !== "martin.swarm-evidence-index.v1") {
+        throw new Error("INVALID_SWARM_EVIDENCE_INDEX");
+    }
+    return value;
+}
+function validateArtifactIdentities(swarmId, receipt, evidenceIndex, indexRaw, eventsRaw) {
+    if (receipt.swarmId !== swarmId
+        || evidenceIndex.swarmId !== swarmId
+        || evidenceIndex.planHash !== receipt.planHash) {
+        throw new Error("SWARM_ARTIFACT_IDENTITY_MISMATCH");
+    }
+    if (receipt.evidenceIndexSha256 !== sha256(indexRaw)
+        || stableJson(receipt.evidenceFiles) !== stableJson(evidenceIndex.files)
+        || `${receipt.events.map((event) => JSON.stringify(event)).join("\n")}\n` !== eventsRaw) {
+        throw new Error("SWARM_ARTIFACT_RELATION_MISMATCH");
+    }
+}
+async function resolveExactDirectory(parent, expected) {
+    const metadata = await lstat(expected);
+    if (metadata.isSymbolicLink() || !metadata.isDirectory())
+        throw new Error("SWARM_INTEGRITY_PATH_ALIAS");
+    const canonical = await realpath(expected);
+    assertContained(parent, canonical);
+    if (!sameFilesystemPath(canonical, resolve(expected)))
+        throw new Error("SWARM_INTEGRITY_PATH_ALIAS");
+    return canonical;
+}
+async function resolveExactRegularFile(parent, expected) {
+    const metadata = await lstat(expected);
+    if (metadata.isSymbolicLink() || !metadata.isFile())
+        throw new Error("SWARM_INTEGRITY_PATH_ALIAS");
+    const canonical = await realpath(expected);
+    assertContained(parent, canonical);
+    if (!sameFilesystemPath(canonical, resolve(expected)))
+        throw new Error("SWARM_INTEGRITY_PATH_ALIAS");
+    return canonical;
+}
+function sealAuthenticationBase(runsRoot, commit) {
+    return {
+        purpose: "martin.swarm-receipt-seal-commit.v1",
+        rootBindingSha256: sha256(runsRoot),
+        ...commit
+    };
+}
+function sameFilesystemPath(left, right) {
+    return process.platform === "win32" ? left.toLowerCase() === right.toLowerCase() : left === right;
+}
+function stableJson(value) {
+    return JSON.stringify(canonicalize(value));
+}
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (!isRecord(value))
+        return value;
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonicalize(value[key])]));
+}
+function validMaterialShape(value) {
+    return value.schemaVersion === SWARM_RECEIPT_INTEGRITY_SCHEMA_VERSION
+        && typeof value.signatureHmacSha256 === "string"
+        && typeof value.keyId === "string"
+        && typeof value.signedAt === "string"
+        && Array.isArray(value.artifacts);
+}
+function sameManifest(stored, actual) {
+    if (stored.length !== actual.length)
+        return false;
+    const seen = new Set();
+    return stored.every((entry, index) => {
+        if (entry.path.includes("..") || entry.path.includes("\\") || seen.has(entry.path))
+            return false;
+        seen.add(entry.path);
+        const expected = actual[index];
+        return expected !== undefined
+            && entry.path === expected.path
+            && entry.sha256 === expected.sha256
+            && entry.bytes === expected.bytes;
+    });
+}
+function tamper(material, reason) {
+    return {
+        state: "tamper_detected",
+        ...(typeof material.taskVerificationState === "string"
+            ? { taskVerificationState: material.taskVerificationState }
+            : {}),
+        ...(typeof material.keyId === "string" ? { keyId: material.keyId } : {}),
+        ...(typeof material.signedAt === "string" ? { signedAt: material.signedAt } : {}),
+        reason
+    };
+}
+function constantTimeHexEqual(left, right) {
+    if (!/^[a-f0-9]{64}$/u.test(left) || !/^[a-f0-9]{64}$/u.test(right))
+        return false;
+    const leftBytes = Buffer.from(left, "hex");
+    const rightBytes = Buffer.from(right, "hex");
+    return leftBytes.byteLength === rightBytes.byteLength && timingSafeEqual(leftBytes, rightBytes);
+}
+function keyFileName(swarmId) {
+    return `swarm-${swarmId}.key`;
+}
+function assertContained(parent, child) {
+    const value = relative(parent, child);
+    if (value === "" || (!value.startsWith(`..${sep}`) && value !== ".." && !isAbsolute(value)))
+        return;
+    throw new Error("SWARM_INTEGRITY_PATH_ESCAPE");
+}
+function serializeJson(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+async function writeExactOnce(path, contents) {
+    const existing = await lstat(path).catch((error) => {
+        if (isNodeError(error, "ENOENT"))
+            return undefined;
+        throw error;
+    });
+    if (existing?.isSymbolicLink() || (existing && !existing.isFile()))
+        throw new Error("UNSAFE_SWARM_INTEGRITY_PATH");
+    if (existing) {
+        if (await readFile(path, "utf8") === contents)
+            return;
+        throw new Error("SWARM_INTEGRITY_IDENTITY_CONFLICT");
+    }
+    let handle;
+    try {
+        handle = await open(path, "wx", 0o600);
+        await handle.writeFile(contents, "utf8");
+        await handle.sync();
+    }
+    catch (error) {
+        if (!isNodeError(error, "EEXIST"))
+            throw error;
+        if (await readFile(path, "utf8") === contents)
+            return;
+        throw new Error("SWARM_INTEGRITY_IDENTITY_CONFLICT");
+    }
+    finally {
+        await handle?.close();
+    }
+}
+function isNodeError(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}
+function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/vendor/core/swarm/candidates.d.ts

@@ -0,0 +1,78 @@
+import { type ReceiptIntegritySummary, type SwarmCandidate, type SwarmPatchAdmission, type SwarmRunRecord } from "../../contracts/index.js";
+import type { SwarmWorkspaceRuntimeHandle } from "./workspaces.js";
+export interface SwarmCandidateGitCommand {
+    readonly cwd: string;
+    readonly args: readonly string[];
+}
+export interface SwarmCandidateGitResult {
+    readonly stdout: Buffer;
+    readonly stderr: Buffer;
+}
+export type SwarmCandidateGitRunner = (command: SwarmCandidateGitCommand) => Promise<SwarmCandidateGitResult>;
+export interface PersistedSwarmCandidateArtifact {
+    readonly candidate: SwarmCandidate;
+    readonly attemptId: string;
+    readonly proposalId: string;
+    readonly identitySha256: string;
+    readonly candidateTreeHash: string;
+    readonly patch: Buffer;
+    readonly manifest: Buffer;
+    readonly manifestSha256: string;
+    readonly receiptIntegrity: ReceiptIntegritySummary;
+}
+export interface SwarmProcessClosureEvidence {
+    readonly swarmId: string;
+    readonly workspaceId: string;
+    readonly childRunId: string;
+    readonly agentId: string;
+    readonly state: "closed";
+    readonly completedAt: string;
+}
+/**
+ * Implementations must durably and atomically reject duplicate candidate IDs.
+ * The caller does not receive cleanup authority until both operations resolve.
+ */
+export interface SwarmCandidateArtifactWriter {
+    loadProcessClosure(childRunId: string): Promise<SwarmProcessClosureEvidence | undefined>;
+    persistCandidate(artifact: PersistedSwarmCandidateArtifact): Promise<void>;
+    persistDecision(decision: SwarmPatchAdmission): Promise<void>;
+}
+export interface CaptureSwarmCandidateInput {
+    readonly swarmRecord: SwarmRunRecord;
+    readonly canonicalRoot: string;
+    readonly swarmId: string;
+    readonly candidateId: string;
+    readonly admissionId: string;
+    readonly attemptId: string;
+    readonly proposalId: string;
+    readonly childRunId: string;
+    readonly agentId: string;
+    readonly taskIds: readonly string[];
+    readonly expectedBaselineCommit: string;
+    readonly workspace: SwarmWorkspaceRuntimeHandle;
+    readonly childState: "verified" | "stopped" | "needs_review" | "running" | "queued";
+    readonly declaredPaths: readonly string[];
+    readonly childAllowedPaths: readonly string[];
+    readonly inheritedDeniedPaths: readonly string[];
+    readonly taskWriteScope: readonly string[];
+    readonly runsRoot: string;
+    readonly loopRecordPath: string;
+    readonly ledgerPath: string;
+    readonly artifactWriter: SwarmCandidateArtifactWriter;
+    readonly gitRunner?: SwarmCandidateGitRunner;
+    readonly now?: () => string;
+    /** Test-only race seam executed after validation and before staging. */
+    readonly beforeStage?: () => void | Promise<void>;
+}
+export interface CaptureSwarmCandidateResult {
+    readonly admission: SwarmPatchAdmission;
+    readonly artifact?: PersistedSwarmCandidateArtifact;
+    readonly cleanupAuthorized: boolean;
+}
+/**
+ * Internal live-runtime bridge to the candidate module's single NUL-safe Git
+ * inventory parser. Policy enforcement remains in captureAndAdmitSwarmCandidate.
+ */
+export declare function inventorySwarmCandidatePaths(workspacePath: string, gitRunner?: SwarmCandidateGitRunner): Promise<string[]>;
+export declare function captureAndAdmitSwarmCandidate(input: CaptureSwarmCandidateInput): Promise<CaptureSwarmCandidateResult>;
+export declare function verifyPersistedSwarmCandidateArtifact(artifact: PersistedSwarmCandidateArtifact): boolean;