@entrorove/skill 0.1.22 → 0.1.24

package/local-scope-workspaces.mjs

@@ -0,0 +1,83 @@
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { scopeFail, scopePath, scopeRead, scopeTarget } from './local-scope-files.mjs';
+
+async function manifest(root, relative, input) {
+  try {
+    const read = await scopeRead(root, relative, input);
+    return { value: JSON.parse(read.content.toString('utf8')), path: relative, sha256: read.sha256 };
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    if (error instanceof SyntaxError) scopeFail('ENTROROVE_PACKAGE_INVALID', 'workspace package manifest is invalid JSON');
+    throw error;
+  }
+}
+async function patterns(root, input) {
+  const main = await manifest(root, 'package.json', input);
+  const metadata = main ? [{ path: main.path, sha256: main.sha256 }] : [];
+  let result = main?.value.workspaces ?? [];
+  if (!Array.isArray(result)) result = result.packages;
+  if (!Array.isArray(result) || result.some(pattern => typeof pattern !== 'string')) scopeFail('ENTROROVE_PACKAGE_INVALID', 'workspace patterns must be a literal string array');
+  try {
+    const read = await scopeRead(root, 'pnpm-workspace.yaml', input); const yaml = read.content.toString('utf8'); let active = false;
+    metadata.push({ path: 'pnpm-workspace.yaml', sha256: read.sha256 });
+    for (const line of yaml.split('\n')) {
+      if (/^packages:\s*$/.test(line)) { active = true; continue; }
+      if (/^[A-Za-z]/.test(line)) active = false;
+      if (!active || !line.trim() || line.trim().startsWith('#')) continue;
+      const match = /^\s+-\s+['"]?([A-Za-z0-9_./*-]+)['"]?\s*$/.exec(line);
+      if (!match) scopeFail('ENTROROVE_PACKAGE_INVALID', 'workspace YAML requires supported literal package patterns');
+      result.push(match[1]);
+    }
+  } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  return { patterns: [...new Set(result)], metadata };
+}
+async function packageDirectories(root, pattern) {
+  if (!pattern.includes('*')) { scopePath(pattern); return [pattern]; }
+  if (!pattern.endsWith('/*') || pattern.slice(0, -2).includes('*')) scopeFail('ENTROROVE_PACKAGE_INVALID', 'workspace glob needs a literal parent and a single terminal wildcard');
+  const parent = scopePath(pattern.slice(0, -2)); const item = await scopeTarget(root, parent, true);
+  if (!item.exists) return [];
+  if (!item.stat.isDirectory()) scopeFail('ENTROROVE_PACKAGE_INVALID', 'workspace parent must be a real directory');
+  const result = [];
+  for (const name of (await fs.readdir(item.target)).sort()) {
+    const directory = `${parent}/${name}`; const target = await scopeTarget(root, directory);
+    if (target.stat.isDirectory()) result.push(directory);
+  }
+  return result;
+}
+export async function workspaceIndex(root, input = { repositoryRoot: root }) {
+  const index = new Map(); let count = 0;
+  const workspace = await patterns(root, input); index.metadata = workspace.metadata;
+  for (const pattern of workspace.patterns) for (const directory of await packageDirectories(root, pattern)) {
+    if (++count > 1000) scopeFail('ENTROROVE_SCOPE_LIMIT', 'workspace metadata exceeds the 1000-package bound');
+    const entry = await manifest(root, `${directory}/package.json`, input);
+    if (!entry) continue;
+    if (typeof entry.value.name !== 'string' || !entry.value.name) scopeFail('ENTROROVE_PACKAGE_INVALID', 'workspace package requires its actual package name');
+    if (index.has(entry.value.name)) scopeFail('ENTROROVE_PACKAGE_INVALID', 'workspace package names are ambiguous');
+    index.metadata.push({ path: entry.path, sha256: entry.sha256 });
+    index.set(entry.value.name, { directory, ...entry });
+  }
+  index.metadata.sort((a, b) => a.path.localeCompare(b.path));
+  return index;
+}
+function exportedTarget(value) {
+  if (typeof value === 'string') return value;
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const targets = [...new Set(Object.entries(value).filter(([condition]) => condition !== 'types').map(([, entry]) => exportedTarget(entry)).filter(Boolean))];
+  if (targets.length > 1) scopeFail('ENTROROVE_IMPORT_AMBIGUOUS', 'conditional workspace export needs an actual unambiguous execution context');
+  return targets[0] ?? null;
+}
+export function workspaceImport(index, specifier) {
+  const name = specifier.startsWith('@') ? specifier.split('/').slice(0, 2).join('/') : specifier.split('/')[0];
+  const entry = index.get(name); if (!entry) return null;
+  const subpath = specifier === name ? '.' : `.${specifier.slice(name.length)}`;
+  const exports = entry.value.exports;
+  const rootConditions = exports && typeof exports === 'object' && !Array.isArray(exports) && Object.keys(exports).every(key => !key.startsWith('.'));
+  let target = subpath === '.' && (typeof exports === 'string' || rootConditions) ? exportedTarget(exports) : exportedTarget(exports?.[subpath]);
+  if (!target && subpath === '.' && exports === undefined) target = entry.value.module ?? entry.value.main ?? 'index.js';
+  if (!target && subpath !== '.' && entry.value.exports === undefined) target = subpath.slice(2);
+  if (typeof target !== 'string') scopeFail('ENTROROVE_IMPORT_UNRESOLVED', 'workspace import has no explicit resolvable export');
+  const relative = path.posix.normalize(path.posix.join(entry.directory, target)); scopePath(relative);
+  if (!relative.startsWith(`${entry.directory}/`)) scopeFail('ENTROROVE_PATH_UNSAFE', 'workspace export escapes its package boundary');
+  return relative;
+}

package/local-swarm-authority.mjs

@@ -0,0 +1,143 @@
+import Ajv from 'ajv';
+import { createPublicKey, verify } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { canonical, sha256 } from './local-integrity.mjs';
+import { WORKFLOW_ACCEPTED_PLAN_SCHEMA, WORKFLOW_LOCAL_LEASE_SCHEMA } from './workflow-local-contracts.mjs';
+import { readTaskHandoffFence } from './local-task-handoff-fence.mjs';
+import { canonicalSwarmPaths, SWARM_PRIORITIES } from './local-swarm-state.mjs';
+import { assertSwarmOriginalBaseline } from './local-swarm-baseline.mjs';
+
+export const SWARM_GRANT_SCHEMA = 'entrorove.swarm-delegation-grant/1.0';
+const ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/, SHA = /^[0-9a-f]{64}$/;
+const GRANT_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/;
+const GRANT_FIELDS = ['schemaVersion', 'grantId', 'assignmentId', 'assignmentRevision', 'ownerId', 'originOwnerId',
+  'taskId', 'taskDigest', 'chainDigest', 'chainRevision', 'flowId', 'planId', 'planDigest', 'stepId', 'executionPlanSha256',
+  'workerId', 'runnerId', 'runnerKeyId', 'repositoryId', 'localRepositoryDigest', 'scopeArtifactDigest', 'scopeRevision',
+  'snapshotDigest', 'paths', 'frozenManifest', 'frozenManifestDigest', 'priority', 'leaseId', 'leaseDigest', 'generation', 'spawnDepth', 'spawnAllowed',
+  'issuedAt', 'expiresAt', 'scopeExpiresAt'];
+const ajv = new Ajv({ allErrors: true, strict: false });
+const validatePlan = ajv.compile(WORKFLOW_ACCEPTED_PLAN_SCHEMA), validateLease = ajv.compile(WORKFLOW_LOCAL_LEASE_SCHEMA);
+function fail(code, message) { throw Object.assign(new Error(message), { code }); }
+export const unsignedSwarmAuthority = value => Object.fromEntries(Object.entries(value).filter(([key]) => key !== 'authorityReceipt'));
+function exact(value, fields) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || canonical(Object.keys(value).sort()) !== canonical([...fields].sort())) fail('ENTROROVE_SWARM_AUTHORITY_INVALID', 'signed authority fields are invalid');
+}
+function configuredKey(name) {
+  try {
+    const encoded = process.env[name], bytes = Buffer.from(encoded ?? '', 'base64');
+    const key = createPublicKey({ key: bytes, format: 'der', type: 'spki' });
+    if (key.asymmetricKeyType !== 'ed25519' || key.export({ format: 'der', type: 'spki' }).toString('base64') !== encoded) throw new Error();
+    return { key, keyId: sha256(bytes) };
+  } catch { fail('ENTROROVE_SWARM_AUTHORITY_INVALID', 'the configured original cloud or runner key is unavailable'); }
+}
+function signed(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) fail('ENTROROVE_SWARM_AUTHORITY_INVALID', 'cloud authority must be a signed object');
+  const core = unsignedSwarmAuthority(value), receipt = value.authorityReceipt, configured = configuredKey('ENTROROVE_WORKFLOW_PLAN_PUBLIC_KEY');
+  exact(receipt, ['schemaVersion', 'keyId', 'payloadDigest', 'signature']);
+  const bytes = Buffer.from(canonical(core)), signature = Buffer.from(receipt.signature ?? '', 'base64url');
+  if (bytes.length > 4 * 1024 * 1024 || receipt.schemaVersion !== 'entrorove.workflow-authority-receipt/1.0'
+    || receipt.keyId !== configured.keyId || receipt.payloadDigest !== sha256(bytes) || typeof receipt.signature !== 'string'
+    || signature.length !== 64 || signature.toString('base64url') !== receipt.signature || !verify(null, bytes, configured.key, signature)) {
+    fail('ENTROROVE_SWARM_AUTHORITY_INVALID', 'the original cloud signature or authority digest is invalid');
+  }
+  return core;
+}
+function lifetime(start, end, maximum, permitExpired = false) {
+  const issued = Date.parse(start), expires = Date.parse(end);
+  if (typeof start !== 'string' || typeof end !== 'string' || !Number.isFinite(issued) || !Number.isFinite(expires)
+    || issued > Date.now() || expires <= issued || expires - issued > maximum || (!permitExpired && expires <= Date.now())) {
+    fail('ENTROROVE_SWARM_AUTHORITY_EXPIRED', 'cloud authority lifetime is invalid or expired');
+  }
+}
+export function verifyStoredSwarmGrant(value, permitExpired = false) {
+  const grant = signed(value); exact(grant, GRANT_FIELDS);
+  const ids = ['grantId', 'assignmentId', 'ownerId', 'originOwnerId', 'taskId', 'flowId', 'planId', 'stepId', 'workerId', 'runnerId', 'repositoryId', 'leaseId'];
+  const hashes = ['taskDigest', 'chainDigest', 'planDigest', 'executionPlanSha256', 'runnerKeyId', 'scopeArtifactDigest', 'snapshotDigest', 'leaseDigest', 'frozenManifestDigest'];
+  if (grant.schemaVersion !== SWARM_GRANT_SCHEMA || ids.some(field => typeof grant[field] !== 'string' || !GRANT_ID.test(grant[field]))
+    || hashes.some(field => !SHA.test(grant[field] ?? '')) || !/^[0-9a-f]{32}$/.test(grant.localRepositoryDigest ?? '')
+    || ['assignmentRevision', 'chainRevision', 'scopeRevision', 'generation'].some(field => !Number.isSafeInteger(grant[field]) || grant[field] < 1)
+    || grant.spawnDepth !== 1 || grant.spawnAllowed !== false || !SWARM_PRIORITIES.includes(grant.priority)
+    || canonical(canonicalSwarmPaths(grant.paths)) !== canonical(grant.paths)) fail('ENTROROVE_SWARM_AUTHORITY_INVALID', 'delegation grant identifiers, immutable scope or recursion policy are invalid');
+  if (!Array.isArray(grant.frozenManifest) || !grant.frozenManifest.length || grant.frozenManifest.length > 512) fail('ENTROROVE_SWARM_AUTHORITY_INVALID', 'frozen original manifest is missing');
+  for (const file of grant.frozenManifest) {
+    exact(file, ['path', 'sha256']); canonicalSwarmPaths([file.path]);
+    if (!SHA.test(file.sha256 ?? '')) fail('ENTROROVE_SWARM_AUTHORITY_INVALID', 'frozen original manifest hash is invalid');
+  }
+  const ordered = [...grant.frozenManifest].sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
+  if (new Set(ordered.map(file => file.path)).size !== ordered.length || canonical(ordered) !== canonical(grant.frozenManifest)) fail('ENTROROVE_SWARM_AUTHORITY_INVALID', 'frozen original manifest must be sorted and unique');
+  if (sha256(`validator.file-manifest/1.0\n${ordered.map(file => `${file.path}\0${file.sha256}`).join('\n')}`) !== grant.frozenManifestDigest) fail('ENTROROVE_SWARM_AUTHORITY_INVALID', 'original frozen manifest digest is invalid');
+  lifetime(grant.issuedAt, grant.expiresAt, 90_000, permitExpired);
+  const scopeExpiry = Date.parse(grant.scopeExpiresAt);
+  if (!Number.isFinite(scopeExpiry) || Date.parse(grant.expiresAt) > scopeExpiry) fail('ENTROROVE_SWARM_AUTHORITY_INVALID', 'delegation expiry exceeds its actual scope authority');
+  return grant;
+}
+export function requireSwarmCloudMaterial(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input) || typeof input.stepId !== 'string' || !input.stepId
+    || !input.acceptedPlan || !input.lease || !input.delegationGrant || !input.executionAuthority
+    || typeof input.executionAttemptNonce !== 'string' || !ID.test(input.executionAttemptNonce)) {
+    fail('ENTROROVE_SWARM_CLOUD_AUTHORITY_REQUIRED', 'peer operations require the original accepted plan, step, cloud lease, delegation grant and fresh execution authority');
+  }
+}
+export function readSignedSwarmMaterial(input, purpose = 'issue') {
+  if (!validatePlan(input.acceptedPlan) || !validateLease(input.lease)) fail('ENTROROVE_SWARM_AUTHORITY_INVALID', 'original accepted plan or cloud lease schema is invalid');
+  const plan = signed(input.acceptedPlan), lease = signed(input.lease), grant = verifyStoredSwarmGrant(input.delegationGrant, purpose === 'verify' || purpose === 'report');
+  const step = plan.steps.find(value => value.stepId === input.stepId);
+  if (!step || input.flowId !== plan.flowId || grant.stepId !== input.stepId || (input.workerId !== undefined && input.workerId !== grant.workerId)
+    || ['planId', 'flowId', 'ownerId', 'taskDigest', 'chainDigest', 'chainRevision'].some(field => lease[field] !== plan[field] || grant[field] !== plan[field])
+    || lease.stepId !== step.stepId || lease.sequence !== step.sequence || grant.generation !== lease.generation || grant.leaseId !== lease.leaseId
+    || lease.planDigest !== sha256(canonical(plan)) || grant.planDigest !== lease.planDigest || grant.leaseDigest !== sha256(canonical(lease))
+    || grant.executionPlanSha256 !== step.executionPlanSha256 || sha256(canonical(step.executionPlan) + '\n') !== step.executionPlanSha256
+    || grant.runnerKeyId !== plan.runnerKeyId || grant.runnerKeyId !== configuredKey('ENTROROVE_TASK_HANDOFF_RUNNER_PUBLIC_KEY').keyId) {
+    fail('ENTROROVE_SWARM_AUTHORITY_INVALID', 'peer grant lost its original plan, owner, task, step, lease or registered runner');
+  }
+  const manifest = step.executionPlan.files;
+  if (canonical(manifest) !== canonical(grant.frozenManifest) || step.executionPlan.artifactSha256 !== grant.frozenManifestDigest || lease.verifiedDependencies.length !== step.dependsOn.length
+    || new Set(lease.verifiedDependencies.map(value => value.stepId)).size !== step.dependsOn.length
+    || lease.verifiedDependencies.some(value => !step.dependsOn.includes(value.stepId))) fail('ENTROROVE_SWARM_AUTHORITY_INVALID', 'the grant changed the original manifest or verified dependency closure');
+  lifetime(plan.acceptedAt, plan.expiresAt, 86_400_000, purpose === 'report'); lifetime(lease.issuedAt, lease.expiresAt, 600_000, purpose === 'report');
+  if (Date.parse(grant.expiresAt) > Date.parse(lease.expiresAt)) fail('ENTROROVE_SWARM_AUTHORITY_INVALID', 'delegation exceeds the original business lease');
+  return { plan, lease, grant, step };
+}
+export async function readSwarmCloudAuthority(input, purpose = 'issue') {
+  requireSwarmCloudMaterial(input);
+  const { plan, lease, grant, step } = readSignedSwarmMaterial(input, purpose);
+  if (typeof input.repositoryRoot !== 'string' || !path.isAbsolute(input.repositoryRoot)) fail('ENTROROVE_SWARM_AUTHORITY_INVALID', 'repository root must be absolute');
+  const rootStat = await fs.lstat(input.repositoryRoot);
+  if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) fail('ENTROROVE_SWARM_AUTHORITY_INVALID', 'repository root must be an actual directory');
+  const root = await fs.realpath(input.repositoryRoot), home = await fs.realpath(input.home ?? os.homedir()), repositoryDigest = sha256(root).slice(0, 32);
+  if (grant.localRepositoryDigest !== repositoryDigest) fail('ENTROROVE_SWARM_AUTHORITY_INVALID', 'delegation belongs to another physical repository');
+  const execution = signed(input.executionAuthority), fence = await readTaskHandoffFence({ ...input, repositoryRoot: root, home });
+  const attempt = fence.executionAttempts.find(value => value.authority.attemptNonce === input.executionAttemptNonce);
+  if (!attempt || canonical(attempt.authority) !== canonical(input.executionAuthority) || attempt.executionHome !== home
+    || !['ready', 'used'].includes(attempt.status) || execution.schemaVersion !== 'entrorove.task-execution-epoch-authority/1.0'
+    || execution.status !== 'active' || execution.epoch !== fence.epoch || execution.attemptNonce !== input.executionAttemptNonce
+    || execution.taskId !== grant.taskId || execution.leaseId !== lease.leaseId || execution.generation !== lease.generation
+    || ['flowId', 'ownerId', 'taskDigest', 'chainDigest', 'runnerKeyId', 'localRepositoryDigest'].some(field => execution[field] !== grant[field])) {
+    fail('ENTROROVE_SWARM_AUTHORITY_INVALID', 'peer grant has no original consumed execution nonce and epoch');
+  }
+  if (attempt.status === 'ready' && purpose !== 'report') lifetime(execution.issuedAt, execution.expiresAt, 30_000);
+  else if (attempt.status === 'used' && purpose !== 'report') {
+    const activity = fence.activities.find(value => value.executionId === attempt.executionId && value.leaseId === lease.leaseId && value.epoch === fence.epoch);
+    if (!activity || !Number.isSafeInteger(activity.pid) || activity.pid < 1) fail('ENTROROVE_SWARM_AUTHORITY_INVALID', 'used execution authority has no actual active process');
+    try { process.kill(activity.pid, 0); } catch { fail('ENTROROVE_SWARM_AUTHORITY_INVALID', 'the original execution process is no longer active'); }
+  }
+  if (Date.parse(grant.expiresAt) <= Date.now() && attempt.status !== 'used') fail('ENTROROVE_SWARM_AUTHORITY_EXPIRED', 'historical delegation cannot admit or report a new unused execution');
+  const requestedPaths = canonicalSwarmPaths(input.paths ?? grant.paths), paths = grant.paths;
+  if (purpose === 'verify' ? requestedPaths.some(target => !paths.includes(target)) : canonical(requestedPaths) !== canonical(paths)) {
+    fail('ENTROROVE_SWARM_AUTHORITY_INVALID', 'caller paths cannot replace the exact cloud write-path grant');
+  }
+  for (const target of paths) {
+    let current = root;
+    for (const part of target.split('/')) {
+      current = path.join(current, part);
+      try { if ((await fs.lstat(current)).isSymbolicLink()) fail('ENTROROVE_SWARM_PATH_INVALID', 'a granted path crosses an actual symlink'); }
+      catch (error) { if (error.code === 'ENOENT') break; throw error; }
+    }
+  }
+  const authority = { root, home, repositoryDigest, plan, lease, step, grant, epoch: fence.epoch, paths, requestedPaths };
+  if (purpose === 'issue') await assertSwarmOriginalBaseline(authority, input);
+  return authority;
+}

