@entrorove/skill 0.1.71 → 0.1.78

package/scope-runner-journal.mjs

@@ -0,0 +1,109 @@
+import path from 'node:path';
+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');
+  await atomicMutationJson14(location.file, state, { privateFrom: location.stateRoot, replace: true });
+}
+export async function scopeRunnerJournal(location, identity) {
+  let state;
+  try {
+    const item = await mutationFile14(location.file);
+    if (item.stat.size > 8_000_000 || item.stat.nlink !== 1) evidenceFail('Scope connection journal is invalid');
+    state = await readMutationJson14(location.file);
+    if (state.schemaVersion !== 'entrorove.scope-connection-journal/1.0' || canonical(state.identity) !== canonical(identity)) {
+      evidenceFail('Scope connection journal replaced its original task, repository or complete input');
+    }
+  } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  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() };
+    await saveScopeRunnerJournal(location, state);
+  }
+  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 };
+}

package/service-prerequisite.mjs

@@ -0,0 +1,87 @@
+import { canonical } from './local-integrity.mjs';
+import { consumeRecovery } from './local-recovery-budget.mjs';
+
+const fields = ['schemaVersion', 'error', 'code', 'version', 'requiredSetDigest', 'confirmationUrl',
+  'grantsExecutionAuthority', 'recoverable', 'preAdmission', 'knownBeforeEffects'];
+const bound = 4096;
+export function servicePrerequisite(response, value) {
+  if (response?.status !== 403 || !value || typeof value !== 'object' || Array.isArray(value)
+    || Object.keys(value).sort().join('\0') !== [...fields].sort().join('\0')
+    || value.schemaVersion !== 'entrorove.account-agreement-required/1.0'
+    || value.error !== 'account-agreement-required' || value.code !== 'ENTROROVE_ACCOUNT_AGREEMENT_REQUIRED'
+    || !/^\d{4}-\d{2}-\d{2}\.[1-9][0-9]{0,5}$/.test(value.version ?? '')
+    || !/^[a-f0-9]{64}$/.test(value.requiredSetDigest ?? '') || value.confirmationUrl !== '/?legal=confirm'
+    || value.grantsExecutionAuthority !== false || value.recoverable !== true
+    || typeof value.preAdmission !== 'boolean' || value.preAdmission !== value.knownBeforeEffects
+    || Buffer.byteLength(JSON.stringify(value)) > bound) return null;
+  return Object.fromEntries(fields.map(field => [field, value[field]]));
+}
+export function prerequisiteError(response, value, binding = {}) {
+  const prerequisite = servicePrerequisite(response, value);
+  if (!prerequisite) return null;
+  return Object.assign(new Error('The account must explicitly confirm the current service agreement on Entrorove before retrying the original request'),
+    { code: prerequisite.code, servicePrerequisite: prerequisite, ...binding,
+      knownBeforeEffects: binding.outcomeUnknown === true ? false : prerequisite.knownBeforeEffects,
+      grantsExecutionAuthority: false, recoverable: true });
+}
+export function prerequisiteFields(error) {
+  const value = servicePrerequisite({ status: 403 }, error?.servicePrerequisite);
+  return value ? { servicePrerequisite: value, grantsExecutionAuthority: false, recoverable: true,
+    interaction: { kind: 'confirm-account-agreement', confirmationUrl: value.confirmationUrl,
+      version: value.version, requiredSetDigest: value.requiredSetDigest },
+    ...(error.knownBeforeTransmission ? { knownBeforeTransmission: true } : {}),
+    ...(error.knownBeforeEffects ? { knownBeforeEffects: true } : {}) } : {};
+}
+export function discoveryPrerequisite(error, requestId) {
+  if (!servicePrerequisite({ status: 403 }, error?.servicePrerequisite)) return error;
+  Object.assign(error, { sourceRequestId: error.requestId, requestId, knownBeforeTransmission: true });
+  delete error.outcomeUnknown; return error;
+}
+export async function retainPrerequisite(error, state, location, save, field = 'pending') {
+  const pending = state[field], value = servicePrerequisite({ status: 403 }, error?.servicePrerequisite);
+  const identity = pending?.requestId ?? pending?.uploadId;
+  if (!pending || !value || !(error.knownBeforeTransmission || error.knownBeforeEffects)
+    || (error.requestId ?? error.uploadId) !== identity) return false;
+  const { servicePrerequisite: _previous, ...original } = pending;
+  const receipt = { originalId: identity, original: structuredClone(original), response: value, httpStatus: 403,
+    ...(error.sourceRequestId ? { sourceRequestId: error.sourceRequestId } : {}),
+    ...(error.knownBeforeTransmission ? { originalNotSent: true } : {}) };
+  pending.servicePrerequisite = receipt;
+  state.servicePrerequisiteHistory = [...(state.servicePrerequisiteHistory ?? []), receipt];
+  await save(location, state); return true;
+}
+export async function retryKnownPrerequisite(state, location, save, field = 'pending') {
+  const pending = state[field], receipt = pending?.servicePrerequisite;
+  if (!receipt) return false;
+  const value = servicePrerequisite({ status: receipt.httpStatus }, receipt.response);
+  const { servicePrerequisite: _receipt, ...original } = pending;
+  if (!value || receipt.originalId !== (pending.requestId ?? pending.uploadId)
+    || canonical(receipt.original) !== canonical(original)
+    || !(receipt.originalNotSent === true || value.preAdmission === true && value.knownBeforeEffects === true)) {
+    throw new Error('Original service prerequisite receipt is invalid; preserve its journal without retransmission');
+  }
+  // Persist a new unresolved attempt before sending. If that attempt loses its
+  // response, later calls must use GET even though an earlier attempt was denied.
+  consumeRecovery(state, 'prerequisite');
+  delete pending.servicePrerequisite; await save(location, state); return true;
+}
+export async function fetchPrerequisiteError(response, binding = {}) {
+  if (response.status !== 403 || !response.headers.get('content-type')?.startsWith('application/json')) return null;
+  const reader = response.body?.getReader(); if (!reader) return null;
+  const chunks = []; let size = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read(); if (done) break;
+      size += value.byteLength; if (size > bound) return null; chunks.push(Buffer.from(value));
+    }
+    return prerequisiteError(response, JSON.parse(Buffer.concat(chunks).toString('utf8')), binding);
+  } catch { return null; } finally { await reader.cancel().catch(() => {}); }
+}
+export function streamPrerequisiteError(value, binding = {}) {
+  if (!['ENTROROVE_ACCOUNT_AGREEMENT_REQUIRED', 'account-agreement-required'].includes(value?.code)
+    || value.recoverable !== true || value.grantsExecutionAuthority !== false) return null;
+  const prerequisite = servicePrerequisite({ status: 403 }, value.prerequisite);
+  if (!prerequisite || prerequisite.preAdmission || prerequisite.knownBeforeEffects) return null;
+  // This is a running stream notification, not a proof about prior effects.
+  return prerequisiteError({ status: 403 }, prerequisite, { ...binding, outcomeUnknown: true });
+}

