@entrorove/skill 0.1.23 → 0.1.24

package/local-budget-git-scratch.mjs

@@ -0,0 +1,112 @@
+import { fixedNativeScratchComparison } from './local-budget-git-native.mjs';
+import { constants, promises as fs } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { fail, requireLiveBudget } from './local-budget-grants.mjs';
+import { withBudget, loadBudget, commitBudget } from './local-budget-store.mjs';
+import { assertDependencyReadAllowed, assertBudgetReadContext, copyBudgetedProjectBuffer } from './local-budget-reads.mjs';
+import { consumeBudgetRenewal } from './local-budget-renewal.mjs';
+import { gitReadBinding, gitReadDeadline, validateGitRead, chargedGitRead } from './local-budget-git.mjs';
+import { createGitScratch, assertGitScratch, fixedScratchComparison, scratchNumstat, verifyScratchBytes } from './local-budget-git-scratch-loader.mjs';
+
+function renewedState(state) {
+  if (state.grant?.purpose === 'handoff-read') { requireLiveBudget(state); return state; }
+  return consumeBudgetRenewal({ state });
+}
+async function scratchSourceStream(descriptor) {
+  await assertGitScratch(descriptor);
+  if (descriptor.mode === '120000') return { chunks: [Buffer.from(await fs.readlink(descriptor.target))], close: async () => {} };
+  const handle = await fs.open(descriptor.target, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  const stat = await handle.stat({ bigint: true });
+  if (stat.dev !== descriptor.stat.dev || stat.ino !== descriptor.stat.ino || !stat.isFile()) { await handle.close(); fail('ENTROROVE_GIT_SOURCE_INVALID', 'Scratch descriptor lost its bound source inode'); }
+  return { chunks: handle.createReadStream({ autoClose: false }), close: () => handle.close() };
+}
+async function receiveScratch(input, state, descriptor, received) {
+  await validateGitRead(input, state, descriptor, descriptor.bytes);
+  const source = await scratchSourceStream(descriptor), chunks = [];
+  try {
+    for await (const chunk of source.chunks) {
+      received.bytes += chunk.length; chunks.push(chunk);
+      await validateGitRead(input, state, descriptor, received.bytes);
+      if (received.bytes > descriptor.bytes) fail('ENTROROVE_GIT_SOURCE_INVALID', 'actual scratch bytes exceed the original source binding');
+    }
+    received.complete = true; verifyScratchBytes(descriptor, Buffer.concat(chunks, received.bytes));
+    await assertGitScratch(descriptor); await validateGitRead(input, state, descriptor, received.bytes);
+  } finally { await source.close(); }
+}
+async function readScratch(input, descriptor) {
+  if (!input.flowId) return receiveScratch(input, null, descriptor, { bytes: 0 });
+  return withBudget(input, async (location, loaded) => {
+    const received = { bytes: 0, complete: false }, readId = randomUUID(); let state = loaded.state, committed = false;
+    try {
+      await assertDependencyReadAllowed(input); state = renewedState(state);
+      await receiveScratch(input, state, descriptor, received);
+      state = await commitBudget(location, loaded, chargedGitRead(state, descriptor, received.bytes), 'budget-read',
+        { path: descriptor.path, bytes: received.bytes, tokens: Math.ceil(received.bytes / 4), source: evidence(descriptor), readId });
+      committed = true; await validateGitRead(input, state, descriptor); await assertBudgetReadContext(input);
+    } catch (error) {
+      let current = await loadBudget(location);
+      if (current.latest.data.readId === readId) committed = true;
+      if (!committed && (received.bytes || received.complete)) {
+        await commitBudget(location, current, chargedGitRead(current.state, descriptor, received.bytes), 'budget-read',
+          { path: descriptor.path, bytes: received.bytes, tokens: Math.ceil(received.bytes / 4), source: evidence(descriptor), readId, readIncomplete: true });
+      }
+      current = await loadBudget(location);
+      if (error.code?.startsWith('ENTROROVE_') && error.code !== 'ENTROROVE_BUDGET_CHAIN_INVALID') {
+        await commitBudget(location, current, current.state, 'budget-read-denied', { path: descriptor.path, sourceRole: descriptor.role, code: error.code });
+      }
+      throw error;
+    }
+  });
+}
+function evidence(descriptor) {
+  const { target, stat, ...source } = descriptor; return source;
+}
+async function validateComparison(input, state, session) {
+  await assertBudgetReadContext(input);
+  if (state) await assertDependencyReadAllowed(input);
+  for (const descriptor of session.descriptors) {
+    await assertGitScratch(descriptor); await validateGitRead(input, state, descriptor);
+  }
+}
+async function fixedComparison(input, state, session) {
+  await validateComparison(input, state, session);
+  const runner = fixedScratchComparison(session, gitReadDeadline(state)); let done = false;
+  const result = runner.done.then(value => { done = true; return value; });
+  try {
+    while (!done) {
+      await Promise.race([result, new Promise(resolve => setTimeout(resolve, 25))]);
+      await validateComparison(input, state, session);
+    }
+    const output = await result;
+    if (!output.ok) fail('ENTROROVE_GIT_FAILED', 'fixed sealed source comparison failed or exceeded its execution deadline');
+    await validateComparison(input, state, session); return scratchNumstat(output.output);
+  } finally { runner.close(); await result; }
+}
+async function preflight(input, before, after) {
+  if (!input.flowId) return;
+  await withBudget(input, async (_location, loaded) => {
+    await assertDependencyReadAllowed(input); const state = renewedState(loaded.state);
+    for (const entry of [...before, ...after]) await validateGitRead(input, state, { path: entry.path, role: 'git-comparison' });
+  });
+}
+/** Only fixed numstat over adapter-created sealed scratch inputs; no caller command or callback. */
+export async function compareBudgetedGitSources(input, before, after, options) {
+  const binding = await gitReadBinding(input);
+  if (!Array.isArray(before) || !Array.isArray(after)) fail('ENTROROVE_GIT_SOURCE_INVALID', 'fixed Git comparison requires both source arrays');
+  const copy = entries => entries.map(entry => {
+    if (!entry || !Buffer.isBuffer(entry.content)) fail('ENTROROVE_GIT_SOURCE_INVALID', 'Git comparison requires actual immutable source buffers');
+    return { ...entry, content: copyBudgetedProjectBuffer(entry.content) };
+  });
+  before = copy(before); after = copy(after);
+  await preflight(binding.input, before, after);
+  const session = await createGitScratch(binding.input, before, after, options);
+  try {
+    // Captured scope metadata permits verification of each actual native chunk against its private original buffer.
+    // Standalone comparisons retain their original full-source preflight before starting the fixed process.
+    if (!binding.input.flowId || !session.capturedAttributes) {
+      for (const descriptor of session.descriptors) await readScratch(binding.input, descriptor);
+    }
+    if (!binding.input.flowId) return fixedComparison(binding.input, null, session);
+    return await fixedNativeScratchComparison(binding.input, session);
+  } finally { await fs.rm(session.directory, { recursive: true, force: true }); }
+}

package/local-budget-git-system-attributes.mjs

@@ -0,0 +1,44 @@
+import { constants, promises as fs } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { fail } from './local-budget-grants.mjs';
+const target = '/usr/bin/git', maximumBytes = 33_554_432;
+const hash = data => createHash('sha256').update(data).digest('hex');
+const unsupported = () => fail('ENTROROVE_GIT_ATTRIBUTES_UNSUPPORTED', 'old fixed Git must expose one actual immutable compiled system attribute path');
+function same(a, b) {
+  return ['dev', 'ino', 'mode', 'uid', 'size', 'mtimeNs', 'ctimeNs'].every(key => a[key] === b[key]);
+}
+async function trustedStat() {
+  for (const directory of ['/usr', '/usr/bin']) {
+    const stat = await fs.lstat(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || stat.uid !== 0 || stat.mode & 0o7022 || await fs.realpath(directory) !== directory) unsupported();
+  }
+  const stat = await fs.lstat(target, { bigint: true });
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.uid !== 0n || stat.mode & 0o7022n
+    || stat.size < 1n || stat.size > BigInt(maximumBytes) || await fs.realpath(target) !== target) unsupported();
+  return stat;
+}
+/** Only immutable binary metadata from the original fixed system Git, never project source bytes. */
+export async function compiledGitSystemAttributes() {
+  const before = await trustedStat(), handle = await fs.open(target, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    if (!same(before, await handle.stat({ bigint: true }))) unsupported();
+    const first = await handle.readFile();
+    if (first.length !== Number(before.size) || !same(before, await handle.stat({ bigint: true }))) unsupported();
+    const second = Buffer.alloc(first.length); let count = 0;
+    while (count < second.length) {
+      const { bytesRead } = await handle.read(second, count, second.length - count, count);
+      if (!bytesRead) unsupported(); count += bytesRead;
+    }
+    if (hash(first) !== hash(second) || !same(before, await handle.stat({ bigint: true })) || !same(before, await trustedStat())) unsupported();
+    const paths = new Set();
+    for (const raw of first.toString('latin1').split('\0').slice(0, -1)) {
+      if (!raw.startsWith('/') || !raw.endsWith('/gitattributes')) continue;
+      let candidate;
+      try { candidate = new TextDecoder('utf-8', { fatal: true }).decode(Buffer.from(raw, 'latin1')); } catch { unsupported(); }
+      if (raw.length > 4096 || /[\x00-\x1f\x7f]/.test(candidate) || candidate.split('/').some(part => part === '.' || part === '..')) unsupported();
+      paths.add(candidate);
+    }
+    if (paths.size !== 1) unsupported();
+    return [...paths][0];
+  } finally { await handle.close(); }
+}