package/local-swarm-baseline.mjs

@@ -0,0 +1,32 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { sha256 } from './local-integrity.mjs';
+import { readBudgetedProjectFile } from './local-budget-reads.mjs';
+
+function stale(relative) {
+  throw Object.assign(new Error(`the original Aimlock baseline changed at ${relative}; obtain a new legitimate scope and plan instead of replacing the old grant`),
+    { code: 'ENTROROVE_SWARM_BASELINE_STALE' });
+}
+async function originalFile(root, relative) {
+  let target = root;
+  const parts = relative.split('/');
+  for (const [index, part] of parts.entries()) {
+    target = path.join(target, part);
+    let stat;
+    try { stat = await fs.lstat(target); } catch { stale(relative); }
+    const final = index === parts.length - 1;
+    if (stat.isSymbolicLink() || (final ? !stat.isFile() : !stat.isDirectory())) stale(relative);
+  }
+  if (await fs.realpath(target) !== target) stale(relative);
+  return { target, stat: await fs.lstat(target) };
+}
+export async function assertSwarmOriginalBaseline(authority, input) {
+  const reader = { ...input, repositoryRoot: authority.root, home: authority.home, flowId: authority.plan.flowId };
+  for (const file of authority.grant.frozenManifest) {
+    const before = await originalFile(authority.root, file.path);
+    const bytes = await readBudgetedProjectFile(reader, before.target, { sourcePath: file.path });
+    const after = await originalFile(authority.root, file.path);
+    if (before.stat.dev !== after.stat.dev || before.stat.ino !== after.stat.ino || before.stat.size !== after.stat.size
+      || before.stat.mtimeMs !== after.stat.mtimeMs || sha256(bytes) !== file.sha256) stale(file.path);
+  }
+}

