@entrorove/skill 0.1.71 → 0.1.78

package/scope-context-remote.mjs

@@ -6,6 +6,8 @@ import { acknowledgeAutomaticFeedback, queryAutomaticFeedback, verifyAutomaticFe
 import { readInvocations } from './local-invocations.mjs';
 import { saveContextJournal } from './scope-context-state.mjs';
 import { contextFail } from './scope-context-wire.mjs';
+import { prerequisiteError, retainPrerequisite, retryKnownPrerequisite } from './service-prerequisite.mjs';
+import { consumeRecovery } from './local-recovery-budget.mjs';
 
 const unknown = requestId => Object.assign(new Error('Context recovery outcome is unknown; query its original request with GET only'),
   { code: 'ENTROROVE_SCOPE_CONTEXT_UNKNOWN', outcomeUnknown: true, requestId });
@@ -15,6 +17,8 @@ async function recover(pending, dependencies) {
     const response = await requestTransport(origin, `/api/skill/status/${pending.requestId}`, {
       headers: { authorization: `Bearer ${token}`, ...ideClientHeaders() } });
     const result = parseTransportResponse(response, 'original context recovery status');
+    const prerequisite = prerequisiteError(response, result, { requestId: pending.requestId });
+    if (prerequisite) throw Object.assign(unknown(pending.requestId), { servicePrerequisite: prerequisite.servicePrerequisite });
     if (result?.output?.requestId !== pending.requestId || !response.ok || ['running', 'pending'].includes(result.output.status)) throw unknown(pending.requestId);
     if (pending.operation !== 'scope-runner-context-status' || result.feedback) {
       result.feedback ??= await queryAutomaticFeedback(pending.requestId, dependencies);
@@ -22,7 +26,8 @@ async function recover(pending, dependencies) {
       result.feedback = await acknowledgeAutomaticFeedback(result.feedback, origin, token, ideClientHeaders());
     }
     return { response, result };
-  } catch { throw unknown(pending.requestId); }
+  } catch (error) { throw Object.assign(unknown(pending.requestId),
+    error?.servicePrerequisite ? { servicePrerequisite: error.servicePrerequisite } : {}); }
 }
 async function notSent(pending, home) {
   try {
@@ -30,31 +35,37 @@ async function notSent(pending, home) {
     return !rows.length || rows.at(-1).event === 'not-sent';
   } catch (error) { return error.code === 'ENOENT'; }
 }
-export async function contextRemote(stage, operation, input, state, location, dependencies) {
+export async function contextRemote(stage, operation, input, state, location, dependencies, save = saveContextJournal) {
   const requestId = buildInvocation(operation, input).requestId; let response, result;
-  if (state.pending) {
+  const existing = Boolean(state.pending);
+  if (existing) {
     if (state.pending.stage !== stage || state.pending.requestId !== requestId || state.pending.operation !== operation
       || canonical(state.pending.input) !== canonical(input)) contextFail('Recover the original context POST before another operation');
+  }
+  if (existing && !await retryKnownPrerequisite(state, location, save)) {
+    consumeRecovery(state, 'status'); await save(location, state);
     ({ response, result } = await recover(state.pending, dependencies));
-  } else {
-    state.pending = { stage, operation, input, requestId }; await saveContextJournal(location, state);
+  }
+  else {
+    if (!existing) { state.pending = { stage, operation, input, requestId }; await save(location, state); }
     try { ({ response, result } = await invokeRemoteResult({ operation, input }, dependencies)); }
     catch (error) {
+      if (await retainPrerequisite(error, state, location, save)) throw error;
       if (await notSent(state.pending, dependencies.home)) {
-        delete state.pending; await saveContextJournal(location, state);
+        delete state.pending; await save(location, state);
         throw Object.assign(new Error('Context request was not transmitted; repair its prerequisite and reuse the original input'),
           { code: 'ENTROROVE_SCOPE_CONTEXT_NOT_SENT', knownBeforeTransmission: true, requestId });
       }
-      throw unknown(requestId);
+      throw Object.assign(unknown(requestId), error?.servicePrerequisite ? { servicePrerequisite: error.servicePrerequisite } : {});
     }
   }
   if (!result?.output || result.output.requestId !== requestId) throw unknown(requestId);
   if (result.feedback) state.feedback = result.feedback;
   if (!response.ok || !['succeeded', 'needs-input'].includes(result.output.status)) {
-    state.rejection = { requestId, output: result.output }; delete state.pending; await saveContextJournal(location, state);
+    state.rejection = { requestId, output: result.output }; delete state.pending; await save(location, state);
     throw Object.assign(new Error('Original context request was rejected; preserve its exact evidence and history'),
       { code: result.output.code ?? 'ENTROROVE_SCOPE_CONTEXT_REJECTED', requestId, output: result.output });
   }
-  state[stage] = result.output.result ?? result.output; delete state.pending; await saveContextJournal(location, state);
+  state[stage] = result.output.result ?? result.output; delete state.pending; await save(location, state);
   return state[stage];
 }

package/scope-context-state.mjs

@@ -8,6 +8,7 @@ import { mutationHome14, mutationFile14, readMutationJson14, atomicMutationJson1
 import { trustedOrigin } from './remote-transport.mjs';
 import { contextExact, contextFail, contextList, validateContextAuthority } from './scope-context-wire.mjs';
 import { hydrateCloudMutationAuthority, bootstrapCloudMutationAuthority } from './cloud-mutation-authority.mjs';
+import { readScopeEvidence } from './scope-evidence-local.mjs';
 
 export async function contextPrivate(file, final = 'file', maximumBytes = 8_000_000) {
   const item = await mutationFile14(file, { final });
@@ -53,6 +54,7 @@ export async function effectiveScopeContexts(location) {
   for (const name of names) {
     const file = path.join(directory, name); await contextPrivate(file, 'file', 1_000_000);
     const saved = await readMutationJson14(file), checked = validateContextAuthority(saved.record, location, current);
+    if (checked.record.attestationRef) await readScopeEvidence(location, checked.record.attestationRef);
     if (saved.revisionDigest !== checked.revisionDigest || name !== `${String(checked.record.revision).padStart(6, '0')}-${checked.revisionDigest}.json`) contextFail('Context history checksum or order changed');
     current = checked;
   }
@@ -68,6 +70,7 @@ export async function retainContextAuthority(location, effective) {
   const current = await effectiveScopeContexts(location);
   if (current?.revisionDigest === effective?.revisionDigest && canonical(current.record) === canonical(effective.record)) return current;
   const checked = validateContextAuthority(effective?.record, location, current);
+  if (checked.record.attestationRef) await readScopeEvidence(location, checked.record.attestationRef);
   if (effective.revisionDigest !== checked.revisionDigest) contextFail('Applied context authority checksum changed');
   const directory = path.join(location.base, 'context-authority'), file = path.join(directory, `${String(checked.record.revision).padStart(6, '0')}-${checked.revisionDigest}.json`);
   await atomicMutationJson14(file, checked, { privateFrom: location.stateRoot }); return checked;
@@ -77,7 +80,7 @@ export async function readContextJournal(location, input) {
     await contextPrivate(location.file);
     const value = await readMutationJson14(location.file);
     if (value.schemaVersion !== 'entrorove.scope-context-journal/1.0' || value.localBindingDigest !== location.localBindingDigest) contextFail('Context journal cannot replace its original identity');
-    if (value.pending && canonical(value.input) !== canonical(input)) contextFail('Recover the original pending context request before another operation');
+    if ((value.pending || value.evidencePending) && canonical(value.input) !== canonical(input)) contextFail('Recover the original pending context request before another operation');
     return canonical(value.input) === canonical(input) ? value : { previous: value };
   } catch (error) { if (error.code === 'ENOENT') return {}; throw error; }
 }

package/scope-context-wire.mjs

@@ -1,6 +1,7 @@
 import { canonical, sha256 } from './local-integrity.mjs';
 import { scopeFail, scopePath } from './local-scope-files.mjs';
 import { scopeRevisionAuthority } from './scope-amendment-wire.mjs';
+import { evidenceReference } from './scope-evidence-wire.mjs';
 
 const id = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/;
 const hash = /^[a-f0-9]{64}$/;
@@ -51,7 +52,8 @@ export function contextInput(input) {
 export const originalContextDigest = location => sha256(canonical({ localBindingDigest: location.localBindingDigest,
   importContexts: location.binding.importContexts }));
 export function validateContextAuthority(value, location, previous) {
-  const record = scopeRevisionAuthority(value, 'entrorove.scope-context-authority/1.0');
+  const version = value?.schemaVersion === 'entrorove.scope-context-authority/2.0' ? '2.0' : '1.0';
+  const record = scopeRevisionAuthority(value, `entrorove.scope-context-authority/${version}`);
   const expectedRevision = (previous?.record.revision ?? 0) + 1;
   if (['flowId', 'runnerId', 'repositoryId', 'keyId'].some(field => record[field] !== location.binding[field])
     || record.localBindingDigest !== location.localBindingDigest || record.revision !== expectedRevision
@@ -64,6 +66,12 @@ export function validateContextAuthority(value, location, previous) {
   contextEvidence(record.evidence);
   if (previous && ['ownerId', 'taskDigest', 'chainDigest'].some(field => record[field] !== previous.record[field])
     || record.importContexts.some(context => !record.evidence.some(file => file.path === context.configPath))) contextFail('Context authority lost its original task or actual configuration evidence');
+  if (version === '2.0') {
+    const reference = evidenceReference(record.attestationRef, undefined, location);
+    if (reference.kind !== 'scope-context' || Object.hasOwn(record, 'attestation')
+      || ['flowId', 'ownerId', 'taskDigest', 'chainDigest', 'proposalId', 'proposalDigest', 'challengeId'].some(field => record[field] !== reference[field])
+      || !hash.test(record.challengeDigest ?? '')) contextFail('Compact context authority lost its exact evidence binding');
+  }
   return { record, revisionDigest: sha256(canonical(record)) };
 }
 export function contextChallenge(value, location, proposal, { allowExpired = false } = {}) {

package/scope-evidence-local.mjs

@@ -0,0 +1,52 @@
+import { constants, promises as fs } from 'node:fs';
+import path from 'node:path';
+import { mutationFile14, writeMutationFile14 } from './local-mutation-files.mjs';
+import { maximumScopeEvidenceBytes, evidenceFail, verifyEvidenceData } from './scope-evidence-wire.mjs';
+
+function evidencePath(location, descriptor) {
+  if (!/^[a-f0-9]{64}$/.test(descriptor?.sha256 ?? '')) evidenceFail('Scope evidence requires its exact SHA256 derived private data file');
+  return path.join(location.base, 'evidence-data', `${descriptor.sha256}.json`);
+}
+async function privateEvidence(file) {
+  const item = await mutationFile14(file);
+  if (process.getuid && item.stat.uid !== process.getuid() || process.platform !== 'win32' && (item.stat.mode & 0o777) !== 0o600
+    || item.stat.nlink !== 1 || item.stat.size < 1 || item.stat.size > maximumScopeEvidenceBytes) evidenceFail('Scope evidence must remain a bounded private single-link data file');
+  const directory = await mutationFile14(path.dirname(file), { final: 'directory' });
+  if (process.getuid && directory.stat.uid !== process.getuid()
+    || process.platform !== 'win32' && (directory.stat.mode & 0o777) !== 0o700) evidenceFail('Scope evidence directory must remain private');
+  return item;
+}
+export async function readScopeEvidence(location, descriptor) {
+  const file = evidencePath(location, descriptor), before = await privateEvidence(file);
+  const handle = await fs.open(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  try {
+    const opened = await handle.stat();
+    const changed = stat => ['dev', 'ino', 'size', 'mtimeMs', 'ctimeMs', 'mode', 'nlink', 'uid'].some(field => stat[field] !== before.stat[field]);
+    if (changed(opened) || opened.size !== descriptor.canonicalBytes) evidenceFail('Scope evidence changed before its bounded private read');
+    const buffer = Buffer.alloc(opened.size + 1); let length = 0;
+    while (length < buffer.length) {
+      const chunk = await handle.read(buffer, length, buffer.length - length, length);
+      if (!chunk.bytesRead) break; length += chunk.bytesRead;
+    }
+    const bytes = buffer.subarray(0, length), after = await handle.stat(), latest = await privateEvidence(file);
+    if ([opened, after, latest.stat].some(stat => ['dev', 'ino', 'size', 'mtimeMs', 'ctimeMs', 'mode', 'nlink', 'uid']
+      .some(field => stat[field] !== before.stat[field])) || latest.ancestors.length !== before.ancestors.length
+      || latest.ancestors.some((item, index) => item.path !== before.ancestors[index].path
+        || item.stat.dev !== before.ancestors[index].stat.dev || item.stat.ino !== before.ancestors[index].stat.ino)) evidenceFail('Scope evidence changed during its stable private read');
+    let value;
+    try { value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)); }
+    catch { evidenceFail('Scope evidence data has invalid UTF8 JSON'); }
+    if (!verifyEvidenceData(value, descriptor, location).equals(bytes)) evidenceFail('Scope evidence data lost its exact canonical bytes');
+    return value;
+  } finally { await handle.close(); }
+}
+export async function retainScopeEvidence(location, descriptor, value) {
+  const bytes = verifyEvidenceData(value, descriptor, location), file = evidencePath(location, descriptor);
+  try { await readScopeEvidence(location, descriptor); }
+  catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    await writeMutationFile14(file, bytes, { privateFrom: location.stateRoot });
+    await readScopeEvidence(location, descriptor);
+  }
+  return descriptor;
+}

package/scope-evidence-remote.mjs

@@ -0,0 +1,87 @@
+import { canonical, sha256 } from './local-integrity.mjs';
+import { contextRemote } from './scope-context-remote.mjs';
+import { readScopeEvidence, retainScopeEvidence } from './scope-evidence-local.mjs';
+import { describeScopeEvidence, evidenceBytes, evidenceFail, evidenceUpload, evidenceReference } from './scope-evidence-wire.mjs';
+import { requestTransport, putScopeEvidence, parseTransportResponse } from './remote-transport.mjs';
+import { ideClientHeaders } from './ide-presentation.mjs';
+import { prerequisiteError, retainPrerequisite, retryKnownPrerequisite } from './service-prerequisite.mjs';
+
+const unknown = uploadId => Object.assign(new Error('Scope evidence upload outcome is unknown; recover the original reservation with GET only'),
+  { code: 'ENTROROVE_SCOPE_EVIDENCE_UNKNOWN', outcomeUnknown: true, uploadId });
+export async function saveLocalScopeEvidence(value, kind, challenge, state, location, save) {
+  const described = describeScopeEvidence(kind, value, challenge, location);
+  await retainScopeEvidence(location, described.descriptor, value);
+  state.evidenceDescriptor = described.descriptor; state.evidenceSignature = described.signature;
+  state.attestationDigest = described.descriptor.sha256;
+  delete state.attestation;
+  await save(location, state);
+}
+function resultReference(value, upload, descriptor, location) {
+  if (value?.schemaVersion !== 'entrorove.scope-evidence-upload-status/1.0' || value.uploadId !== upload.uploadId
+    || value.grantsExecutionAuthority !== false || value.expiresAt !== upload.expiresAt
+    || !['reserved', 'receiving', 'stored', 'rejected'].includes(value.status)) throw unknown(upload.uploadId);
+  if (value.status !== 'stored') return null;
+  const reference = evidenceReference(value.evidenceReference, descriptor, location);
+  if (['ownerId', 'taskDigest', 'chainDigest'].some(field => reference[field] !== upload[field])) evidenceFail('Stored scope evidence replaced its original account or task');
+  return reference;
+}
+async function acceptResult(response, upload, state, location, save, sentPut = false) {
+  let value;
+  try { value = parseTransportResponse(response, 'scope evidence upload'); }
+  catch { throw unknown(upload.uploadId); }
+  const prerequisite = prerequisiteError(response, value, { uploadId: upload.uploadId });
+  if (prerequisite) {
+    if (sentPut && await retainPrerequisite(prerequisite, state, location, save, 'evidencePending')) throw prerequisite;
+    throw Object.assign(unknown(upload.uploadId), { servicePrerequisite: prerequisite.servicePrerequisite });
+  }
+  const reference = resultReference(value, upload, state.evidenceDescriptor, location);
+  if (reference) {
+    state.attestationRef = reference; state.evidenceResult = value; delete state.evidencePending;
+    await save(location, state); return reference;
+  }
+  if (value.status === 'rejected' && /^ENTROROVE_EVIDENCE_[A-Z_]+$/.test(value.code ?? '')) {
+    state.evidenceResult = value; state.rejection = { uploadId: upload.uploadId, output: value };
+    delete state.evidencePending; await save(location, state);
+    throw Object.assign(new Error('The original evidence reservation was rejected; preserve it before another signed attempt'),
+      { code: value.code, uploadId: upload.uploadId, output: value });
+  }
+  throw unknown(upload.uploadId);
+}
+export async function ensureScopeEvidence(state, location, dependencies, challenge, save) {
+  const descriptor = state.evidenceDescriptor;
+  if (!descriptor || !state.evidenceSignature) evidenceFail('Original signed evidence descriptor is unavailable');
+  const value = await readScopeEvidence(location, descriptor);
+  if (state.attestationRef) return evidenceReference(state.attestationRef, descriptor, location);
+  if (!state.evidencePrepared) await contextRemote('evidencePrepared', 'scope-evidence-prepare', {
+    flowId: descriptor.flowId, descriptor, signature: state.evidenceSignature }, state, location, dependencies, save);
+  const upload = evidenceUpload(state.evidencePrepared.upload, descriptor, location, challenge);
+  const token = await dependencies.readCredential(dependencies.home), headers = { authorization: `Bearer ${token}`, ...ideClientHeaders() };
+  const origin = dependencies.apiOrigin();
+  const existing = Boolean(state.evidencePending);
+  if (existing) {
+    if (state.evidencePending.uploadId !== upload.uploadId || state.evidencePending.sha256 !== descriptor.sha256
+      || state.evidencePending.canonicalBytes !== descriptor.canonicalBytes) evidenceFail('Recover the exact original evidence reservation first');
+  }
+  if (existing && !await retryKnownPrerequisite(state, location, save, 'evidencePending')) {
+    let response;
+    try { response = await requestTransport(origin, `/api/skill/evidence/${upload.uploadId}`, { headers }); }
+    catch { throw unknown(upload.uploadId); }
+    return acceptResult(response, upload, state, location, save);
+  }
+  if (!existing) { state.evidencePending = { uploadId: upload.uploadId, sha256: descriptor.sha256, canonicalBytes: descriptor.canonicalBytes };
+    await save(location, state); }
+  let response; const sentPut = Date.parse(upload.expiresAt) > Date.now();
+  try {
+    if (!sentPut) response = await requestTransport(origin, `/api/skill/evidence/${upload.uploadId}`, { headers });
+    else response = await putScopeEvidence(origin, upload.uploadId, evidenceBytes(value), headers);
+  } catch { throw unknown(upload.uploadId); }
+  return acceptResult(response, upload, state, location, save, sentPut);
+}
+export async function validateAppliedEvidence(record, state, location, challenge, kind) {
+  const reference = evidenceReference(kind === 'scope-context' ? record.attestationRef : record.candidateAttestationRef,
+    state.evidenceDescriptor, location);
+  if (reference.kind !== kind || canonical(reference) !== canonical(state.attestationRef)
+    || record.challengeId !== challenge.challengeId || record.challengeDigest !== sha256(canonical(challenge))
+    || ['ownerId', 'taskDigest', 'chainDigest'].some(field => reference[field] !== challenge[field])) evidenceFail('Applied authority differs from its original uploaded S evidence');
+  return readScopeEvidence(location, reference);
+}

package/scope-evidence-wire.mjs

@@ -0,0 +1,120 @@
+import { createPublicKey, sign, verify } from 'node:crypto';
+import { canonical, sha256 } from './local-integrity.mjs';
+import { scopeRevisionAuthority } from './scope-amendment-wire.mjs';
+
+export const maximumScopeEvidenceBytes = 16_000_000;
+const hash = /^[a-f0-9]{64}$/, id = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/;
+const common = ['kind', 'flowId', 'challengeId', 'runnerId', 'repositoryId', 'keyId', 'sha256', 'canonicalBytes'];
+export const evidenceFail = message => { throw Object.assign(new Error(message), { code: 'ENTROROVE_SCOPE_EVIDENCE_BINDING' }); };
+function exact(value, fields) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || Object.keys(value).sort().join('\0') !== [...fields].sort().join('\0')) evidenceFail('Scope evidence fields are invalid');
+}
+function validString(value) {
+  if (value.includes('\0') || Buffer.byteLength(value) > maximumScopeEvidenceBytes) evidenceFail('Scope evidence string exceeds its valid bounded UTF8 representation');
+  for (let index = 0; index < value.length; index++) {
+    const code = value.charCodeAt(index);
+    if (code >= 0xd800 && code <= 0xdbff) {
+      const next = value.charCodeAt(++index);
+      if (!(next >= 0xdc00 && next <= 0xdfff)) evidenceFail('Scope evidence contains an invalid Unicode surrogate');
+    } else if (code >= 0xdc00 && code <= 0xdfff) evidenceFail('Scope evidence contains an invalid Unicode surrogate');
+  }
+}
+export function evidenceBytes(value) {
+  const stack = [[value, 0, false]], ancestors = new Set(); let nodes = 0;
+  while (stack.length) {
+    const [item, depth, leaving] = stack.pop();
+    if (leaving) { ancestors.delete(item); continue; }
+    if (++nodes > 250_000 || depth > 64) evidenceFail('Scope evidence exceeds its bounded structure');
+    if (typeof item === 'string') { validString(item); continue; }
+    if (item === null || typeof item === 'boolean') continue;
+    if (typeof item === 'number' && Number.isFinite(item)) continue;
+    if (!item || typeof item !== 'object' || ancestors.has(item)
+      || !Array.isArray(item) && ![Object.prototype, null].includes(Object.getPrototypeOf(item))) evidenceFail('Scope evidence requires finite acyclic JSON');
+    ancestors.add(item); stack.push([item, depth, true]);
+    const fields = Object.getOwnPropertyDescriptors(item), keys = Reflect.ownKeys(fields);
+    if (Array.isArray(item) ? item.length > 100_000 : keys.length > 1024) evidenceFail('Scope evidence collection exceeds its bounded structure');
+    for (const key of keys) {
+      if (Array.isArray(item) && key === 'length') continue;
+      const field = fields[key];
+      if (typeof key !== 'string' || !Object.hasOwn(field, 'value') || !field.enumerable) evidenceFail('Scope evidence refuses accessors and non-JSON properties');
+      validString(key);
+      stack.push([field.value, depth + 1, false]);
+    }
+  }
+  const bytes = Buffer.from(canonical(value));
+  if (!bytes.length || bytes.length > maximumScopeEvidenceBytes) evidenceFail('Scope evidence exceeds its separate sixteen million byte data limit');
+  return bytes;
+}
+export function evidenceFields(value) {
+  if (!['scope-context', 'scope-revision', 'scope-refresh', 'scope-observation'].includes(value?.kind)) evidenceFail('Scope evidence kind is invalid');
+  return [...common, ...(value.kind === 'scope-observation' ? ['stepId'] : ['proposalId', 'proposalDigest'])];
+}
+export function validateEvidenceIdentity(value, expected, location) {
+  for (const field of evidenceFields(value)) {
+    if (field === 'canonicalBytes') {
+      if (!Number.isSafeInteger(value[field]) || value[field] < 1 || value[field] > maximumScopeEvidenceBytes) evidenceFail('Scope evidence byte length is invalid');
+    } else if (!(['sha256', 'keyId', 'proposalDigest'].includes(field) ? hash : id).test(value[field] ?? '')) evidenceFail('Scope evidence identity is invalid');
+    if (expected && value[field] !== expected[field]) evidenceFail('Scope evidence reference replaced its exact original data identity');
+  }
+  if (location && ['flowId', 'runnerId', 'repositoryId', 'keyId'].some(field => value[field] !== location.binding[field])) {
+    evidenceFail('Scope evidence replaced its original local signer binding');
+  }
+  return value;
+}
+function signature(value, key) {
+  const { signature: encoded, ...core } = value ?? {};
+  if (typeof encoded !== 'string' || !/^[A-Za-z0-9_-]{86}$/.test(encoded)
+    || Buffer.from(encoded, 'base64url').toString('base64url') !== encoded
+    || !verify(null, Buffer.from(canonical(core)), key, Buffer.from(encoded, 'base64url'))) evidenceFail('Original scope evidence S signature changed');
+}
+export function verifyEvidenceData(value, descriptor, location) {
+  validateEvidenceIdentity(descriptor, undefined, location);
+  const bytes = evidenceBytes(value);
+  if (sha256(bytes) !== descriptor.sha256 || bytes.length !== descriptor.canonicalBytes) evidenceFail('Scope evidence hash or canonical UTF8 length changed');
+  const key = createPublicKey({ key: Buffer.from(location.binding.publicKey, 'base64'), type: 'spki', format: 'der' });
+  if (sha256(key.export({ type: 'spki', format: 'der' })) !== descriptor.keyId) evidenceFail('Scope evidence original public key changed');
+  signature(value, key);
+  const observation = descriptor.kind === 'scope-observation', inner = observation ? value : value.scopeAttestation;
+  if (!observation) signature(inner, key);
+  if (inner?.schemaVersion !== 'entrorove.scope-facts/1.0'
+    || ['flowId', 'repositoryId', 'keyId'].some(field => inner[field] !== descriptor[field])
+    || observation && (inner.challenge !== descriptor.challengeId || inner.stepId !== descriptor.stepId)
+    || !observation && value.proposalDigest !== descriptor.proposalDigest
+    || descriptor.kind === 'scope-context' && (value.schemaVersion !== 'entrorove.scope-context-attestation/1.0' || value.challengeId !== descriptor.challengeId)
+    || ['scope-revision', 'scope-refresh'].includes(descriptor.kind) && (value.schemaVersion !== 'entrorove.scope-revision-attestation/1.0'
+      || value.proposalId !== descriptor.proposalId || value.purpose !== (descriptor.kind === 'scope-refresh' ? 'scope-revision-refresh' : 'scope-revision'))
+    || ['ownerId', 'taskDigest', 'chainDigest'].some(field => descriptor[field] !== undefined && inner[field] !== descriptor[field])) {
+    evidenceFail('Scope evidence has another original kind, task or challenge');
+  }
+  return bytes;
+}
+export function describeScopeEvidence(kind, value, challenge, location) {
+  const bytes = evidenceBytes(value), observation = kind === 'scope-observation';
+  const descriptor = { schemaVersion: 'entrorove.scope-evidence-descriptor/1.0', kind, flowId: challenge.flowId,
+    ...(observation ? { stepId: challenge.stepId } : { proposalId: challenge.proposalId, proposalDigest: challenge.proposalDigest }),
+    challengeId: observation ? challenge.challenge : challenge.challengeId, runnerId: location.binding.runnerId,
+    repositoryId: location.binding.repositoryId, keyId: location.binding.keyId, sha256: sha256(bytes), canonicalBytes: bytes.length };
+  verifyEvidenceData(value, descriptor, location);
+  const inner = observation ? value : value.scopeAttestation;
+  if (['flowId', 'ownerId', 'taskDigest', 'chainDigest', 'repositoryId', 'stepId', 'challenge'].some(field => inner[field] !== challenge[field])
+    || Date.parse(inner.expiresAt) > Date.parse(challenge.expiresAt)) evidenceFail('Scope evidence differs from its exact original challenge');
+  return { descriptor, signature: sign(null, Buffer.from(canonical(descriptor)), location.key).toString('base64url') };
+}
+export function evidenceReference(value, expected, location) {
+  exact(value, ['schemaVersion', 'evidenceId', ...evidenceFields(value), 'ownerId', 'taskDigest', 'chainDigest']);
+  if (value.schemaVersion !== 'entrorove.scope-evidence-reference/1.0' || !id.test(value.evidenceId ?? '')
+    || !id.test(value.ownerId ?? '') || !hash.test(value.taskDigest ?? '') || !hash.test(value.chainDigest ?? '')) evidenceFail('Scope evidence reference is invalid');
+  return validateEvidenceIdentity(value, expected, location);
+}
+export function evidenceUpload(value, descriptor, location, challenge) {
+  const upload = scopeRevisionAuthority(value, 'entrorove.scope-evidence-upload/1.0');
+  exact(upload, ['schemaVersion', ...evidenceFields(upload), 'uploadId', 'ownerId', 'taskDigest', 'chainDigest', 'issuedAt', 'expiresAt', 'grantsExecutionAuthority', 'authorityReceipt']);
+  validateEvidenceIdentity(upload, descriptor, location);
+  const issued = Date.parse(upload.issuedAt), expires = Date.parse(upload.expiresAt);
+  if (!id.test(upload.uploadId ?? '') || upload.grantsExecutionAuthority !== false
+    || ['ownerId', 'taskDigest', 'chainDigest'].some(field => upload[field] !== challenge[field])
+    || !Number.isFinite(issued) || !Number.isFinite(expires) || expires <= issued || expires - issued > 90_000
+    || expires > Date.parse(challenge.expiresAt)) evidenceFail('Scope evidence upload replaced its original challenge or authority');
+  return upload;
+}

package/scope-runner-client.mjs

@@ -1,3 +1,4 @@
+import { prerequisiteFields } from './service-prerequisite.mjs';
 import { createPrivateKey, createPublicKey, generateKeyPairSync, randomUUID, sign } from 'node:crypto';
 import { constants, promises as fs } from 'node:fs';
 import path from 'node:path';
@@ -6,8 +7,12 @@ import { scopeFail, scopePath, scopeRoot, scopeTarget } from './local-scope-file
 import { withStateLock } from './local-state-lock.mjs';
 import { snapshotPlan, snapshotVerify } from './local-execution.mjs';
 import { probe } from './local-probe.mjs';
-import { invokeRemoteResult } from './remote-client.mjs';
+import { recoveryFailureFields } from './local-recovery-budget.mjs';
+import { contextRemote } from './scope-context-remote.mjs';
+import { scopeRunnerJournal, saveScopeRunnerJournal, renewScopeRunnerChallenge, validateScopeRunnerChallenge } from './scope-runner-journal.mjs';
+import { saveLocalScopeEvidence, ensureScopeEvidence } from './scope-evidence-remote.mjs';
 import { boundScopeContexts } from './scope-context-state.mjs';
+import { mutationFile14 } from './local-mutation-files.mjs';
 
 async function privateDirectory(directory) {
   await fs.mkdir(directory, { recursive: true, mode: 0o700 });
@@ -54,38 +59,7 @@ async function signer(directory, identity, dependencies) {
   }
   return { binding, key, signerConfigPath: path.join(controls, 'signer.json'), contextAuthority };
 }
-async function remote(operation, input, dependencies) {
-  const { response, result } = await invokeRemoteResult({ operation, input }, dependencies);
-  if (!response.ok || result.output.status !== 'succeeded') {
-    throw Object.assign(new Error(result.output.message ?? `Scope connection blocked at ${operation}`),
-      { code: result.output.code ?? 'ENTROROVE_SCOPE_BLOCKED', output: result.output });
-  }
-  return result.output;
-}
-async function connect(identity, directory, dependencies) {
-  const { binding, key, signerConfigPath, contextAuthority } = await signer(directory, identity, dependencies);
-  const prepared = await remote('scope-runner-prepare', { flowId: identity.flowId, attemptId: randomUUID(), runnerId: binding.runnerId,
-    repositoryId: binding.repositoryId, publicKey: binding.publicKey, targetPaths: identity.targetPaths }, dependencies);
-  const enrollment = prepared.enrollment;
-  if (enrollment.flowId !== identity.flowId || enrollment.runnerId !== binding.runnerId || enrollment.keyId !== binding.keyId
-    || canonical(enrollment.targetPaths) !== canonical(identity.targetPaths)) scopeFail('ENTROROVE_SCOPE_BINDING', 'Cloud enrollment differs from the original local task signer');
-  await remote('scope-runner-register', { flowId: identity.flowId, enrollmentId: enrollment.enrollmentId,
-    signature: sign(null, Buffer.from(canonical(enrollment)), key).toString('base64url') }, dependencies);
-  const issued = await remote('scope-runner-challenge', { flowId: identity.flowId, receiverId: binding.runnerId, attemptId: randomUUID() }, dependencies);
-  const challenge = issued.challenge;
-  if (challenge.flowId !== identity.flowId || challenge.ownerId !== enrollment.ownerId || challenge.runnerId !== binding.runnerId
-    || challenge.repositoryId !== binding.repositoryId || challenge.taskDigest !== enrollment.taskDigest
-    || challenge.chainDigest !== enrollment.chainDigest || canonical(challenge.targetPaths) !== canonical(identity.targetPaths)) {
-    scopeFail('ENTROROVE_SCOPE_BINDING', 'Cloud scope challenge differs from the original account and accepted task');
-  }
-  const input = { repositoryRoot: identity.repositoryRoot, home: dependencies.home, flowId: identity.flowId,
-    stepId: challenge.stepId, paths: identity.targetPaths, snapshotId: `snapshot-${randomUUID()}`, importContexts: identity.importContexts,
-    ...(contextAuthority ? { contextRevisionDigest: contextAuthority.revisionDigest, contextEvidence: contextAuthority.record.evidence } : {}) };
-  const planned = await snapshotPlan(input), verified = await snapshotVerify(input);
-  if (verified.verified !== true || verified.receipt.snapshotDigest !== planned.snapshotDigest) scopeFail('ENTROROVE_SCOPE_SNAPSHOT', 'Actual copied snapshot did not verify');
-  const observed = await probe({ ...input, ownerId: challenge.ownerId, task: challenge.task, taskDigest: challenge.taskDigest,
-    chainDigest: challenge.chainDigest, repositoryId: challenge.repositoryId, challenge: challenge.challenge, signerConfigPath });
-  const accepted = await remote('scope-runner-attest', { flowId: identity.flowId, attestation: observed.attestation }, dependencies);
+async function scopeConnectionResult(identity, binding, accepted) {
   const next = accepted.nextStep ?? { operation: 'workflow-gate', payload: { targetFiles: [...identity.targetPaths] } };
   if (next.localOperation === 'scope-connect') return { schemaVersion: 'entrorove.scope-connection/1.0', status: 'succeeded',
     flowId: identity.flowId, runnerId: binding.runnerId, scopeEvidence: accepted.scopeEvidence, grantsExecutionAuthority: false,
@@ -97,6 +71,85 @@ async function connect(identity, directory, dependencies) {
     runnerId: binding.runnerId, scopeEvidence: accepted.scopeEvidence, grantsExecutionAuthority: false,
     nextOperation: next.operation, ...(resumeOriginalRequest ? { resumeOriginalRequest: true } : { nextInput }), nextStep: next };
 }
+async function verifyConnectionSnapshot(input) {
+  try { return await snapshotVerify(input); }
+  catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    const directory = path.join(input.home, '.entrorove', 'snapshots', sha256(input.repositoryRoot).slice(0, 32), input.flowId, input.snapshotId);
+    const existing = await mutationFile14(directory, { allowMissing: true, final: 'directory' });
+    if (!existing.exists) scopeFail('ENTROROVE_SCOPE_SNAPSHOT_MISSING', 'The original scope snapshot directory is unavailable; preserve its journal before another attempt');
+    if (!(await mutationFile14(path.join(directory, 'manifest.json'), { allowMissing: true })).exists) {
+      scopeFail('ENTROROVE_SCOPE_SNAPSHOT_INTERRUPTED', 'The original scope snapshot was interrupted before its manifest; preserve the partial files and repeat this exact original input to archive its rejected attempt');
+    }
+    throw error;
+  }
+}
+async function observeConnection(identity, location, state, original, contextAuthority, dependencies, remote) {
+  let challenge = (state.signingChallenge ?? state.challenged).challenge;
+  validateScopeRunnerChallenge(challenge, original, identity, location.binding, { allowExpired: true });
+  if (state.evidenceDescriptor) {
+    if (state.evidenceDescriptor.challengeId !== challenge.challenge) scopeFail('ENTROROVE_SCOPE_BINDING', 'Recover evidence against its original signing challenge');
+    return challenge;
+  }
+  const input = { repositoryRoot: identity.repositoryRoot, home: dependencies.home, flowId: identity.flowId,
+    stepId: challenge.stepId, paths: identity.targetPaths, snapshotId: state.snapshotId, importContexts: identity.importContexts,
+    ...(contextAuthority ? { contextRevisionDigest: contextAuthority.revisionDigest, contextEvidence: contextAuthority.record.evidence } : {}) };
+  if (!state.snapshotStarted) {
+    state.snapshotStarted = true; await saveScopeRunnerJournal(location, state);
+    try { await snapshotPlan(input); }
+    catch (error) { delete state.snapshotStarted; await saveScopeRunnerJournal(location, state); throw error; }
+  }
+  const verified = await verifyConnectionSnapshot(input);
+  if (verified.verified !== true) scopeFail('ENTROROVE_SCOPE_SNAPSHOT', 'Actual copied snapshot did not verify');
+  const observed = await probe({ ...input, ownerId: challenge.ownerId, task: challenge.task, taskDigest: challenge.taskDigest,
+    chainDigest: challenge.chainDigest, repositoryId: challenge.repositoryId, challenge: challenge.challenge, signerConfigPath: location.signerConfigPath },
+  { beforeSign: async () => {
+    challenge = await renewScopeRunnerChallenge(identity, location, state, original, remote);
+    return { challenge: challenge.challenge, maximumExpiresAt: Date.parse(challenge.expiresAt) };
+  } });
+  if (observed.attestation.snapshotDigest !== verified.receipt.snapshotDigest) scopeFail('ENTROROVE_SCOPE_SNAPSHOT', 'Actual S proof replaced its original verified snapshot');
+  await saveLocalScopeEvidence(observed.attestation, 'scope-observation', challenge, state, location, saveScopeRunnerJournal);
+  return challenge;
+}
+async function connect(identity, directory, dependencies) {
+  const local = await signer(directory, identity, dependencies), { binding, key, contextAuthority } = local;
+  const location = { ...local, root: identity.repositoryRoot, home: dependencies.home, base: directory,
+    stateRoot: path.join(dependencies.home, '.entrorove'), directory: path.join(directory, 'scope-connection'),
+    file: path.join(directory, 'scope-connection', 'journal.json') };
+  const state = await scopeRunnerJournal(location, identity);
+  const remote = (stage, operation, input) => contextRemote(stage, operation, input, state, location, dependencies, saveScopeRunnerJournal);
+  try {
+    if (state.pending) await remote(state.pending.stage, state.pending.operation, state.pending.input);
+    const prepared = state.prepared ?? await remote('prepared', 'scope-runner-prepare', { flowId: identity.flowId,
+      attemptId: state.attemptId, runnerId: binding.runnerId, repositoryId: binding.repositoryId, publicKey: binding.publicKey, targetPaths: identity.targetPaths });
+    const enrollment = prepared.enrollment;
+    if (enrollment.flowId !== identity.flowId || enrollment.runnerId !== binding.runnerId || enrollment.keyId !== binding.keyId
+      || canonical(enrollment.targetPaths) !== canonical(identity.targetPaths)) scopeFail('ENTROROVE_SCOPE_BINDING', 'Cloud enrollment differs from the original local task signer');
+    if (!state.registered) await remote('registered', 'scope-runner-register', { flowId: identity.flowId, enrollmentId: enrollment.enrollmentId,
+      signature: sign(null, Buffer.from(canonical(enrollment)), key).toString('base64url') });
+    const issued = state.challenged ?? await remote('challenged', 'scope-runner-challenge', { flowId: identity.flowId,
+      receiverId: binding.runnerId, attemptId: state.attemptId });
+    const challenge = issued.challenge;
+    if (challenge.flowId !== identity.flowId || challenge.ownerId !== enrollment.ownerId || challenge.runnerId !== binding.runnerId
+      || challenge.repositoryId !== binding.repositoryId || challenge.taskDigest !== enrollment.taskDigest
+      || challenge.chainDigest !== enrollment.chainDigest || canonical(challenge.targetPaths) !== canonical(identity.targetPaths)) {
+      scopeFail('ENTROROVE_SCOPE_BINDING', 'Cloud scope challenge differs from the original account and accepted task');
+    }
+    if (!state.snapshotId) { state.snapshotId = `snapshot-${randomUUID()}`; await saveScopeRunnerJournal(location, state); }
+    if (!state.accepted) {
+      const signingChallenge = await observeConnection(identity, location, state, challenge, contextAuthority, dependencies, remote);
+      const attestationRef = await ensureScopeEvidence(state, location, dependencies, signingChallenge, saveScopeRunnerJournal);
+      await remote('accepted', 'scope-runner-attest', { flowId: identity.flowId, attestationRef });
+    }
+    state.completed = true; await saveScopeRunnerJournal(location, state);
+    return scopeConnectionResult(identity, binding, state.accepted);
+  } catch (error) {
+    if (!state.pending && !state.evidencePending) {
+      state.rejection ??= { code: error.code, message: error.message }; await saveScopeRunnerJournal(location, state);
+    }
+    throw error;
+  }
+}
 export async function connectScopeRunner(repositoryRoot, input, dependencies) {
   if (!input || Object.keys(input).some(field => !['flowId', 'paths', 'importContexts'].includes(field))
     || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(input.flowId ?? '') || !Array.isArray(input.paths) || !input.paths.length) {
@@ -129,8 +182,12 @@ export async function runScopeConnect(repositoryRoot, input, dependencies) {
   if (!await dependencies.agreementAccepted(dependencies.home)) return dependencies.agreementRequired(dependencies.home);
   try { return await connectScopeRunner(repositoryRoot, input, dependencies); }
   catch (error) {
-    if (error.outcomeUnknown || !error.code?.startsWith('ENTROROVE_')) throw error;
+    if (!error.code?.startsWith('ENTROROVE_')) throw error;
     return { schemaVersion: 'entrorove.scope-connection/1.0', status: 'blocked', flowId: input?.flowId,
-      code: error.code, message: error.message, ...(error.output ? { output: error.output } : {}) };
+      ...prerequisiteFields(error),
+      code: error.code, message: error.message, ...(error.output ? { output: error.output } : {}),
+      ...recoveryFailureFields(error),
+      ...(error.outcomeUnknown ? { outcomeUnknown: true, nextAction: { method: 'GET', operation: 'scope-connect',
+        ...(error.requestId ? { requestId: error.requestId } : { uploadId: error.uploadId }), reuseOriginalInput: true, repeatPost: false } } : {}) };
   }
 }