package/local-budget-git.mjs

@@ -0,0 +1,92 @@
+import { promises as fs } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { fail, relativePath, requireLiveBudget } from './local-budget-grants.mjs';
+import { assertBudgetSourceReadAllowed } from './local-budget.mjs';
+import { budgetBindingForRead, assertBudgetReadContext, assertDependencyReadAllowed } from './local-budget-reads.mjs';
+import { budgetLocation, loadBudget, withBudget, commitBudget } from './local-budget-store.mjs';
+import { consumeBudgetRenewal } from './local-budget-renewal.mjs';
+import { assertBudgetHandoffReadAllowed } from './local-budget-handoff.mjs';
+import { fixedGitBlobStream, gitSourceDescriptor, verifyFixedGitBlob, verifyGitBlobBytes } from './local-budget-git-loader.mjs';
+
+export const BUDGET_GIT_BLOB_READER = Object.freeze({ kind: 'fixed-git-blob' });
+export function gitReadDeadline(state) {
+  if (!state?.enforced) return Date.now() + 10000;
+  return Math.min(Date.now() + 10000, Date.parse(state.startedAt) + state.maxDurationMs,
+    Date.parse(state.grant.expiresAt));
+}
+export async function gitReadBinding(input) {
+  if (!input || typeof input.repositoryRoot !== 'string') fail('ENTROROVE_ROOT_INVALID', 'fixed Git reading requires its original repository input');
+  await assertBudgetReadContext(input);
+  const root = await fs.realpath(input.repositoryRoot), stat = await fs.lstat(input.repositoryRoot);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) fail('ENTROROVE_ROOT_INVALID', 'Git reading requires its original real repository directory');
+  const selected = await budgetBindingForRead(input);
+  if (!selected) return { root, input: Object.freeze({ repositoryRoot: root }) };
+  const location = await budgetLocation(selected);
+  return { root, input: Object.freeze({ repositoryRoot: location.root, home: location.home, flowId: location.flowId }) };
+}
+export async function validateGitRead(input, state, descriptor, bytes = 0) {
+  relativePath(descriptor.path);
+  if (!state) return;
+  requireLiveBudget(state);
+  assertBudgetSourceReadAllowed(state, descriptor.path, Math.ceil(bytes / 4));
+  await assertBudgetHandoffReadAllowed({ ...input, path: descriptor.path, sourceRole: descriptor.role }, state);
+}
+async function receiveBlob(input, state, descriptor, received) {
+  await validateGitRead(input, state, descriptor, descriptor.bytes);
+  const expires = gitReadDeadline(state);
+  await verifyFixedGitBlob(input.repositoryRoot, descriptor, expires);
+  await validateGitRead(input, state, descriptor, descriptor.bytes);
+  const stream = fixedGitBlobStream(input.repositoryRoot, descriptor, expires), chunks = [];
+  try {
+    for await (const chunk of stream.chunks) {
+      received.bytes += chunk.length; chunks.push(chunk);
+      await validateGitRead(input, state, descriptor, received.bytes);
+      if (received.bytes > descriptor.bytes) fail('ENTROROVE_GIT_SOURCE_INVALID', 'Git source exceeded its exact authorized immutable size');
+    }
+    await validateGitRead(input, state, descriptor, received.bytes);
+    if (!await stream.done) fail('ENTROROVE_GIT_FAILED', 'fixed Git blob source reading failed or exceeded its deadline');
+    received.complete = true;
+    const content = Buffer.concat(chunks, received.bytes);
+    verifyGitBlobBytes(descriptor, content);
+    await verifyFixedGitBlob(input.repositoryRoot, descriptor, gitReadDeadline(state));
+    await validateGitRead(input, state, descriptor, received.bytes);
+    return content;
+  } finally { stream.close(); await stream.done; }
+}
+export function chargedGitRead(state, descriptor, bytes) {
+  return { ...state, files: state.files.includes(descriptor.path) ? state.files : [...state.files, descriptor.path],
+    readCalls: state.readCalls + 1, tokenEstimate: state.tokenEstimate + Math.ceil(bytes / 4) };
+}
+export async function readBudgetedGitBlob(input, descriptor, reader = BUDGET_GIT_BLOB_READER) {
+  if (reader !== BUDGET_GIT_BLOB_READER) fail('ENTROROVE_GIT_READER_UNSUPPORTED', 'Git source reading accepts only the fixed opaque blob reader identity');
+  descriptor = gitSourceDescriptor(descriptor); relativePath(descriptor.path);
+  const binding = await gitReadBinding(input);
+  if (!binding.input.flowId) return receiveBlob(binding.input, null, descriptor, { bytes: 0 });
+  return withBudget(binding.input, async (location, loaded) => {
+    const received = { bytes: 0, complete: false }, readId = randomUUID(); let state = loaded.state, committed = false;
+    try {
+      await assertDependencyReadAllowed(binding.input);
+      if (state.grant?.purpose === 'handoff-read') requireLiveBudget(state);
+      else state = consumeBudgetRenewal({ state });
+      const content = await receiveBlob(binding.input, state, descriptor, received);
+      state = await commitBudget(location, loaded, chargedGitRead(state, descriptor, received.bytes), 'budget-read',
+        { path: descriptor.path, bytes: received.bytes, tokens: Math.ceil(received.bytes / 4), source: descriptor, readId });
+      committed = true; await validateGitRead(binding.input, state, descriptor);
+      await assertBudgetReadContext(binding.input); return content;
+    } catch (error) {
+      let current = await loadBudget(location);
+      if (current.latest.data.readId === readId) { state = current.state; committed = true; }
+      if (!committed && (received.bytes || received.complete)) {
+        state = await commitBudget(location, current, chargedGitRead(state, descriptor, received.bytes), 'budget-read',
+          { path: descriptor.path, bytes: received.bytes, tokens: Math.ceil(received.bytes / 4), source: descriptor, readId, readIncomplete: true });
+        committed = true;
+      }
+      if (error.code?.startsWith('ENTROROVE_') && error.code !== 'ENTROROVE_BUDGET_CHAIN_INVALID') {
+        current = await loadBudget(location);
+        await commitBudget(location, current, current.state, 'budget-read-denied',
+        { path: descriptor.path, sourceRole: descriptor.role, code: error.code });
+      }
+      throw error;
+    }
+  });
+}