package/local-swarm-completion.mjs

@@ -0,0 +1,102 @@
+import { constants, promises as fs } from 'node:fs';
+import path from 'node:path';
+import { canonical, sha256 } from './local-integrity.mjs';
+import { readSwarmCloudAuthority } from './local-swarm-authority.mjs';
+import { observeWorkflowLocalStep } from './workflow-local-runner.mjs';
+
+const proofs = new WeakMap();
+function unknown() { throw Object.assign(new Error('the original signed completion cache is missing, changed or unknown'), { code: 'ENTROROVE_SWARM_EXECUTION_UNKNOWN' }); }
+function materialDigest(authority, input) {
+  return sha256(canonical({ root: authority.root, home: authority.home, epoch: authority.epoch,
+    acceptedPlan: input.acceptedPlan, lease: input.lease, delegationGrant: input.delegationGrant,
+    executionAuthority: input.executionAuthority, executionAttemptNonce: input.executionAttemptNonce }));
+}
+function cachePath(authority) {
+  return path.join(authority.home, '.entrorove', 'workflow-local', authority.repositoryDigest,
+    authority.plan.flowId, authority.step.stepId, 'state.json');
+}
+async function readCache(authority) {
+  const file = cachePath(authority);
+  let directory = authority.home;
+  for (const part of path.relative(authority.home, path.dirname(file)).split(path.sep)) {
+    directory = path.join(directory, part);
+    const stat = await fs.lstat(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o777) !== 0o700
+      || (typeof process.getuid === 'function' && stat.uid !== process.getuid())) unknown();
+  }
+  const before = await fs.lstat(file);
+  if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1 || before.size > 8 * 1024 * 1024
+    || (before.mode & 0o777) !== 0o600 || (typeof process.getuid === 'function' && before.uid !== process.getuid())) unknown();
+  const handle = await fs.open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const opened = await handle.stat();
+    if (opened.dev !== before.dev || opened.ino !== before.ino) unknown();
+    const bytes = await handle.readFile(), after = await handle.stat(), current = await fs.lstat(file);
+    if (bytes.length > 8 * 1024 * 1024 || after.size !== opened.size || after.mtimeMs !== opened.mtimeMs
+      || current.dev !== opened.dev || current.ino !== opened.ino) unknown();
+    return { state: JSON.parse(bytes.toString('utf8')), digest: sha256(bytes), dev: opened.dev, ino: opened.ino };
+  } finally { await handle.close(); }
+}
+function sameObservedCache(authority, input, cache, result) {
+  const state = cache.state, original = { ...result, cached: false };
+  const identity = { repositoryDigest: authority.repositoryDigest, planId: authority.plan.planId,
+    planDigest: authority.lease.planDigest, flowId: authority.plan.flowId, ownerId: authority.plan.ownerId,
+    stepId: authority.step.stepId, sequence: authority.step.sequence, leaseId: authority.lease.leaseId,
+    generation: authority.lease.generation, leaseDigest: sha256(canonical(authority.lease)) };
+  if (state?.schemaVersion !== 'entrorove.workflow-local-state/1.0' || state.status !== result.status
+    || Object.entries(identity).some(([key, value]) => state[key] !== value)
+    || canonical(state.executionAuthority) !== canonical(input.executionAuthority)
+    || state.resultDigest !== sha256(canonical(original)) || canonical(state.result) !== canonical(original)) unknown();
+  const started = Date.parse(result.process?.startedAt), finished = Date.parse(result.process?.finishedAt);
+  if (!['reported', 'failed'].includes(result.status) || !result.receipt || !Number.isInteger(result.process?.exitCode)
+    || !Number.isFinite(started) || !Number.isFinite(finished) || started < Date.parse(authority.grant.issuedAt)
+    || started >= Date.parse(authority.grant.expiresAt) || started < Date.parse(authority.lease.issuedAt)
+    || finished < started || finished > Date.parse(authority.lease.expiresAt)) unknown();
+}
+// Call before the outer handoff/repository locks. Tokens can only be minted by
+// the original observer verifying its real persisted runner-signed result.
+export async function captureSwarmCompletion(input) {
+  try {
+    const material = structuredClone(input), authority = await readSwarmCloudAuthority(material, 'report');
+    const result = await observeWorkflowLocalStep({ repositoryRoot: authority.root, home: authority.home,
+      acceptedPlan: material.acceptedPlan, lease: material.lease, stepId: authority.step.stepId,
+      approvalPath: null, signerConfigPath: null, executionAttemptNonce: material.executionAttemptNonce });
+    if (!result) return null;
+    const cache = await readCache(authority); sameObservedCache(authority, material, cache, result);
+    const token = Object.freeze({});
+    proofs.set(token, { materialDigest: materialDigest(authority, material), ...cache, result: structuredClone(result) });
+    return token;
+  } catch { return null; }
+}
+// The caller holds the original handoff fence and repository lock. Re-read
+// bytes and immutable bindings without acquiring that fence a second time.
+export async function revalidateSwarmCompletion(token, authority, input) {
+  try {
+    const proof = proofs.get(token);
+    if (!proof || proof.materialDigest !== materialDigest(authority, input)) unknown();
+    const cache = await readCache(authority);
+    if (cache.digest !== proof.digest || cache.dev !== proof.dev || cache.ino !== proof.ino) unknown();
+    sameObservedCache(authority, input, cache, proof.result);
+    return structuredClone(proof.result);
+  } catch { unknown(); }
+}
+export function swarmOwnershipCompletionInput(record, root) {
+  return { repositoryRoot: root, home: record.home, flowId: record.flowId,
+    stepId: record.delegationGrant?.stepId, workerId: record.workerId, leaseId: record.leaseId,
+    acceptedPlan: record.acceptedPlan, lease: record.lease, delegationGrant: record.delegationGrant,
+    executionAuthority: record.executionAuthority,
+    executionAttemptNonce: record.executionAttemptNonce ?? record.executionAuthority?.attemptNonce };
+}
+export async function captureSwarmOwnershipCompletions(index, root) {
+  const captured = new Map();
+  if (!Array.isArray(index?.records) || index.records.length > 1024) return captured;
+  const intents = Array.isArray(index.intents) && index.intents.length <= 1024 ? index.intents : [];
+  for (const record of [...index.records, ...intents]) {
+    if (!record || (Date.parse(record.expiresAt) > Date.now() && !['active', 'completed'].includes(record.status))) continue;
+    const key = record.grantDigest ?? record.intentId;
+    if (captured.has(key)) continue;
+    const token = await captureSwarmCompletion(swarmOwnershipCompletionInput(record, root));
+    if (token) captured.set(key, token);
+  }
+  return captured;
+}