package/task-entry-client.mjs

@@ -1,6 +1,7 @@
 import { requestTransport, parseTransportResponse, trustedOrigin } from './remote-transport.mjs';
 import { runCloudTask } from './cloud-task-client.mjs';
 import { displayIdeEvent, ideClientHeaders, ideTaskIdentity } from './ide-presentation.mjs';
+import { prerequisiteError } from './service-prerequisite.mjs';
 
 /** New IDE tasks use the authenticated account preference; resumes keep their original route. */
 export async function routeTaskEntry(data, token, dependencies) {
@@ -20,6 +21,8 @@ export async function routeTaskEntry(data, token, dependencies) {
     headers: { authorization: `Bearer ${token}`,...ideClientHeaders() },timeoutMs: 15000,
   });
   const preference = parseTransportResponse(response, 'cloud-sandbox preference');
+  const prerequisite = prerequisiteError(response, preference, { knownBeforeTransmission: true });
+  if (prerequisite) throw prerequisite;
   if (!response.ok || typeof preference?.enabled !== 'boolean') {
     throw new Error(`Cloud sandbox preference unavailable: HTTP ${response.status}. Task entry stopped.`);
   }

package/workflow-observation-client.mjs

@@ -1,3 +1,4 @@
+import { prerequisiteFields } from './service-prerequisite.mjs';
 import { bootstrapCloudMutationAuthority } from './cloud-mutation-authority.mjs';
 import { observationInput } from './workflow-observation-wire.mjs';
 