package/local-budget-grants.mjs

@@ -0,0 +1,82 @@
+import { createHash, createPublicKey, verify } from 'node:crypto';
+import path from 'node:path';
+
+export const BUDGET_SCHEMA = 'entrorove.read-budget/2.0';
+export const GRANT_SCHEMA = 'entrorove.budget-grant/1.0';
+export const READ_BUDGETS = Object.freeze({
+  lock: Object.freeze({ maxFiles: 3, maxTokenEstimate: 12000, maxDurationMs: 120000 }),
+  probe: Object.freeze({ maxFiles: 10, maxTokenEstimate: 30000, maxDurationMs: 480000 }),
+  swarm: Object.freeze({ maxFiles: 30, maxTokenEstimate: 100000, maxDurationMs: 3600000 }),
+});
+export function fail(code, message) { throw Object.assign(new Error(message), { code }); }
+export function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (value && typeof value === 'object') return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
+  return JSON.stringify(value);
+}
+export const sha = value => createHash('sha256').update(value).digest('hex');
+export function identifier(value, field) {
+  if (typeof value !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value)) fail('ENTROROVE_ID_INVALID', `${field} must be a safe identifier`);
+  return value;
+}
+export function relativePath(value) {
+  if (typeof value !== 'string' || !value || value !== value.normalize('NFC') || path.isAbsolute(value)
+    || /^[A-Za-z]:/.test(value) || /[\\\u0000-\u001f\u007f]/.test(value)
+    || value.split('/').some(part => !part || part === '.' || part === '..')) fail('ENTROROVE_PATH_UNSAFE', 'budget source path is unsafe');
+  return value;
+}
+export function normalizeScope(scope) {
+  if (!scope || typeof scope.goal !== 'string' || !scope.goal.trim() || !Array.isArray(scope.allowedPaths) || !scope.allowedPaths.length) fail('ENTROROVE_RENEWAL_SCOPE', 'scope must contain the original goal and allowed paths');
+  const allowedPaths = [...new Set(scope.allowedPaths.map(relativePath))].sort();
+  if (scope.forbiddenPaths !== undefined && !Array.isArray(scope.forbiddenPaths)) fail('ENTROROVE_BUDGET_SCOPE', 'forbidden source paths must be an array');
+  const forbiddenPaths = [...new Set((scope.forbiddenPaths ?? []).map(relativePath))].sort();
+  return { goal: scope.goal, allowedPaths, ...(forbiddenPaths.length ? { forbiddenPaths } : {}) };
+}
+export function validatePolicy(policy) {
+  if (!policy || !Number.isSafeInteger(policy.intervalMs) || policy.intervalMs < 1 || !Number.isSafeInteger(policy.maxRenewals) || policy.maxRenewals < 1 || policy.maxRenewals > 100
+    || !Number.isSafeInteger(policy.intervalMs * policy.maxRenewals)) fail('ENTROROVE_RENEWAL_POLICY', 'renewal intervals and cap must be bounded safe integers');
+  return { intervalMs: policy.intervalMs, maxRenewals: policy.maxRenewals };
+}
+export function validateAdditions(additions) {
+  if (!additions || ['files', 'tokenEstimate', 'durationMs'].some(key => !Number.isSafeInteger(additions[key]) || additions[key] < 0)
+    || !Object.values(additions).some(value => value > 0)) fail('ENTROROVE_EXTENSION_INVALID', 'budget additions must be nonnegative safe integers with a positive increase');
+  return { files: additions.files, tokenEstimate: additions.tokenEstimate, durationMs: additions.durationMs };
+}
+function configuredKey(grant) {
+  let keys;
+  try { keys = JSON.parse(process.env.ENTROROVE_BUDGET_PUBLIC_KEYS ?? '{}'); } catch { fail('ENTROROVE_BUDGET_TRUST_INVALID', 'budget trust configuration is invalid'); }
+  if (!keys || typeof keys[grant.keyId] !== 'string') fail('ENTROROVE_BUDGET_UNTRUSTED', 'budget grant signer is not configured');
+  try {
+    const encoded = keys[grant.keyId];
+    const key = encoded.includes('BEGIN PUBLIC KEY') ? createPublicKey(encoded) : createPublicKey({ key: Buffer.from(encoded, 'base64'), type: 'spki', format: 'der' });
+    if (key.asymmetricKeyType !== 'ed25519' || sha(key.export({ type: 'spki', format: 'der' })) !== grant.keyId) throw new Error();
+    return key;
+  } catch { fail('ENTROROVE_BUDGET_TRUST_INVALID', 'budget trusted key identity is invalid'); }
+}
+export function verifyBudgetGrant(grant, binding, kind, checkExpiry = true) {
+  if (!grant || grant.schemaVersion !== GRANT_SCHEMA || grant.kind !== kind || typeof grant.signature !== 'string') fail('ENTROROVE_BUDGET_GRANT_REQUIRED', 'a cloud-signed budget grant is required');
+  for (const field of ['grantId', 'flowId', 'stepId', 'ownerId', 'leaseId', 'requestId']) identifier(grant[field], field);
+  const unsigned = Object.fromEntries(Object.entries(grant).filter(([key]) => key !== 'signature'));
+  let valid = false;
+  try { valid = verify(null, Buffer.from(canonical(unsigned)), configuredKey(grant), Buffer.from(grant.signature, 'base64url')); } catch (error) { if (error.code) throw error; }
+  if (!valid) fail('ENTROROVE_BUDGET_SIGNATURE', 'budget cloud signature is invalid');
+  if (!READ_BUDGETS[grant.mode] || !Number.isSafeInteger(grant.revision) || grant.revision < 1 || !Number.isSafeInteger(grant.leaseGeneration) || grant.leaseGeneration < 1
+    || !/^[0-9a-f]{32}$/.test(grant.repositoryDigest) || !Number.isFinite(Date.parse(grant.issuedAt)) || !Number.isFinite(Date.parse(grant.expiresAt))
+    || Date.parse(grant.issuedAt) > Date.now() + 5000 || Date.parse(grant.expiresAt) <= Date.parse(grant.issuedAt)) fail('ENTROROVE_BUDGET_GRANT_INVALID', 'budget grant fields are invalid');
+  if (checkExpiry && Date.parse(grant.expiresAt) <= Date.now()) fail('ENTROROVE_BUDGET_LEASE_EXPIRED', 'the cloud step budget lease expired');
+  if (grant.handoff !== undefined && grant.purpose !== 'handoff-read'
+    || grant.purpose === 'handoff-read' && !['init', 'handoff-read', 'handoff-claim'].includes(grant.kind)) {
+    fail('ENTROROVE_BUDGET_HANDOFF_FORBIDDEN', 'handoff provenance cannot be reused by an ordinary budget operation');
+  }
+  const scope = normalizeScope(grant.scope);
+  if (canonical(scope) !== canonical(grant.scope) || sha(canonical(scope)) !== grant.scopeDigest) fail('ENTROROVE_BUDGET_SCOPE', 'budget scope digest is invalid');
+  if (!grant.limits || ['maxFiles', 'maxTokenEstimate', 'maxDurationMs'].some(field => !Number.isSafeInteger(grant.limits[field]) || grant.limits[field] < 1)) fail('ENTROROVE_BUDGET_GRANT_INVALID', 'budget limits are invalid');
+  for (const field of ['flowId', 'repositoryDigest', 'stepId', 'ownerId', 'leaseId', 'leaseGeneration', 'mode', 'scopeDigest']) {
+    if (binding[field] !== undefined && grant[field] !== binding[field]) fail('ENTROROVE_BUDGET_SCOPE', `budget grant ${field} does not match its original task lease`);
+  }
+  return grant;
+}
+export function requireLiveBudget(state, now = Date.now()) {
+  if (state.closedReason === 'completed') fail('ENTROROVE_BUDGET_COMPLETED', 'completed tasks cannot read more source');
+  if (state.enforced && Date.parse(state.grant.expiresAt) <= now) fail('ENTROROVE_BUDGET_LEASE_EXPIRED', 'the cloud budget lease expired');
+}