package/local-swarm-contracts.mjs

@@ -0,0 +1,47 @@
+import { WORKFLOW_ACCEPTED_PLAN_SCHEMA, WORKFLOW_LOCAL_LEASE_SCHEMA } from './workflow-local-contracts.mjs';
+import { array, enumeration, integer, nullable, object, paths, sha256, text } from './local-contract-types.mjs';
+
+const id = { ...text, maxLength: 200, pattern: '^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$' };
+const rootDigest = { type: 'string', pattern: '^[0-9a-f]{32}$' };
+const priority = enumeration(['background', 'normal', 'high', 'urgent']);
+const exact = properties => object(properties, Object.keys(properties));
+const receipt = exact({ schemaVersion: { const: 'entrorove.workflow-authority-receipt/1.0' },
+  keyId: sha256, payloadDigest: sha256, signature: { ...text, pattern: '^[A-Za-z0-9_-]{86}$' } });
+export const SWARM_DELEGATION_GRANT_SCHEMA = exact({
+  schemaVersion: { const: 'entrorove.swarm-delegation-grant/1.0' }, grantId: id, assignmentId: id,
+  assignmentRevision: integer(1), ownerId: id, originOwnerId: id, taskId: id,
+  taskDigest: sha256, chainDigest: sha256, chainRevision: integer(1), flowId: id, planId: id,
+  planDigest: sha256, stepId: id, executionPlanSha256: sha256, workerId: id, runnerId: id, runnerKeyId: sha256,
+  repositoryId: id, localRepositoryDigest: rootDigest, scopeArtifactDigest: sha256, scopeRevision: integer(1),
+  scopeExpiresAt: text, snapshotDigest: sha256, paths,
+  frozenManifest: { ...array(exact({ path: paths.items, sha256 }), 1), maxItems: 512 },
+  frozenManifestDigest: sha256, priority, leaseId: id, leaseDigest: sha256, generation: integer(1),
+  spawnDepth: { const: 1 }, spawnAllowed: { const: false }, issuedAt: text, expiresAt: text, authorityReceipt: receipt,
+});
+const executionAuthority = exact({ schemaVersion: { const: 'entrorove.task-execution-epoch-authority/1.0' },
+  authorityId: id, attemptNonce: id, taskId: id, flowId: id, ownerId: id, taskDigest: sha256, chainDigest: sha256,
+  leaseId: id, generation: integer(1), epoch: integer(0), status: { const: 'active' }, runnerKeyId: sha256,
+  localRepositoryDigest: rootDigest, issuedAt: text, expiresAt: text, authorityReceipt: receipt });
+export const SWARM_LOCAL_AUTHORITY_PROPERTIES = Object.freeze({ acceptedPlan: WORKFLOW_ACCEPTED_PLAN_SCHEMA,
+  lease: WORKFLOW_LOCAL_LEASE_SCHEMA, delegationGrant: SWARM_DELEGATION_GRANT_SCHEMA,
+  executionAuthority, executionAttemptNonce: id, workerId: id, leaseId: id });
+export const SWARM_LOCAL_AUTHORITY_REQUIRED = Object.freeze(Object.keys(SWARM_LOCAL_AUTHORITY_PROPERTIES));
+const common = { repositoryRoot: text, home: text, flowId: id, stepId: id, paths, ...SWARM_LOCAL_AUTHORITY_PROPERTIES };
+const required = ['repositoryRoot', 'flowId', 'stepId', ...SWARM_LOCAL_AUTHORITY_REQUIRED];
+const coordinate = object({ ...common, workerCount: integer(0, 50), priority }, required);
+const spawn = object({ ...common, priority, parentWorkerId: nullable(text) }, [...required, 'paths']);
+const complete = object({ ...common, status: enumeration(['completed', 'failed', 'blocked']),
+  approvalPath: nullable(text), signerConfigPath: nullable(text) }, required);
+const verify = object(common, [...required, 'paths']);
+export const SWARM_LOCAL_OPERATION_SCHEMAS = Object.freeze({
+  'peer-coordinate': coordinate, coordinate, 'spawn-bind': spawn,
+  'peer-complete': complete, complete, 'lease-verify': verify,
+});
+// Capture the authority before verification; the gate must verify this exact
+// binding before signing it into the existing pass. This never issues a grant.
+export function swarmCoordinationBinding(input) {
+  const binding = Object.fromEntries(SWARM_LOCAL_AUTHORITY_REQUIRED.map(field => [field, structuredClone(input[field])]));
+  if (binding.workerId === undefined) binding.workerId = binding.delegationGrant?.workerId;
+  if (binding.leaseId === undefined) binding.leaseId = binding.lease?.leaseId;
+  return binding;
+}

