@entrorove/skill 0.1.73 → 0.1.78

package/scope-amendment-observer.mjs

@@ -21,12 +21,14 @@ async function inspectFiles(location, challenge) {
     physical.add(identity);
   }
 }
-export async function observeScopeAmendment(location, state) {
-  const challenge = scopeAmendmentChallenge(state.challenged.challenge, location);
+export async function observeScopeAmendment(location, state, { beforeSign } = {}) {
+  const original = scopeAmendmentChallenge(state.challenged.challenge, location, { allowExpired: beforeSign !== undefined });
+  let challenge = original;
   await inspectFiles(location, challenge);
   if (!state.snapshotId) { state.snapshotId = `scope-amend-${randomUUID()}`; await saveScopeAmendmentState(location, state); }
   const input = { repositoryRoot: location.root, home: location.home, flowId: challenge.flowId, stepId: challenge.stepId,
     snapshotId: state.snapshotId, paths: challenge.files.map(file => file.path).sort(),
+    scopeWritePaths: challenge.files.filter(file => file.access !== 'read-only').map(file => file.path).sort(),
     contractDigest: challenge.proposalDigest, importContexts: location.contextAuthority?.record.importContexts ?? location.binding.importContexts,
     ...(location.contextAuthority ? { contextRevisionDigest: location.contextAuthority.revisionDigest,
       contextEvidence: location.contextAuthority.record.evidence } : {}),
@@ -56,7 +58,11 @@ export async function observeScopeAmendment(location, state) {
   const observed = await attestScopeFacts({ ...input, ownerId: challenge.ownerId, taskDigest: challenge.taskDigest,
     chainDigest: challenge.chainDigest, repositoryId: challenge.repositoryId, challenge: challenge.challenge,
     signerConfigPath: location.signerConfigPath }, { repositoryRoot: location.root, facts,
-    snapshotDigest: facts.snapshotEvidence.snapshotDigest }, { maximumExpiresAt: Date.parse(challenge.expiresAt) });
+    snapshotDigest: facts.snapshotEvidence.snapshotDigest }, { maximumExpiresAt: Date.parse(challenge.expiresAt),
+    ...(beforeSign === undefined ? {} : { beforeSign: async () => {
+      challenge = await beforeSign();
+      return { challenge: challenge.challenge, maximumExpiresAt: Date.parse(challenge.expiresAt) };
+    } }) });
   const memberMutation = await scopeAmendmentMutation(location, state, challenge, facts);
   const core = { schemaVersion: 'entrorove.scope-revision-attestation/1.0', purpose: challenge.purpose,
     proposalId: challenge.proposalId, proposalDigest: challenge.proposalDigest, expectedRevision: challenge.expectedRevision,

package/scope-amendment-remote.mjs

@@ -7,6 +7,8 @@ import { readInvocations } from './local-invocations.mjs';
 import { saveScopeAmendmentState } from './scope-amendment-state.mjs';
 import { amendmentFail } from './scope-amendment-wire.mjs';
 import { retireMissingChallenge } from './scope-amendment-retirement.mjs';
+import { prerequisiteError, retainPrerequisite, retryKnownPrerequisite } from './service-prerequisite.mjs';
+import { consumeRecovery } from './local-recovery-budget.mjs';
 
 const unknown = requestId => Object.assign(new Error('Scope amendment outcome is unknown; recover the original request with GET only'),
   { code: 'ENTROROVE_SCOPE_AMENDMENT_UNKNOWN', outcomeUnknown: true, requestId });
@@ -16,6 +18,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 scope amendment status');
+    const prerequisite = prerequisiteError(response, result, { requestId: pending.requestId });
+    if (prerequisite) throw Object.assign(unknown(pending.requestId), { servicePrerequisite: prerequisite.servicePrerequisite });
     if (response.status === 404 && result?.error === 'request-not-found') {
       throw Object.assign(unknown(pending.requestId), { requestNotFound: true });
     }
@@ -25,7 +29,8 @@ async function recover(pending, dependencies) {
     verifyAutomaticFeedback(result.feedback, pending.requestId, pending.requestId);
     result.feedback = await acknowledgeAutomaticFeedback(result.feedback, origin, token, ideClientHeaders());
     return { response, result };
-  } catch (error) { throw error?.requestNotFound ? error : unknown(pending.requestId); }
+  } catch (error) { throw error?.requestNotFound ? error : Object.assign(unknown(pending.requestId),
+    error?.servicePrerequisite ? { servicePrerequisite: error.servicePrerequisite } : {}); }
 }
 async function notSent(pending, home) {
   try {
@@ -36,10 +41,14 @@ async function notSent(pending, home) {
 export async function amendmentRemote(stage, operation, payload, state, location, dependencies) {
   const input = { flowId: location.identity.flowId, operation, payload }, requestId = buildInvocation('continue', input).requestId;
   let response, result;
-  if (state.pending) {
+  const existing = Boolean(state.pending);
+  if (existing) {
     if (state.pending.stage !== stage || state.pending.requestId !== requestId || canonical(state.pending.input) !== canonical(input)) {
       amendmentFail('Recover the original amendment request before another operation');
     }
+  }
+  if (existing && !await retryKnownPrerequisite(state, location, saveScopeAmendmentState)) {
+    consumeRecovery(state, 'status'); await saveScopeAmendmentState(location, state);
     if (state.challengeRetirement) await retireMissingChallenge(state, location, dependencies, recover, notSent);
     try { ({ response, result } = await recover(state.pending, dependencies)); }
     catch (error) {
@@ -48,16 +57,18 @@ export async function amendmentRemote(stage, operation, payload, state, location
       ({ response, result } = await recover(state.pending, dependencies));
     }
   } else {
-    state.pending = { stage, operation: 'continue', input, requestId };
-    await saveScopeAmendmentState(location, state);
+    if (!existing) { state.pending = { stage, operation: 'continue', input, requestId };
+      await saveScopeAmendmentState(location, state); }
     try { ({ response, result } = await invokeRemoteResult({ operation: 'continue', input }, dependencies)); }
     catch (error) {
+      if (await retainPrerequisite(error, state, location, saveScopeAmendmentState)) throw error;
       if (await notSent(state.pending, dependencies.home)) {
+        state.rejection = { code: 'ENTROROVE_SCOPE_AMENDMENT_NOT_SENT', effects: 'none', requestId };
         delete state.pending; await saveScopeAmendmentState(location, state);
         throw Object.assign(new Error('Scope amendment was not transmitted; repair its prerequisite and reuse the original input'),
           { code: 'ENTROROVE_SCOPE_AMENDMENT_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);
@@ -80,5 +91,8 @@ export async function scopeAmendmentStatus(flowId, dependencies) {
       input: { flowId, operation: 'workflow-scope-status', payload: {} } }, dependencies);
     if (!response.ok || result?.output?.status !== 'succeeded') throw new Error();
     return result.output.result ?? result.output;
-  } catch { amendmentFail('Current account cannot read its original live scope revision; no amendment mutation was sent'); }
+  } catch (error) {
+    if (error?.servicePrerequisite) throw error;
+    amendmentFail('Current account cannot read its original live scope revision; no amendment mutation was sent');
+  }
 }

package/scope-amendment-retirement.mjs

@@ -2,6 +2,7 @@ import { canonical, sha256 } from './local-integrity.mjs';
 import { buildInvocation, invokeRemoteResult } from './remote-client.mjs';
 import { scopeRevisionAuthority, amendmentFail } from './scope-amendment-wire.mjs';
 import { saveScopeAmendmentState } from './scope-amendment-state.mjs';
+import { retainPrerequisite, retryKnownPrerequisite } from './service-prerequisite.mjs';
 
 export async function retireMissingChallenge(state, location, dependencies, recover, notSent) {
   const original = state.pending;
@@ -14,14 +15,15 @@ export async function retireMissingChallenge(state, location, dependencies, reco
   if (attempt && (attempt.requestId !== call.requestId || canonical(attempt.input) !== canonical(input))) {
     amendmentFail('Challenge retirement must retain its original preparation envelope');
   }
-  if (!attempt) {
-    attempt = state.challengeRetirement = { requestId: call.requestId, input, state: 'pending' };
+  if (!attempt || await retryKnownPrerequisite(state, location, saveScopeAmendmentState, 'challengeRetirement')) {
+    if (!attempt) attempt = state.challengeRetirement = { requestId: call.requestId, input, state: 'pending' };
     await saveScopeAmendmentState(location, state);
     try {
       const { result } = await invokeRemoteResult({ operation: 'scope-challenge-retire', input }, dependencies);
       attempt.output = result.output; attempt.feedback = result.feedback; attempt.state = 'completed';
       await saveScopeAmendmentState(location, state);
     } catch (error) {
+      if (await retainPrerequisite(error, state, location, saveScopeAmendmentState, 'challengeRetirement')) throw error;
       if (await notSent(attempt, dependencies.home)) {
         attempt.state = 'not-sent'; await saveScopeAmendmentState(location, state);
       }

package/scope-amendment-state.mjs

@@ -10,17 +10,21 @@ import { trustedOrigin } from './remote-transport.mjs';
 import { boundScopeContexts } from './scope-context-state.mjs';
 
 const fail = message => scopeFail('ENTROROVE_SCOPE_AMENDMENT_STATE', message);
-const maximumStateBytes = 1_000_000;
+const maximumControlBytes = 1_000_000;
+// Retained scope combines original facts and verified history, not a single
+// signing control. Keep its aggregate bound separate from key/config files.
+const maximumRetainedScopeBytes = 8_000_000;
 // A journal retains the challenge, S proof, original pending request and full
 // signed response together. Each signed authority retains its own 1 MB bound.
 const maximumJournalBytes = 8_000_000;
-async function privateItem(file, final = 'file', maximumBytes = maximumStateBytes) {
+async function privateItem(file, final = 'file', maximumBytes = maximumControlBytes) {
   const value = await mutationFile14(file, { final });
   if (process.getuid && value.stat.uid !== process.getuid()
     || process.platform !== 'win32' && value.stat.mode & 0o077
-    || final === 'file' && (value.stat.nlink !== 1 || value.stat.size > maximumBytes)) {
-    fail('Scope amendment controls must be bounded private files owned by the current OS account');
+    || final === 'file' && value.stat.nlink !== 1) {
+    fail('Scope amendment controls must be private single-link files owned by the current OS account');
   }
+  if (final === 'file' && value.stat.size > maximumBytes) fail(`Scope amendment file exceeds the ${maximumBytes} byte limit`);
   return value;
 }
 async function privateText(file) {
@@ -68,7 +72,7 @@ export async function scopeAmendmentLocation(repositoryRoot, input, dependencies
   if (key.asymmetricKeyType !== 'ed25519' || der.toString('base64') !== binding.publicKey
     || sha256(der) !== binding.keyId) fail('Original scope signing identity changed');
   const originalStatePath = path.join(stateRoot, 'scope', sha256(root).slice(0, 32), input.flowId, 'state.json');
-  await privateItem(originalStatePath);
+  await privateItem(originalStatePath, 'file', maximumRetainedScopeBytes);
   const saved = await readMutationJson14(originalStatePath);
   const original = await retainedScope({ repositoryRoot: root, home, flowId: input.flowId,
     stepId: saved.stepId, snapshotId: saved.originalSnapshot?.snapshotId }, root);

package/scope-context-client.mjs

@@ -1,3 +1,4 @@
+import { prerequisiteFields } from './service-prerequisite.mjs';
 import path from 'node:path';
 import { sign } from 'node:crypto';
 import { canonical } from './local-integrity.mjs';
@@ -9,6 +10,7 @@ import { scopeContextLocation, effectiveScopeContexts, retainContextAuthority,
 import { contextRemote } from './scope-context-remote.mjs';
 import { inspectContextEvidence, observeScopeContext, prepareScopeContext } from './scope-context-observer.mjs';
 import { contextJournal, renewContextChallenge } from './scope-context-journal.mjs';
+import { recoveryFailureFields } from './local-recovery-budget.mjs';
 import { saveLocalScopeEvidence, ensureScopeEvidence, validateAppliedEvidence } from './scope-evidence-remote.mjs';
 
 const schemaVersion = 'entrorove.scope-context-connection/1.0';
@@ -23,6 +25,9 @@ function proposalFor(status, input, location) {
 }
 function waiting(value, flowId) {
   const status = value.proposal?.approval?.status;
+  if (status === 'approved') return { ...value, schemaVersion, status: 'succeeded', flowId,
+    grantsExecutionAuthority: false, claimsCompletion: false, nextOperation: 'scope-context',
+    nextInput: { action: 'apply', flowId, proposalId: value.proposal.proposalId, proposalDigest: value.proposal.proposalDigest } };
   return { ...value, schemaVersion, status: status === 'declined' ? 'blocked' : 'needs-input', flowId,
     grantsExecutionAuthority: false, claimsCompletion: false,
     nextStep: value.nextStep ?? { operation: 'interaction-answer', requiresOriginalOwnerApproval: true,
@@ -118,9 +123,11 @@ export async function runScopeContext(repositoryRoot, input, dependencies) {
     return await withStateLock(path.join(location.base, 'connection'), () => run(location, input, dependencies));
   } catch (error) {
     return { schemaVersion, status: 'blocked', flowId: input?.flowId,
+      ...prerequisiteFields(error),
       code: error?.code?.startsWith('ENTROROVE_') ? error.code : 'ENTROROVE_SCOPE_CONTEXT_PREREQUISITE',
       message: error?.code?.startsWith('ENTROROVE_') ? error.message : 'Context recovery stopped; preserve original signer, binding, journal and evidence.',
       ...(error?.requestId ? { requestId: error.requestId } : {}), ...(error?.uploadId ? { uploadId: error.uploadId } : {}), ...(error?.output ? { output: error.output } : {}),
+      ...recoveryFailureFields(error),
       ...(error?.outcomeUnknown ? { outcomeUnknown: true, nextAction: { operation: 'scope-context', method: 'GET',
         ...(error.requestId ? { requestId: error.requestId } : { uploadId: error.uploadId }), reuseOriginalInput: true, repeatPost: false } } : {}) };
   }

package/scope-context-journal.mjs

@@ -5,6 +5,7 @@ import { atomicMutationJson14, readMutationJson14 } from './local-mutation-files
 import { contextFail } from './scope-context-wire.mjs';
 import { readContextJournal, saveContextJournal } from './scope-context-state.mjs';
 import { contextRemote } from './scope-context-remote.mjs';
+import { consumeRecovery } from './local-recovery-budget.mjs';
 
 export async function archiveContextAttempt(location, state) {
   if (!state.attemptId) return;
@@ -20,22 +21,27 @@ export async function contextJournal(location, input) {
   let state = await readContextJournal(location, input);
   if (!state.previous && reusableSnapshot(state, input)) {
     await archiveContextAttempt(location, state);
+    consumeRecovery(state, 'attempt', state.signingAttemptId ?? state.attemptId);
     for (const field of ['rejection', 'checked', 'attestation', 'signingChallenge', 'signingAttemptId',
       'evidenceDescriptor', 'evidenceSignature', 'evidencePrepared', 'attestationRef', 'evidenceResult']) delete state[field];
     await saveContextJournal(location, state);
   } else if (state.previous || !state.pending && !state.evidencePending && !state.applied && (state.rejection
     || input.action === 'status' && state.completed || input.action === 'apply' && state.completed)) {
-    await archiveContextAttempt(location, state.previous ?? state); state = {};
+    const previous = state.previous ?? state;
+    await archiveContextAttempt(location, previous);
+    const recovery = previous.completed ? undefined : consumeRecovery(previous, 'attempt', previous.attemptId);
+    state = { ...(recovery ? { recovery } : {}) };
   }
   if (!state.attemptId) {
     state = { schemaVersion: 'entrorove.scope-context-journal/1.0', localBindingDigest: location.localBindingDigest,
-      input, attemptId: randomUUID() }; await saveContextJournal(location, state);
+      input, attemptId: randomUUID(), ...(state.recovery ? { recovery: state.recovery } : {}) }; await saveContextJournal(location, state);
   }
   return state;
 }
 export async function renewContextChallenge(location, state, proposal, dependencies) {
   if (state.pending || state.evidencePending) contextFail('Recover the original pending request before any challenge renewal');
   await archiveContextAttempt(location, state);
+  consumeRecovery(state, 'signing', state.signingAttemptId ?? state.attemptId);
   delete state.signingChallenge;
   state.signingAttemptId = randomUUID(); await saveContextJournal(location, state);
   const output = await contextRemote('signingChallenge', 'scope-runner-context-challenge', { flowId: location.binding.flowId,

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 {
@@ -32,20 +37,26 @@ async function notSent(pending, home) {
 }
 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 save(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 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);

package/scope-evidence-remote.mjs

@@ -4,6 +4,7 @@ import { readScopeEvidence, retainScopeEvidence } from './scope-evidence-local.m
 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 });
@@ -24,10 +25,15 @@ function resultReference(value, upload, 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) {
+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;
@@ -51,22 +57,25 @@ export async function ensureScopeEvidence(state, location, dependencies, challen
   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();
-  if (state.evidencePending) {
+  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);
   }
-  state.evidencePending = { uploadId: upload.uploadId, sha256: descriptor.sha256, canonicalBytes: descriptor.canonicalBytes };
-  await save(location, state);
-  let response;
+  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 (Date.parse(upload.expiresAt) <= Date.now()) response = await requestTransport(origin, `/api/skill/evidence/${upload.uploadId}`, { headers });
+    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);
+  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,

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,10 +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 { recoveryFailureFields } from './local-recovery-budget.mjs';
 import { contextRemote } from './scope-context-remote.mjs';
-import { scopeRunnerJournal, saveScopeRunnerJournal } from './scope-runner-journal.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 });
@@ -68,8 +71,26 @@ async function scopeConnectionResult(identity, binding, accepted) {
     runnerId: binding.runnerId, scopeEvidence: accepted.scopeEvidence, grantsExecutionAuthority: false,
     nextOperation: next.operation, ...(resumeOriginalRequest ? { resumeOriginalRequest: true } : { nextInput }), nextStep: next };
 }
-async function observeConnection(identity, location, state, challenge, contextAuthority, dependencies) {
-  if (state.evidenceDescriptor) return;
+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 } : {}) };
@@ -78,13 +99,17 @@ async function observeConnection(identity, location, state, challenge, contextAu
     try { await snapshotPlan(input); }
     catch (error) { delete state.snapshotStarted; await saveScopeRunnerJournal(location, state); throw error; }
   }
-  const verified = await snapshotVerify(input);
+  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 },
-  { maximumExpiresAt: Date.parse(challenge.expiresAt) });
+  { 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;
@@ -112,8 +137,8 @@ async function connect(identity, directory, dependencies) {
     }
     if (!state.snapshotId) { state.snapshotId = `snapshot-${randomUUID()}`; await saveScopeRunnerJournal(location, state); }
     if (!state.accepted) {
-      await observeConnection(identity, location, state, challenge, contextAuthority, dependencies);
-      const attestationRef = await ensureScopeEvidence(state, location, dependencies, challenge, saveScopeRunnerJournal);
+      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);
@@ -159,7 +184,9 @@ export async function runScopeConnect(repositoryRoot, input, dependencies) {
   catch (error) {
     if (!error.code?.startsWith('ENTROROVE_')) throw error;
     return { schemaVersion: 'entrorove.scope-connection/1.0', status: 'blocked', flowId: input?.flowId,
+      ...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 } } : {}) };
   }

package/scope-runner-journal.mjs

@@ -3,6 +3,8 @@ import { randomUUID } from 'node:crypto';
 import { canonical, sha256 } from './local-integrity.mjs';
 import { readMutationJson14, atomicMutationJson14, mutationFile14 } from './local-mutation-files.mjs';
 import { evidenceFail } from './scope-evidence-wire.mjs';
+import { scopeFail } from './local-scope-files.mjs';
+import { consumeRecovery } from './local-recovery-budget.mjs';
 
 export async function saveScopeRunnerJournal(location, state) {
   if (Buffer.byteLength(canonical(state)) + 1 > 8_000_000) evidenceFail('Scope connection journal exceeds its unchanged bounded control limit');
@@ -18,11 +20,19 @@ export async function scopeRunnerJournal(location, identity) {
       evidenceFail('Scope connection journal replaced its original task, repository or complete input');
     }
   } catch (error) { if (error.code !== 'ENOENT') throw error; }
-  if (state && !state.pending && !state.evidencePending && (state.completed || state.rejection)) {
-    const archive = path.join(location.directory, `${state.attemptId}-${sha256(canonical(state))}.json`);
-    try { if (canonical(await readMutationJson14(archive)) !== canonical(state)) evidenceFail('Scope connection history changed'); }
-    catch (error) { if (error.code !== 'ENOENT') throw error; await atomicMutationJson14(archive, state, { privateFrom: location.stateRoot }); }
-    state = undefined;
+  if (state && reusableExpiredScopeSnapshot(state, identity)) {
+    const archivedDigest = await archiveScopeRunnerAttempt(location, state);
+    consumeRecovery(state, 'attempt', state.attemptId);
+    state.signingRecovery = { reason: 'known-local-signature-expiry', archivedDigest, snapshotId: state.snapshotId,
+      requiresSnapshotVerification: true, grantsExecutionAuthority: false, recoveredAt: new Date().toISOString() };
+    delete state.rejection;
+    await saveScopeRunnerJournal(location, state);
+  } else if (state && !state.pending && !state.evidencePending && (state.completed || state.rejection)) {
+    await archiveScopeRunnerAttempt(location, state);
+    const recovery = state.completed ? undefined : consumeRecovery(state, 'attempt', state.attemptId);
+    state = { schemaVersion: 'entrorove.scope-connection-journal/1.0', identity, attemptId: randomUUID(),
+      ...(recovery ? { recovery } : {}) };
+    await saveScopeRunnerJournal(location, state);
   }
   if (!state) {
     state = { schemaVersion: 'entrorove.scope-connection-journal/1.0', identity, attemptId: randomUUID() };
@@ -30,3 +40,70 @@ export async function scopeRunnerJournal(location, identity) {
   }
   return state;
 }
+
+export async function archiveScopeRunnerAttempt(location, state) {
+  const checksum = sha256(canonical(state));
+  const archive = path.join(location.directory, `${state.attemptId}-${checksum}.json`);
+  try { if (canonical(await readMutationJson14(archive)) !== canonical(state)) evidenceFail('Scope connection history changed'); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; await atomicMutationJson14(archive, state, { privateFrom: location.stateRoot }); }
+  return checksum;
+}
+export function validateScopeRunnerChallenge(value, original, identity, binding, { allowExpired = false } = {}) {
+  const immutable = challenge => Object.fromEntries(Object.entries(challenge ?? {}).filter(([field]) => !['challenge', 'expiresAt'].includes(field)));
+  const id = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/, hash = /^[a-f0-9]{64}$/;
+  if (!value || !original || canonical(immutable(value)) !== canonical(immutable(original))
+    || value.flowId !== identity.flowId || value.runnerId !== binding.runnerId || value.receiverId !== binding.runnerId
+    || value.repositoryId !== binding.repositoryId || canonical(value.targetPaths) !== canonical(identity.targetPaths)
+    || ['stepId', 'ownerId', 'challenge'].some(field => !id.test(value[field] ?? ''))
+    || ['taskDigest', 'chainDigest'].some(field => !hash.test(value[field] ?? ''))
+    || !Number.isSafeInteger(value.expectedRevision) || value.expectedRevision < 0
+    || !value.task || typeof value.task !== 'object' || Array.isArray(value.task)) {
+    scopeFail('ENTROROVE_SCOPE_BINDING', 'Fresh scope challenge replaced its original task, signer, step, paths or revision');
+  }
+  const expiresAt = Date.parse(value.expiresAt);
+  if (!Number.isFinite(expiresAt) || !allowExpired && (expiresAt <= Date.now() || expiresAt > Date.now() + 90_000)) {
+    scopeFail('ENTROROVE_SCOPE_ATTESTATION_BINDING', 'Actual scope signature requires its current bounded original challenge');
+  }
+  return value;
+}
+function noScopeSubmission(state) {
+  return !['pending', 'evidencePending', 'evidenceDescriptor', 'evidencePrepared', 'evidenceSignature',
+    'attestation', 'attestationRef', 'evidenceResult', 'accepted'].some(field => Object.hasOwn(state, field));
+}
+function reusableExpiredScopeSnapshot(state, identity) {
+  if (!noScopeSubmission(state) || state.completed || state.snapshotStarted !== true
+    || typeof state.snapshotId !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(state.snapshotId)
+    || state.rejection?.code !== 'ENTROROVE_SCOPE_ATTESTATION_BINDING'
+    || state.rejection.message !== 'candidate challenge expired before its actual scope signature'
+    || state.rejection.requestId || state.rejection.output || state.registered?.registered !== true) return false;
+  const enrollment = state.prepared?.enrollment, original = state.challenged?.challenge;
+  if (!enrollment || !original || enrollment.flowId !== identity.flowId || state.registered.runnerId !== enrollment.runnerId
+    || state.registered.repositoryId !== enrollment.repositoryId
+    || canonical(state.registered.targetPaths) !== canonical(identity.targetPaths)
+    || ['ownerId', 'taskDigest', 'chainDigest', 'runnerId', 'repositoryId'].some(field => enrollment[field] !== original[field])
+    || canonical(enrollment.targetPaths) !== canonical(identity.targetPaths)) return false;
+  try { validateScopeRunnerChallenge((state.signingChallenge ?? state.challenged).challenge, original, identity, enrollment, { allowExpired: true }); }
+  catch { return false; }
+  return Date.parse((state.signingChallenge ?? state.challenged).challenge.expiresAt) <= Date.now();
+}
+export async function renewScopeRunnerChallenge(identity, location, state, original, remote) {
+  if (!['evidencePending', 'evidenceDescriptor', 'evidencePrepared', 'attestationRef', 'attestation', 'accepted']
+    .every(field => !Object.hasOwn(state, field)) || canonical(state.identity) !== canonical(identity)) {
+    scopeFail('ENTROROVE_SCOPE_BINDING', 'Recover the original signed evidence before another scope signing challenge');
+  }
+  if (state.pending && (state.pending.stage !== 'signingChallenge' || !state.signingAttemptId)) {
+    scopeFail('ENTROROVE_SCOPE_BINDING', 'Recover only the original pending request before challenge renewal');
+  }
+  if (!state.pending && state.signingChallenge && Date.parse(state.signingChallenge.challenge?.expiresAt) > Date.now()) {
+    return validateScopeRunnerChallenge(state.signingChallenge.challenge, original, identity, location.binding);
+  }
+  if (!state.pending && (!state.signingAttemptId || state.signingChallenge)) {
+    await archiveScopeRunnerAttempt(location, state);
+    consumeRecovery(state, 'signing', state.signingAttemptId ?? state.attemptId);
+    delete state.signingChallenge; state.signingAttemptId = randomUUID();
+    await saveScopeRunnerJournal(location, state);
+  }
+  const issued = await remote('signingChallenge', 'scope-runner-challenge', { flowId: identity.flowId,
+    receiverId: location.binding.runnerId, attemptId: state.signingAttemptId });
+  return validateScopeRunnerChallenge(issued.challenge, original, identity, location.binding);
+}

package/scope-write-observation.d.mts

@@ -0,0 +1,4 @@
+type File = { path: string; bytes: number; lines: number }
+export function projectScopeWriteFacts<T extends { files: File[]; recentChangedLines: number }>(
+  facts: T, signedFacts: Record<string, any>, roles: Array<{ path: string; access: 'write' | 'read-only' | 'create' }>
+): T

package/scope-write-observation.mjs

@@ -0,0 +1,43 @@
+const version = 'entrorove.scope-write-observation/1.0';
+const fields = ['schemaVersion', 'paths', 'fileCount', 'bytes', 'sourceLines', 'tokenEstimate', 'git', 'estimatedChangedLines'];
+function fail() {
+  throw Object.assign(new Error('Write observations require the exact approved roles and independently signed source counts'),
+    { code: 'ENTROROVE_SCOPE_WRITE_OBSERVATION' });
+}
+const same = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+export function scopeWriteFiles(files, requested) {
+  if (!Array.isArray(requested) || !requested.length || requested.length > files.length
+    || requested.some(value => typeof value !== 'string') || new Set(requested).size !== requested.length) fail();
+  const selected = files.filter(file => requested.includes(file.path));
+  if (selected.length !== requested.length) fail();
+  return selected;
+}
+export function scopeEstimatedChanges(files, observation, knownFiles) {
+  const git = observation.facts;
+  return git.available && git.head ? observation.currentDiffPresent ? git.currentChangedLines : git.recentChangedLines
+    : files.reduce((total, file) => total + file.lines + (file.exists === false
+      ? knownFiles.find(previous => previous.path === file.path)?.lines ?? 0 : 0), 0);
+}
+export function scopeWriteObservation(files, observation, knownFiles) {
+  const bytes = files.reduce((total, file) => total + file.bytes, 0);
+  return { schemaVersion: version, paths: files.map(file => file.path).sort(), fileCount: files.length, bytes,
+    sourceLines: files.reduce((total, file) => total + file.lines, 0), tokenEstimate: Math.ceil(bytes / 4),
+    git: observation.facts, estimatedChangedLines: scopeEstimatedChanges(files, observation, knownFiles) };
+}
+// Only call after verifying the original S receipt and its exact approved role set.
+// Older signed receipts retain their conservative full-scope change estimate.
+export function projectScopeWriteFacts(facts, signedFacts, roles) {
+  const files = scopeWriteFiles(facts.files, roles.filter(file => file.access !== 'read-only').map(file => file.path));
+  const observed = signedFacts.writeScope;
+  if (observed === undefined) return { ...facts, files };
+  if (!observed || typeof observed !== 'object' || !same(Object.keys(observed).sort(), [...fields].sort())
+    || observed.schemaVersion !== version || !same(observed.paths, files.map(file => file.path).sort())
+    || !['fileCount', 'bytes', 'sourceLines', 'tokenEstimate', 'estimatedChangedLines']
+      .every(field => Number.isSafeInteger(observed[field]) && observed[field] >= 0)
+    || observed.fileCount !== files.length || observed.bytes !== files.reduce((sum, file) => sum + file.bytes, 0)
+    || observed.sourceLines !== files.reduce((sum, file) => sum + file.lines, 0)
+    || observed.tokenEstimate !== Math.ceil(observed.bytes / 4)
+    || !observed.git || !signedFacts.git
+    || ['available', 'head', 'baseline'].some(field => observed.git[field] !== signedFacts.git[field])) fail();
+  return { ...facts, files, recentChangedLines: observed.estimatedChangedLines };
+}