package/local-budget-handoff-completion.mjs

@@ -0,0 +1,70 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { canonical, fail, sha } from './local-budget-grants.mjs';
+import { withBudget } from './local-budget-store.mjs';
+import { completionChallenge } from './local-task-handoff-completion-wire.mjs';
+
+const observation = new AsyncLocalStorage();
+const fields = ['home', 'repositoryRoot', 'flowId', 'challenge', 'signerConfigPath'];
+function denied(message) { fail('ENTROROVE_BUDGET_HANDOFF_REVOKED', message); }
+function fixedInput(input) {
+  if (!input || typeof input !== 'object' || Object.keys(input).some(field => !fields.includes(field))) {
+    denied('completion observation requires its fixed native input');
+  }
+  try { return structuredClone(input); } catch { denied('completion controls must be immutable data'); }
+}
+function challengeFor(input, state, location) {
+  const retained = state.handoffRead, h = state.grant.handoff;
+  if (!state.enforced || state.closedReason || state.grant.purpose !== 'handoff-read' || h?.stage !== 'claimed'
+    || !retained || canonical(retained.handoff) !== canonical(h)
+    || canonical(retained.local) !== canonical({ home: location.home, root: location.root, flowId: location.flowId })) {
+    denied('completion observation requires the original claimed receiver budget and home');
+  }
+  const challenge = completionChallenge(input.challenge, retained.proof, { flowId: location.flowId, repo: location.repositoryDigest });
+  if (challenge.ownerId !== state.grant.ownerId || challenge.taskId !== h.receiverTaskId
+    || challenge.handoffId !== h.handoffId || challenge.messageRequestId !== h.messageRequestId
+    || challenge.epoch !== h.receiverEpoch || challenge.passDigest !== h.passDigest || challenge.leaseDigest !== h.leaseDigest
+    || canonical([...challenge.paths].sort()) !== canonical(state.grant.scope.allowedPaths)) {
+    denied('completion observation changed its signed takeover or exact source paths');
+  }
+  return challenge;
+}
+export function isBudgetHandoffCompletionObservation(input) {
+  const current = observation.getStore();
+  return Boolean(current && current.inputDigest === sha(canonical(input)));
+}
+// This entry can only invoke the fixed native completion producer. It accepts no reader or callback.
+export async function observeBudgetedTaskHandoffReceiverCompletion(input) {
+  input = fixedInput(input);
+  if (observation.getStore()) denied('completion observation cannot nest another authorization');
+  const native = await import('./local-task-handoff-fence.mjs');
+  const current = await withBudget(input, async (location, loaded) => {
+    const state = loaded?.state;
+    const nativeState = state?.grant?.purpose === 'handoff-read' ? await native.readTaskHandoffFence(input) : null;
+    const replay = nativeState?.receiverCompletion && !nativeState.receiverRestoration
+      && canonical(nativeState.receiverCompletion.challenge) === canonical(input.challenge);
+    const challenge = state?.grant?.purpose === 'handoff-read' && !replay ? challengeFor(input, state, location) : null;
+    return Object.freeze({ inputDigest: sha(canonical(input)), input, location,
+      grantId: challenge ? state.grant.grantId : null, challenge });
+  }, true);
+  return observation.run(current, () => native.observeTaskHandoffReceiverCompletion(input));
+}
+export function budgetHandoffCompletionValidationState(state) {
+  const current = observation.getStore();
+  if (!current?.challenge || current.grantId !== state.grant?.grantId) return state;
+  return { ...state, grant: { ...state.grant, expiresAt: current.challenge.expiresAt } };
+}
+export function assertBudgetHandoffCompletionRead(input, state, nativeState) {
+  const current = observation.getStore();
+  if (!current?.challenge) return false;
+  if (input.sourceRole?.startsWith('git-') || current.grantId !== state.grant?.grantId || input.flowId !== current.location.flowId
+    || input.home !== current.location.home || input.repositoryRoot !== current.location.root
+    || !current.challenge.paths.includes(input.path) || nativeState.receiverRestoration
+    || !nativeState.receiverClaim || canonical(nativeState.receiverClaim) !== canonical(state.handoffRead?.proof)
+    || nativeState.epoch !== state.grant.handoff.receiverEpoch
+    || !['active', 'paused'].includes(nativeState.status)
+    || nativeState.receiverCompletion && Date.parse(nativeState.receiverCompletion.receipt.expiresAt) > Date.now()) {
+    denied('completion source read is outside its fixed original live observation');
+  }
+  challengeFor(current.input, state, current.location);
+  return true;
+}