package/local-swarm-mutation.mjs

@@ -0,0 +1,142 @@
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import { canonical, sha256 } from './local-integrity.mjs';
+import { mutationPass14 } from './local-mutation-wire.mjs';
+import { mutationOriginalBinding14, mutationSnapshotBinding14 } from './local-mutation-binding.mjs';
+import { readSwarmCloudAuthority } from './local-swarm-authority.mjs';
+import { assertSwarmOriginalBaseline } from './local-swarm-baseline.mjs';
+import { canonicalSwarmPaths, swarmPathsOverlap, validateSwarmState } from './local-swarm-state.mjs';
+import { readSwarmJson, readSwarmOwnership, swarmFlowStorage, swarmRepositoryStorage, swarmStorage, validateSwarmOwnership } from './local-swarm-storage.mjs';
+import { readSwarmWriteIntentHistory } from './local-swarm-priority.mjs';
+import { withStateLock } from './local-state-lock.mjs';
+
+function fail(code, message) { throw Object.assign(new Error(message), { code }); }
+const same = (left, right) => canonical(left) === canonical(right);
+function storedInput(record, root) {
+  return { repositoryRoot: root, home: record.home, flowId: record.flowId,
+    stepId: record.delegationGrant.stepId, workerId: record.workerId, leaseId: record.leaseId,
+    paths: record.paths, acceptedPlan: record.acceptedPlan, lease: record.lease,
+    delegationGrant: record.delegationGrant, executionAuthority: record.executionAuthority,
+    executionAttemptNonce: record.executionAuthority.attemptNonce };
+}
+function matchCaller(input, stored) {
+  for (const field of ['flowId', 'stepId', 'workerId', 'leaseId', 'executionAttemptNonce',
+    'acceptedPlan', 'lease', 'delegationGrant', 'executionAuthority']) {
+    if (input[field] !== undefined && !same(input[field], stored[field])) {
+      fail('ENTROROVE_SWARM_LEASE_INVALID', 'mutation caller differs from the original stored worker authority');
+    }
+  }
+  if (input.paths !== undefined && canonicalSwarmPaths(input.paths).some(target => !stored.paths.includes(target))) {
+    fail('ENTROROVE_SWARM_PATH_CONFLICT', 'mutation caller changed its original signed path set');
+  }
+}
+function matchPass(pass, authority, record, targets) {
+  const { grant, lease } = authority;
+  if (['flowId', 'taskId', 'ownerId', 'taskDigest', 'chainDigest', 'chainRevision', 'stepId',
+    'planId', 'planDigest', 'executionPlanSha256', 'runnerId', 'runnerKeyId', 'repositoryId',
+    'scopeArtifactDigest', 'leaseId', 'generation'].some(field => pass[field] !== grant[field])
+    || pass.leaseDigest !== sha256(canonical(record.lease))
+    || pass.repositoryDigest !== authority.repositoryDigest || pass.epoch !== authority.epoch
+    || pass.executionAuthorityId !== record.executionAuthority.authorityId
+    || pass.executionAuthorityDigest !== sha256(canonical(record.executionAuthority))
+    || pass.executionAttemptNonce !== record.executionAuthority.attemptNonce
+    || pass.generation !== lease.generation
+    || targets.some(target => !grant.paths.includes(target) || !pass.paths.includes(target))
+    || pass.paths.some(value => !grant.paths.includes(value))) {
+    fail('ENTROROVE_SWARM_LEASE_INVALID', 'cloud mutation pass differs from the original signed Swarm plan, grant, lease, nonce or paths');
+  }
+}
+function activeWorker(state, authority, record) {
+  validateSwarmState(state, { flowId: authority.plan.flowId, repositoryDigest: authority.repositoryDigest });
+  const worker = state.workers.find(value => value.workerId === record.workerId && value.leaseId === record.leaseId);
+  if (!worker || worker.status !== 'active' || worker.grantDigest !== record.grantDigest
+    || !same(worker.delegationGrant, record.delegationGrant) || !same(worker.paths, record.paths)
+    || worker.handoffEpoch !== authority.epoch || worker.expiresAt !== record.expiresAt
+    || !Array.isArray(state.delegationGrants) || !state.delegationGrants.some(value => same(value, record.delegationGrant))) {
+    fail('ENTROROVE_SWARM_LEASE_INVALID', 'mutation requires its actual active worker and original reserved cloud grant');
+  }
+}
+async function writeForRecord(input, pass, record, targets, performWrite, batch) {
+  const stored = storedInput(record, input.repositoryRoot), authority = await readSwarmCloudAuthority(stored, 'verify');
+  if (input.home !== authority.home) fail('ENTROROVE_SWARM_LEASE_INVALID', 'mutation cannot move its original execution home');
+  matchCaller(input, stored); matchPass(pass, authority, record, targets);
+  const storage = await swarmStorage(authority, 'read');
+  return withStateLock(storage.stateFile, async () => {
+    const fresh = await readSwarmCloudAuthority(stored, 'verify');
+    matchPass(mutationPass14(pass), fresh, record, targets);
+    activeWorker(await readSwarmJson(storage.stateFile, null), fresh, record);
+    if (batch) {
+      await assertSwarmOriginalBaseline(fresh, stored);
+      await mutationSnapshotBinding14(input, pass, { allSources: true });
+      matchPass(mutationPass14(pass), await readSwarmCloudAuthority(stored, 'verify'), record, targets);
+    }
+    return performWrite();
+  });
+}
+async function rejectLostOwnership(authority, pass) {
+  let storage;
+  try { storage = await swarmFlowStorage({ ...authority, plan: { flowId: pass.flowId } }, 'read'); }
+  catch (error) { if (error.code === 'ENOENT') return; throw error; }
+  const state = await readSwarmJson(storage.stateFile, undefined);
+  if (state !== undefined) {
+    validateSwarmState(state, { flowId: pass.flowId, repositoryDigest: authority.repositoryDigest });
+    fail('ENTROROVE_SWARM_RECONCILE_REQUIRED', 'original peer state remains but its repository ownership controls are missing; reconcile before mutation');
+  }
+}
+async function unreservedWrite(input, pass, performWrite, batch) {
+  mutationPass14(pass);
+  if (batch) await mutationSnapshotBinding14(input, pass, { allSources: true });
+  return performWrite();
+}
+async function guardedOwnership(input, pass, authority, storage, targets, performWrite, batch) {
+  const marker = await readSwarmJson(storage.markerFile, null), value = await readSwarmJson(storage.ownershipFile, null);
+  if (!marker && !value) {
+    await rejectLostOwnership(authority, pass);
+    if (input.workerId !== undefined || input.delegationGrant !== undefined) {
+      fail('ENTROROVE_SWARM_CLOUD_AUTHORITY_REQUIRED', 'the original Swarm worker must coordinate and reserve before mutation');
+    }
+    return unreservedWrite(input, pass, performWrite, batch);
+  }
+  const original = await readSwarmOwnership(storage, authority, 'read');
+  const ownership = await validateSwarmOwnership(original, authority);
+  const { index } = await readSwarmWriteIntentHistory(ownership, authority);
+  const matching = ownership.records.filter(record => record.flowId === pass.flowId && record.leaseId === pass.leaseId);
+  if (matching.length > 1) fail('ENTROROVE_SWARM_STATE_INVALID', 'mutation lease has multiple original ownership records');
+  const record = matching[0];
+  if (ownership.records.some(value => value !== record
+    && value.paths.some(scope => targets.some(target => swarmPathsOverlap(scope, target))))) {
+    fail('ENTROROVE_SWARM_PATH_CONFLICT', 'another actual signed worker retains this physical write path');
+  }
+  if (record) return writeForRecord(input, pass, record, targets, performWrite, batch);
+  if (index.intents.some(intent => intent.flowId === pass.flowId && intent.stepId === pass.stepId)
+    || input.workerId !== undefined || input.delegationGrant !== undefined) {
+    fail('ENTROROVE_SWARM_LEASE_INVALID', 'queued, completed or unreserved Swarm work cannot bypass its actual worker ownership');
+  }
+  return unreservedWrite(input, pass, performWrite, batch);
+}
+
+// The native mutation caller already holds its original handoff write fence.
+// Keep repository -> flow locks through the physical write; never reacquire the
+// handoff fence or invoke a completion observer from inside these locks.
+async function withMutationPaths(rawInput, rawPass, performWrite, batch) {
+  if (typeof performWrite !== 'function') fail('ENTROROVE_SWARM_WRITE_INVALID', 'the original physical write callback is required');
+  let input, pass;
+  try { input = structuredClone(rawInput); pass = structuredClone(rawPass); }
+  catch { fail('ENTROROVE_SWARM_AUTHORITY_INVALID', 'mutation authority must be finite JSON data'); }
+  mutationPass14(pass);
+  const targets = canonicalSwarmPaths(batch ? pass.paths : [input.targetPath]);
+  if (targets.some(target => !pass.paths.includes(target))) fail('ENTROROVE_SWARM_PATH_CONFLICT', 'mutation target is outside its original signed pass');
+  const root = await fs.realpath(input.repositoryRoot), home = await fs.realpath(input.home ?? os.homedir());
+  input = { ...input, repositoryRoot: root, home };
+  const binding = await mutationOriginalBinding14(input, pass);
+  const authority = { root, home, repositoryDigest: sha256(root).slice(0, 32) };
+  if (binding.root !== root || binding.home !== home) fail('ENTROROVE_SWARM_LEASE_INVALID', 'mutation changed its actual registered repository or home');
+  const storage = await swarmRepositoryStorage(authority);
+  return withStateLock(storage.ownershipFile, () => guardedOwnership(input, pass, authority, storage, targets, performWrite, batch));
+}
+export async function withSwarmMutationLease(input, originalPass, physicalWriteCallback) {
+  return withMutationPaths(input, originalPass, physicalWriteCallback, false);
+}
+export async function withSwarmMutationBatchLease(input, originalPass, physicalBatchCallback) {
+  return withMutationPaths(input, originalPass, physicalBatchCallback, true);
+}