@@ -31,6 +32,7 @@ function blocked(error, input) {
     && Number.isSafeInteger(cause.rejection.generation) && cause.rejection.generation > 0
     && ['member-observation-admit', 'member-observation-report'].includes(cause.rejection.operation);
   return { schemaVersion: 'entrorove.local-observation-connection/1.0', status: 'blocked',
+    ...prerequisiteFields(cause),
     ...(safeId(input?.flowId) ? { flowId: input.flowId } : {}), independentValidation: 'pending', code,
     message: messages[code] ?? 'Local observation could not continue; its original command and result remain preserved',
     ...(recoverable ? { prerequisite: { status: 'blocked', code, recoverable: true, ...(reason ? { reason } : {}),

package/workflow-observation-remote.mjs

@@ -6,6 +6,7 @@ import { acknowledgeAutomaticFeedback, queryAutomaticFeedback, verifyAutomaticFe
 import { saveObservationState } from './workflow-observation-state.mjs';
 import { observationFail } from './workflow-observation-wire.mjs';
 import { readInvocations } from './local-invocations.mjs';
+import { prerequisiteError, retainPrerequisite, retryKnownPrerequisite } from './service-prerequisite.mjs';
 
 const unknown = requestId => Object.assign(new Error('Original local observation request outcome is unknown; recover its GET without repeating execution'),
   { code: 'ENTROROVE_LOCAL_OBSERVATION_UNKNOWN', outcomeUnknown: true, requestId });
@@ -25,12 +26,15 @@ async function recover(pending, dependencies) {
     response = await requestTransport(origin, `/api/skill/status/${pending.requestId}`, { headers: {
       authorization: `Bearer ${token}`, ...ideClientHeaders() } });
     result = parseTransportResponse(response, 'original local observation 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 && response.status >= 500
       || ['pending', 'running'].includes(result.output.status)) throw unknown(pending.requestId);
     result.feedback ??= await queryAutomaticFeedback(pending.requestId, dependencies);
     verifyAutomaticFeedback(result.feedback, pending.requestId, pending.requestId);
     result.feedback = await acknowledgeAutomaticFeedback(result.feedback, origin, token, ideClientHeaders());
-  } catch { throw unknown(pending.requestId); }
+  } catch (error) { throw Object.assign(unknown(pending.requestId),
+    error?.servicePrerequisite ? { servicePrerequisite: error.servicePrerequisite } : {}); }
   return { response, result };
 }
 function prerequisite(output) {
@@ -66,21 +70,25 @@ function terminalRejection(result, pending) {
 export async function observationRemote(stage, operation, input, state, location, dependencies) {
   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.operation !== operation || state.pending.requestId !== requestId
       || canonical(state.pending.input) !== canonical(input)) observationFail('Original observation request must finish before another operation');
+  }
+  if (existing && !await retryKnownPrerequisite(state, location, saveObservationState)) {
     ({ response, result } = await recover(state.pending, dependencies));
   } else {
-    state.pending = { stage, operation, input, requestId };
+    if (!existing) state.pending = { stage, operation, input, requestId };
     try { await saveObservationState(location, state); } catch { throw notSent(requestId); }
     try { ({ response, result } = await invokeRemoteResult({ operation, input }, dependencies)); }
-    catch {
+    catch (error) {
+      if (await retainPrerequisite(error, state, location, saveObservationState)) throw error;
       if (await knownNotSent(state.pending, dependencies.home)) {
         delete state.pending;
         try { await saveObservationState(location, state); } catch { throw notSent(requestId); }
         throw notSent(requestId);
       }
-      throw unknown(requestId);
+      throw Object.assign(unknown(requestId), error?.servicePrerequisite ? { servicePrerequisite: error.servicePrerequisite } : {});
     }
   }
   const statuses = ['reported', 'succeeded', ...(operation === 'member-observation-report' ? ['local-accepted'] : [])];