package/local-budget-handoff-contracts.mjs

@@ -0,0 +1,53 @@
+import { integer, ledgerIdentifier, object, record, sha256 } from './local-contract-types.mjs';
+import { HANDOFF_PROVISIONAL_LEASE_SCHEMA, HANDOFF_SNAPSHOT_CANDIDATE_SCHEMA,
+  HANDOFF_WRITE_PASS_SCHEMA } from './local-task-handoff-contracts.mjs';
+import { HANDOFF_RESTORATION_FIELDS } from './local-task-handoff-overlay-wire.mjs';
+
+const leased = HANDOFF_PROVISIONAL_LEASE_SCHEMA.properties;
+const inspection = Object.fromEntries(Object.entries(leased).filter(([field]) =>
+  !['generation', 'passId', 'passDigest', 'claimReceiptId'].includes(field)));
+inspection.purpose = { const: 'scope-inspection' };
+inspection.mutationAllowed = { const: false };
+inspection.baselineReceiptDigest = sha256;
+export const HANDOFF_BUDGET_CANDIDATE_LEASE_SCHEMA = object(inspection, Object.keys(inspection));
+const timestamp = leased.issuedAt;
+function restorationField(field) {
+  if (field === 'schemaVersion') return { const: 'entrorove.task-handoff-receiver-restoration/1.0' };
+  if (field === 'localRepositoryDigest') return leased.localRepositoryDigest;
+  if (field.endsWith('Digest')) return sha256;
+  if (['epoch', 'previousEpoch'].includes(field)) return integer(0, 2147483647);
+  if (field === 'paths') return leased.paths;
+  if (['issuedAt', 'expiresAt'].includes(field)) return timestamp;
+  if (['revokedPassIds', 'revokedLeaseIds'].includes(field)) return { type: 'array', items: ledgerIdentifier, minItems: 1, uniqueItems: true };
+  return ledgerIdentifier;
+}
+const restoration = Object.fromEntries(HANDOFF_RESTORATION_FIELDS.map(field => [field, restorationField(field)]));
+restoration.authorityReceipt = leased.authorityReceipt;
+export const HANDOFF_BUDGET_RESTORATION_SCHEMA = object(restoration, Object.keys(restoration));
+export const HANDOFF_BUDGET_INIT_PROPERTIES = {
+  handoffCandidate: HANDOFF_SNAPSHOT_CANDIDATE_SCHEMA, provisionalLease: HANDOFF_BUDGET_CANDIDATE_LEASE_SCHEMA,
+};
+export const HANDOFF_BUDGET_INIT_CONDITION = {
+  if: { type: 'object', anyOf: [
+    { properties: { grant: { type: 'object', properties: { purpose: { const: 'handoff-read' } }, required: ['purpose'] } }, required: ['grant'] },
+    { required: ['handoffCandidate'] }, { required: ['provisionalLease'] },
+  ] },
+  then: { type: 'object', required: ['grant', 'handoffCandidate', 'provisionalLease'],
+    properties: { grant: { type: 'object', properties: { purpose: { const: 'handoff-read' }, kind: { const: 'init' } }, required: ['purpose', 'kind'] } } },
+};
+function grant(kind, purpose) {
+  return { ...record, properties: { kind: { const: kind }, ...(purpose ? { purpose: { const: purpose } } : {}) },
+    required: ['kind', ...(purpose ? ['purpose'] : [])] };
+}
+export function handoffBudgetOperationSchema(flow, mode, executionContext) {
+  const required = ['repositoryRoot', 'home', 'flowId', 'grant'];
+  return { oneOf: [
+    object({ ...flow, grant: grant('handoff-read', 'handoff-read'), mode, executionContext, ...HANDOFF_BUDGET_INIT_PROPERTIES },
+      [...required, 'handoffCandidate', 'provisionalLease']),
+    object({ ...flow, grant: grant('handoff-claim', 'handoff-read'), pass: HANDOFF_WRITE_PASS_SCHEMA,
+      lease: HANDOFF_PROVISIONAL_LEASE_SCHEMA, challenge: HANDOFF_SNAPSHOT_CANDIDATE_SCHEMA },
+      [...required, 'pass', 'lease', 'challenge']),
+    object({ ...flow, grant: grant('handoff-restore'), authorization: HANDOFF_BUDGET_RESTORATION_SCHEMA },
+      [...required, 'authorization']),
+  ] };
+}