@awak-app/simy-cli 0.5.72 → 0.5.73

package/src/sqm/command.js

@@ -11,8 +11,9 @@ import { uploadRunEvidence } from "./evidence-client.js";
 import { evaluateKnowledgeBundle } from "./checkers.js";
 import { runSqmCheck, runSqmMinCheck } from "./index.js";
 import { lintKnowledgeModule, summarizeReplay } from "./reliability.js";
-import { ensureSqmSession } from "./session.js";
+import { ensureSqmSession, sqmSessionScope } from "./session.js";
 import { formatSqmCoverage } from "./report.js";
+import { sqmDiagnostic } from "./request-recovery.js";
 
 export async function runSqmCommand(argv, { cliVersion }) {
   if (argv.includes("--help") || argv.includes("-h") || !argv.length) {
@@ -24,14 +25,17 @@ export async function runSqmCommand(argv, { cliVersion }) {
   if (argv[0] === "replay") return await runReplayCommand(argv);
   if (!["min-check", "check"].includes(argv[0])) throw new Error("Usage: simy sqm <min-check|check|lint|replay> [options]");
   const webOrigin = resolveWebOrigin(option(argv, "--host"));
+  const authorizationLogger = argv.includes("--json")
+    ? { log: message => console.warn(message), error: message => console.error(message) }
+    : console;
   let session = await readSession(webOrigin);
   let validSession = isSessionValid(session, Date.now(), webOrigin) ? session : null;
   if (!validSession && !explicitSqmEnvironment(argv)) {
-    session = await ensureSqmSession(webOrigin, { noOpen: argv.includes("--no-open") });
+    session = await ensureSqmSession(webOrigin, { noOpen: argv.includes("--no-open"), logger: authorizationLogger });
     validSession = session;
   }
   const organizationId = process.env.SIMY_SQM_ORGANIZATION_ID || validSession?.organization_id || validSession?.org_id;
-  const token = process.env.SIMY_SQM_TOKEN || process.env.SIMY_ACCESS_TOKEN || validSession?.token;
+  let token = process.env.SIMY_SQM_TOKEN || process.env.SIMY_ACCESS_TOKEN || validSession?.token;
   const accountId = process.env.SIMY_SQM_ACCOUNT_ID || validSession?.account_id || validSession?.auth_user_id || validSession?.device_id;
   const deviceId = process.env.SIMY_SQM_DEVICE_ID || validSession?.device_id;
   if (!organizationId) throw new Error(`SQM needs an organization-bound SIMY session. Run \`simy --host ${webOrigin}\` once, then retry.`);
@@ -46,10 +50,32 @@ export async function runSqmCommand(argv, { cliVersion }) {
     endpoint,
     accountId,
     organizationId,
+    deviceId,
   };
 
   const save = createSqmCheckRecorder({ scope: { webOrigin, accountId, organizationId },
     phase: argv[0] === "min-check" ? "min" : "full", cwd: common.cwd, baseBranch: common.baseBranch });
+  const onRecoveryEvent = async diagnostic => createSqmCheckRecorder({ scope: { webOrigin, accountId, organizationId },
+    phase: argv[0] === "min-check" ? "min" : "full", cwd: common.cwd, baseBranch: common.baseBranch })({ status: "failed", diagnostic });
+  common.bundleDependencies = { onRecoveryEvent };
+  common.onRecoveryEvent = onRecoveryEvent;
+  let authenticationAttempted = false;
+  if (validSession && !process.env.SIMY_SQM_TOKEN && !process.env.SIMY_ACCESS_TOKEN) {
+    const expectedScope = sqmSessionScope(validSession, webOrigin);
+    common.onAuthenticationRequired = async ({ rejectedToken }) => {
+      if (authenticationAttempted) {
+        const error = new Error("SQM authorization was already refreshed once; resolve the sign-in error before another check.");
+        error.code = "authorization_refresh_failed"; throw error;
+      }
+      authenticationAttempted = true;
+      validSession = await ensureSqmSession(webOrigin, { noOpen: argv.includes("--no-open"), rejectedToken, expectedScope, logger: authorizationLogger });
+      token = validSession.token;
+      common.token = token;
+      return { token, accountId: validSession.account_id || validSession.auth_user_id || validSession.device_id,
+        organizationId: validSession.organization_id || validSession.org_id, deviceId: validSession.device_id,
+        endpoint: process.env.SIMY_SQM_BUNDLE_URL || new URL("sqm/knowledge-bundle", validSession.api_base_url).href };
+    };
+  }
   let stage = "min_check";
   try {
     if (argv[0] === "min-check") {
@@ -77,6 +103,12 @@ export async function runSqmCommand(argv, { cliVersion }) {
     stage = "full_check";
     const result = await runSqmCheck({ ...common, minCheck, deviceId, signingKeyPath: option(argv, "--signing-key") || undefined });
     if (result.status === "unavailable") { await save(result); return printUnavailable(result, argv); }
+    if (result.recovery?.code === "knowledge_bundle_changed") {
+      // Keep the earlier min as history; never rewrite it into an apparent
+      // success for the new bundle.
+      await atomicJson(`${minPath}.previous.${minCheck.result_digest.slice(-16)}.json`, minCheck);
+      await atomicJson(minPath, result.min_check);
+    }
     const proofPath = path.resolve(option(argv, "--proof") || "proof.json");
     const evidencePath = path.resolve(option(argv, "--signed-evidence") || `${proofPath}.signed.json`);
     const diagnosticsPath = path.resolve(option(argv, "--diagnostics") || `${proofPath}.diagnostics.json`);
@@ -107,7 +139,7 @@ export async function runSqmCommand(argv, { cliVersion }) {
     else printFull(result);
     return result.proof.outcome.status === "failed" ? 1 : 0;
   } catch (error) {
-    await save({ status: "failed", diagnostic: safeSqmDiagnostic(error, stage) });
+    await save({ status: "failed", diagnostic: { ...safeSqmDiagnostic(error, stage), ...sqmDiagnostic(error, stage) } });
     throw error;
   }
 }

package/src/sqm/diagnostics.js

@@ -3,7 +3,7 @@
 export function safeSqmDiagnostic(error, stage = "check", code = "sqm_check_failed") {
   const value = error?.diagnostic || (error?.error && typeof error.error === "object" ? error.error : error) || {};
   const machine = (candidate, fallback) => typeof candidate === "string" && /^[a-zA-Z][a-zA-Z0-9_]{0,79}$/.test(candidate) ? candidate : fallback;
-  const status = [value.status, value.errorStatus, value.httpStatus, value.error_status].find(candidate => Number.isInteger(candidate) && candidate >= 400 && candidate <= 599);
+  const status = [value.status, value.http_status, value.errorStatus, value.httpStatus, value.error_status].find(candidate => Number.isInteger(candidate) && candidate >= 400 && candidate <= 599);
   const requestId = value.requestId ?? value.request_id;
   return {
     stage: machine(value.stage ?? value.errorStage ?? value.error_stage, stage),

package/src/sqm/evidence-client.js

@@ -1,13 +1,29 @@
 import { safeSqmDiagnostic } from "./diagnostics.js";
 export async function uploadRunEvidence({ endpoint, token, proof, signedEvidence, fetchImpl = globalThis.fetch }) {
   if (!endpoint || !token) return { uploaded: false, reason: "authenticated_cloud_session_unavailable" };
-  const response = await fetchImpl(endpoint, {
-    method: "POST",
-    headers: { accept: "application/json", authorization: `Bearer ${token}`, "content-type": "application/json" },
-    body: JSON.stringify({ proof, signed_evidence: signedEvidence }),
-    signal: AbortSignal.timeout(10_000),
-  });
+  let response;
+  try {
+    response = await fetchImpl(endpoint, {
+      method: "POST",
+      headers: { accept: "application/json", authorization: `Bearer ${token}`, "content-type": "application/json" },
+      body: JSON.stringify({ proof, signed_evidence: signedEvidence }),
+      signal: AbortSignal.timeout(10_000),
+    });
+  } catch (cause) {
+    const error = cause instanceof Error ? cause : new Error("SQM run evidence upload failed.");
+    error.stage = "evidence_upload";
+    error.retryable = false;
+    throw error;
+  }
   const payload = await response.json().catch(() => null);
-  if (!response.ok) throw Object.assign(new Error(`SQM run evidence upload failed with HTTP ${response.status}${payload?.error ? `: ${typeof payload.error === "string" ? payload.error : payload.error.message || "unknown error"}` : ""}.`), safeSqmDiagnostic({ status: response.status, code: payload?.error?.code, requestId: response.headers?.get?.("x-request-id") }, "evidence_upload", "evidence_upload_failed"));
+  if (!response.ok) {
+    const error = new Error(`SQM run evidence upload failed with HTTP ${response.status}${payload?.error ? `: ${typeof payload.error === "string" ? payload.error : payload.error.message || "unknown error"}` : ""}.`);
+    error.status = response.status;
+    error.stage = "evidence_upload";
+    error.retryable = false;
+    Object.assign(error, safeSqmDiagnostic({ status: response.status, code: payload?.error?.code,
+      requestId: response.headers?.get?.("x-request-id") }, "evidence_upload", "evidence_upload_failed"));
+    throw error;
+  }
   return { uploaded: true, ...payload };
 }

package/src/sqm/history-store.js

@@ -1,3 +1,4 @@
+import { diagnosticLogger } from "../diagnostic-log.js";
 import { safeSqmDiagnostic, formatSqmDiagnostic } from "./diagnostics.js";
 import { createHash, randomUUID } from "node:crypto";
 import { mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
@@ -45,6 +46,8 @@ export function createSqmHistoryStore({ root = defaultSessionRoot(), now = () =>
       try {
         await writeFile(temp, JSON.stringify(item), { mode: 0o600 });
         await rename(temp, target);
+        if (["failed", "unavailable"].includes(item.state)) await diagnosticLogger({ root, scope }).record({
+          kind: item.kind, stage: entry.errorStage || item.phase || "unknown", code: item.errorCode, provider: item.provider, http_status: entry.httpStatus, at: item.finishedAt || item.startedAt });
       } finally { await rm(temp, { force: true }); cache.delete(dir); }
       const items = await list(scope);
       for (const kind of ["analysis", "check"]) {
@@ -74,6 +77,7 @@ function metadata(entry) {
     if (typeof entry[name] === "string") item[name] = entry[name].slice(0, ["instruction", "result", "error"].includes(name) ? 4096 : 512);
   }
   if (Number.isInteger(entry.errorStatus) && entry.errorStatus >= 400 && entry.errorStatus <= 599) item.errorStatus = entry.errorStatus;
+  if (Number.isInteger(entry.httpStatus) && entry.httpStatus >= 400 && entry.httpStatus <= 599) item.httpStatus = entry.httpStatus;
   return item;
 }
 

package/src/sqm/index.js

@@ -6,6 +6,8 @@ import { loadKnowledgeBundle } from "./bundle-store.js";
 import { uploadRunEvidence } from "./evidence-client.js";
 import { buildProof, finalizeMinCheck, repositoryIdentity, sameRepositoryIdentity, signProof, verifyMinCheck, verifySignedEvidence } from "./proof.js";
 import { inspectRepository } from "./repository.js";
+import { sqmDiagnostic } from "./request-recovery.js";
+import { canonicalize } from "./canonical.js";
 
 export function createSqmChecker({
   cwd = process.cwd(),
@@ -21,6 +23,7 @@ export function createSqmChecker({
   webOrigin,
   historyRoot,
   evidenceEndpoint,
+  signingKeyPath,
   uploadRunEvidenceImpl = uploadRunEvidence,
   inspectRepositoryImpl = inspectRepository,
   loadKnowledgeBundleImpl = loadKnowledgeBundle,
@@ -31,34 +34,59 @@ export function createSqmChecker({
   let pinnedLoad = null;
   let pinnedRepository = null;
   let latestMinCheck = null;
+  let pinnedSystemScope;
+  const onRecoveryEvent = async (diagnostic) => {
+    await createSqmCheckRecorder({ root: historyRoot,
+      scope: historyRoot ? { webOrigin, accountId, organizationId } : null,
+      phase: diagnostic.stage === "evidence_upload" ? "full" : "min", cwd, baseBranch })({ status: "failed", diagnostic });
+    await dependencies.onRecoveryEvent?.(diagnostic);
+  };
 
   const checkCurrentRepository = async function(_attempt = null, { phase = "min" } = {}) {
     let repository;
     try {
       repository = await inspectRepositoryImpl(cwd, { baseBranch, runCommand: dependencies.runCommand });
     } catch (error) {
-      return { ...unavailable(`SQM repository inspection failed: ${message(error)}`), diagnostic: safeSqmDiagnostic(error, "repository", "repository_inspection_failed") };
+      return { ...unavailable(`SQM repository inspection failed: ${message(error)}`), diagnostic: { ...safeSqmDiagnostic(error, "repository", "repository_inspection_failed"), ...sqmDiagnostic(error, "repository") } };
     }
     if (pinnedRepository && pinnedRepository !== repository.repository) return unavailable(`SQM repository changed during a pinned run (${pinnedRepository} to ${repository.repository}).`, repository.repository);
     if (!pinnedLoad) {
       pinnedRepository = repository.repository;
-      pinnedLoad = loadKnowledgeBundleImpl({ repository: repository.repository, cliVersion, offline, refresh, token, endpoint, accountId, organizationId, ...dependencies });
+      pinnedLoad = loadKnowledgeBundleImpl({ ...dependencies, repository: repository.repository, cliVersion, offline, refresh, token, endpoint, accountId, organizationId, onRecoveryEvent });
     }
     const loaded = await pinnedLoad;
-    if (!loaded.bundle) return { ...unavailable(loaded.warnings[0], repository.repository), warnings: loaded.warnings, diagnostic: loaded.diagnostic };
+    if (!loaded.bundle) {
+      // A failed read must not poison the run permanently. A later explicit
+      // same-scope check or refreshed sign-in may try loading again.
+      pinnedLoad = null;
+      return { ...unavailable(loaded.warnings[0], repository.repository), warnings: loaded.warnings, diagnostic: loaded.diagnostic };
+    }
+    if (pinnedSystemScope === undefined) pinnedSystemScope = loaded.bundle.system_scope || null;
+    else if (!sameSystemScope(pinnedSystemScope, loaded.bundle.system_scope || null)) {
+      return { ...unavailable("SQM system scope changed during recovery; authorize the current scope before a new check.", repository.repository),
+        diagnostic: { stage: "knowledge_loading", code: "authorization_scope_changed", retryable: false } };
+    }
     try {
       const evaluate = executeKnowledgeBundleImpl
         ? async (bundle, currentRepository) => ({ findings: await executeKnowledgeBundleImpl(bundle, currentRepository), modules: [] })
         : evaluateKnowledgeBundleImpl;
       if (phase === "full") {
-        if (!latestMinCheck || !sameRepositoryIdentity(latestMinCheck.repository_identity, repositoryIdentity(repository))) {
+        if (!latestMinCheck || !sameRepositoryIdentity(latestMinCheck.repository_identity, repositoryIdentity(repository)) ||
+            latestMinCheck.knowledge_bundle.digest !== loaded.bundle.integrity.digest) {
           latestMinCheck = await buildMinCheck({ repository, bundle: loaded.bundle, evaluation: await evaluate(loaded.bundle, repository), organizationId: organizationId || loaded.bundle.organization_id, cliVersion });
         }
-        const full = await buildFullCheck({ repository, bundle: loaded.bundle, minCheck: latestMinCheck, evaluation: await evaluate(loaded.bundle, repository), organizationId: organizationId || loaded.bundle.organization_id, cliVersion, deviceId, accountId });
+        const fullEvaluation = await evaluate(loaded.bundle, repository);
+        const current = await inspectRepositoryImpl(cwd, { baseBranch, runCommand: dependencies.runCommand });
+        if (!sameRepositoryIdentity(repositoryIdentity(repository), repositoryIdentity(current))) {
+          throw candidateError("Repository identity changed during SQM full verification; no current proof can be signed.");
+        }
+        const full = await buildFullCheck({ repository, bundle: loaded.bundle, minCheck: latestMinCheck, evaluation: fullEvaluation, organizationId: organizationId || loaded.bundle.organization_id, cliVersion, deviceId, accountId, signingKeyPath });
         try {
           full.upload = await uploadRunEvidenceImpl({ endpoint: evidenceEndpoint, token, proof: full.proof, signedEvidence: full.signed_evidence });
         } catch (error) {
-          full.upload = { uploaded: false, reason: `upload_failed: ${message(error)}`, diagnostic: safeSqmDiagnostic(error, "evidence_upload", "evidence_upload_failed") };
+          full.upload = { uploaded: false, reason: `upload_failed: ${message(error)}` };
+          full.upload.diagnostic = { ...safeSqmDiagnostic(error, "evidence_upload", "evidence_upload_failed"), ...sqmDiagnostic(error, "evidence_upload") };
+          await onRecoveryEvent(full.upload.diagnostic);
           full.warnings.push(`SQM signed evidence remains local because Cloud upload failed: ${message(error)}`);
         }
         return full;
@@ -66,16 +94,32 @@ export function createSqmChecker({
       latestMinCheck = await buildMinCheck({ repository, bundle: loaded.bundle, evaluation: await evaluate(loaded.bundle, repository), organizationId: organizationId || loaded.bundle.organization_id, cliVersion });
       return toLegacyCheck(latestMinCheck, loaded);
     } catch (error) {
-      return { ...unavailable(`SQM ${phase} execution failed: ${message(error)}`, repository.repository), bundle: bundleIdentity(loaded.bundle), diagnostic: safeSqmDiagnostic(error, phase, "sqm_execution_failed"), warnings: [...loaded.warnings, `SQM ${phase} execution failed: ${message(error)}`] };
+      return { ...unavailable(`SQM ${phase} execution failed: ${message(error)}`, repository.repository), bundle: bundleIdentity(loaded.bundle), warnings: [...loaded.warnings, `SQM ${phase} execution failed: ${message(error)}`], diagnostic: { ...safeSqmDiagnostic(error, `${phase}_check`, "sqm_execution_failed"), ...sqmDiagnostic(error, `${phase}_check`) } };
     }
   };
-  return async (attempt, options = {}) => {
+  const checker = async (attempt, options = {}) => {
     const save = createSqmCheckRecorder({ root: historyRoot, scope: historyRoot ? { webOrigin, accountId, organizationId } : null, phase: options.phase || "min", cwd, baseBranch });
     try {
       const result = await checkCurrentRepository(attempt, options);
       await save(result); return result;
-    } catch (error) { await save({ status: "failed", diagnostic: safeSqmDiagnostic(error, options.phase || "min") }); throw error; }
+    } catch (error) {
+      const stage = options.phase === "full" ? "full_check" : "min_check";
+      const diagnostic = { ...safeSqmDiagnostic(error, stage), ...sqmDiagnostic(error, stage) };
+      if (diagnostic.retryable) pinnedLoad = null;
+      await save({ status: "failed", diagnostic }); throw error;
+    }
   };
+  checker.updateSession = (next) => {
+    for (const [field, current] of Object.entries({ accountId, organizationId, deviceId, endpoint, webOrigin })) {
+      if (current && next?.[field] !== current) {
+        const error = new Error(`SQM session changed its ${field}; the original scope cannot be resumed with it.`);
+        error.code = "authorization_scope_changed"; throw error;
+      }
+    }
+    if (!next?.token) throw new Error("An authenticated same-scope SQM session is required.");
+    if (next.token !== token) { token = next.token; pinnedLoad = null; }
+  };
+  return checker;
 }
 
 export async function runSqmMinCheck(options) {
@@ -89,15 +133,52 @@ export async function runSqmCheck(options) {
   const context = await loadContext(options);
   if (!context.loaded.bundle) return { ...unavailable(context.loaded.warnings[0], context.repository.repository), warnings: context.loaded.warnings, diagnostic: context.loaded.diagnostic };
   verifyMinCheck(options.minCheck);
-  if (!sameRepositoryIdentity(options.minCheck.repository_identity, repositoryIdentity(context.repository))) throw Object.assign(new Error("Repository identity changed after min-check; run `simy sqm min-check` again."), { code: "repository_identity_changed", stage: "identity_validation" });
-  if (options.minCheck.knowledge_bundle.digest !== context.loaded.bundle.integrity.digest) throw Object.assign(new Error("Knowledge bundle changed after min-check; run `simy sqm min-check` again so both phases use one pinned bundle."), { code: "knowledge_bundle_changed", stage: "identity_validation" });
-  const evaluation = await (options.evaluateKnowledgeBundleImpl || evaluateKnowledgeBundle)(context.loaded.bundle, context.repository);
-  return buildFullCheck({ repository: context.repository, bundle: context.loaded.bundle, minCheck: options.minCheck, evaluation, organizationId: options.organizationId, cliVersion: options.cliVersion, deviceId: options.deviceId, accountId: options.accountId, signingKeyPath: options.signingKeyPath });
+  if (options.minCheck.organization_id !== options.organizationId || context.loaded.bundle.organization_id !== options.organizationId) {
+    throw scopeError("SQM organization changed after min-check; authorize the original organization before resuming.");
+  }
+  if (!sameRepositoryIdentity(options.minCheck.repository_identity, repositoryIdentity(context.repository))) throw Object.assign(candidateError("Repository identity changed after min-check; run `simy sqm min-check` again."), { stage: "identity_validation" });
+  if (!sameSystemScope(options.minCheck.knowledge_bundle.system_scope || null, context.loaded.bundle.system_scope || null)) {
+    throw scopeError("SQM system scope changed after min-check; authorize the current scope before a new check.");
+  }
+  const evaluate = options.evaluateKnowledgeBundleImpl || evaluateKnowledgeBundle;
+  let minCheck = options.minCheck;
+  if (minCheck.knowledge_bundle.digest !== context.loaded.bundle.integrity.digest) {
+    await options.onRecoveryEvent?.({ stage: "full_check", code: "knowledge_bundle_changed", retryable: true });
+    minCheck = await buildMinCheck({ repository: context.repository, bundle: context.loaded.bundle,
+      evaluation: await evaluate(context.loaded.bundle, context.repository), organizationId: options.organizationId, cliVersion: options.cliVersion });
+    const current = await (options.inspectRepositoryImpl || inspectRepository)(options.cwd || process.cwd(), { baseBranch: options.baseBranch || "dev", runCommand: options.runCommand });
+    if (!sameRepositoryIdentity(minCheck.repository_identity, repositoryIdentity(current))) throw new Error("Repository identity changed during min-check recovery; run `simy sqm min-check` again.");
+  }
+  const evaluation = await evaluate(context.loaded.bundle, context.repository);
+  const verifiedRepository = await (options.inspectRepositoryImpl || inspectRepository)(options.cwd || process.cwd(), { baseBranch: options.baseBranch || "dev", runCommand: options.runCommand });
+  if (!sameRepositoryIdentity(repositoryIdentity(context.repository), repositoryIdentity(verifiedRepository))) {
+    throw candidateError("Repository identity changed during SQM full verification; no current proof can be signed.");
+  }
+  const result = await buildFullCheck({ repository: context.repository, bundle: context.loaded.bundle, minCheck, evaluation, organizationId: options.organizationId, cliVersion: options.cliVersion, deviceId: options.deviceId, accountId: options.accountId, signingKeyPath: options.signingKeyPath });
+  if (minCheck !== options.minCheck) result.recovery = { code: "knowledge_bundle_changed", previous_min_digest: options.minCheck.result_digest, current_min_digest: minCheck.result_digest };
+  return result;
 }
 
 async function loadContext(options) {
   const repository = await (options.inspectRepositoryImpl || inspectRepository)(options.cwd || process.cwd(), { baseBranch: options.baseBranch || "dev", runCommand: options.runCommand });
-  const loaded = await (options.loadKnowledgeBundleImpl || loadKnowledgeBundle)({ repository: repository.repository, cliVersion: options.cliVersion, offline: options.offline, refresh: options.refresh, token: options.token, endpoint: options.endpoint, accountId: options.accountId, organizationId: options.organizationId, ...(options.bundleDependencies || {}) });
+  const rejectedToken = options.token;
+  const originalIdentity = repositoryIdentity(repository);
+  const scope = Object.fromEntries(["accountId", "organizationId", "deviceId", "endpoint"].map(field => [field, options[field]]));
+  const load = (token) => (options.loadKnowledgeBundleImpl || loadKnowledgeBundle)({ ...(options.bundleDependencies || {}),
+    repository: repository.repository, cliVersion: options.cliVersion, offline: options.offline, refresh: options.refresh,
+    token, endpoint: scope.endpoint, accountId: scope.accountId, organizationId: scope.organizationId });
+  let loaded = await load(rejectedToken);
+  if (!loaded.bundle && loaded.diagnostic?.http_status === 401 && options.onAuthenticationRequired && !options.offline) {
+    await options.onRecoveryEvent?.(loaded.diagnostic);
+    const next = await options.onAuthenticationRequired({ rejectedToken, ...scope });
+    for (const field of ["accountId", "organizationId", "deviceId", "endpoint"]) {
+      if (scope[field] && next?.[field] !== scope[field]) throw scopeError(`SQM authorization changed its ${field}; do not resume another scope.`);
+    }
+    if (!next?.token || next.token === rejectedToken) throw scopeError("SQM authorization did not replace the rejected token.");
+    const current = await (options.inspectRepositoryImpl || inspectRepository)(options.cwd || process.cwd(), { baseBranch: options.baseBranch || "dev", runCommand: options.runCommand });
+    if (!sameRepositoryIdentity(originalIdentity, repositoryIdentity(current))) throw candidateError("Repository identity changed while waiting for SQM authorization; begin a new check against the current candidate.");
+    loaded = await load(next.token);
+  }
   return { repository, loaded };
 }
 
@@ -159,3 +240,12 @@ function unavailable(warning, repository = null) {
 }
 
 function message(error) { return error instanceof Error ? error.message : String(error); }
+
+function sameSystemScope(left, right) {
+  const normalized = (scope) => scope ? { organization_id: scope.organization_id,
+    repository: scope.repository?.toLowerCase(), graph_revision: scope.graph_revision,
+    repositories: [...(scope.repositories || [])].map((repository) => repository.toLowerCase()).sort() } : null;
+  return canonicalize(normalized(left)) === canonicalize(normalized(right));
+}
+function scopeError(message) { const error = new Error(message); error.code = "authorization_scope_changed"; return error; }
+function candidateError(message) { const error = new Error(message); error.code = "repository_identity_changed"; return error; }

package/src/sqm/proof.js

@@ -1,9 +1,9 @@
-import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, randomUUID, sign, verify } from "node:crypto";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { createHash, createPublicKey, randomUUID, sign, verify } from "node:crypto";
 import { homedir } from "node:os";
 import path from "node:path";
 
 import { canonicalize } from "./canonical.js";
+import { loadDeviceSigningIdentity } from "../device-signing-identity.js";
 
 export function repositoryIdentity(repository) {
   return {
@@ -98,7 +98,7 @@ export async function signProof(proof, {
   issuedAt = new Date().toISOString(),
 } = {}) {
   if (!deviceId) throw new Error("A trusted SIMY CLI device identity is required to sign SQM proof.");
-  const identity = await loadOrCreateSigningIdentity(keyPath);
+  const identity = await loadDeviceSigningIdentity(keyPath, { create: true });
   const proofDigest = verifyProof(proof);
   const signature = sign(null, Buffer.from(proofDigest.slice("sha256:".length), "hex"), identity.privateKey).toString("base64");
   return {
@@ -133,26 +133,6 @@ export function verifySignedEvidence(proof, evidence) {
   return { proof_digest: proofDigest, key_id: keyId, valid: true };
 }
 
-async function loadOrCreateSigningIdentity(location) {
-  try {
-    const parsed = JSON.parse(await readFile(location, "utf8"));
-    const privateKey = createPrivateKey({ key: Buffer.from(parsed.private_key, "base64"), format: "der", type: "pkcs8" });
-    const publicKeyDer = Buffer.from(parsed.public_key, "base64");
-    const keyId = `sha256:${createHash("sha256").update(publicKeyDer).digest("hex")}`;
-    if (parsed.key_id !== keyId) throw new Error("stored key ID mismatch");
-    return { privateKey, publicKeyDer, keyId };
-  } catch (error) {
-    if (error?.code !== "ENOENT") throw new Error(`SQM signing identity is invalid: ${error.message}`);
-  }
-  const pair = generateKeyPairSync("ed25519");
-  const privateKeyDer = pair.privateKey.export({ format: "der", type: "pkcs8" });
-  const publicKeyDer = pair.publicKey.export({ format: "der", type: "spki" });
-  const keyId = `sha256:${createHash("sha256").update(publicKeyDer).digest("hex")}`;
-  await mkdir(path.dirname(location), { recursive: true, mode: 0o700 });
-  await writeFile(location, `${JSON.stringify({ algorithm: "ed25519", key_id: keyId, private_key: privateKeyDer.toString("base64"), public_key: publicKeyDer.toString("base64"), created_at: new Date().toISOString() }, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
-  return { privateKey: pair.privateKey, publicKeyDer, keyId };
-}
-
 function taggedDigest(value) {
   return `sha256:${createHash("sha256").update(canonicalize(value), "utf8").digest("hex")}`;
 }

package/src/sqm/request-recovery.js

@@ -0,0 +1,82 @@
+const TRANSIENT_STATUSES = new Set([502, 503, 504]);
+const NETWORK_CODES = new Set(["ECONNRESET", "ECONNREFUSED", "ENETUNREACH", "EAI_AGAIN", "ETIMEDOUT", "UND_ERR_CONNECT_TIMEOUT", "UND_ERR_SOCKET"]);
+
+export function sqmDiagnostic(error, stage = "unknown") {
+  const status = error?.http_status ?? error?.status;
+  const timeout = error?.name === "TimeoutError" || error?.code === "ETIMEDOUT";
+  const network = (error instanceof TypeError && /fetch failed|failed to fetch|network request failed/i.test(error.message)) ||
+    NETWORK_CODES.has(error?.code) || NETWORK_CODES.has(error?.cause?.code);
+  const safeCode = typeof error?.code === "string" && /^[a-z][a-z0-9_]{0,79}$/.test(error.code) ? error.code : null;
+  return {
+    stage: typeof error?.stage === "string" && /^[a-z][a-z0-9_]{0,79}$/.test(error.stage) ? error.stage : stage,
+    code: safeCode || (status === 401 ? "sign_in_required" : status === 403 ? "access_denied" :
+      status === 409 ? "scope_unresolved" : TRANSIENT_STATUSES.has(status) ? "gateway_unavailable" :
+      timeout ? "request_timeout" : network ? "network_unavailable" : "check_failed"),
+    ...(Number.isInteger(status) && status >= 400 && status <= 599 ? { http_status: status } : {}),
+    retryable: error?.retryable !== false && (TRANSIENT_STATUSES.has(status) || timeout || network),
+  };
+}
+
+// This deliberately exposes only GET recovery. Uncertain POST success must be
+// reconciled with a server idempotency contract before it may be replayed.
+export async function fetchSqmRead(url, {
+  headers, signal, fetchImpl = globalThis.fetch,
+  timeoutMs = 45_000, requestTimeoutMs = 15_000, maxAttempts = 3,
+  sleep = abortableSleep, now = Date.now, onRecoveryEvent = async () => {},
+} = {}) {
+  const totalLimit = boundedInteger(timeoutMs, 45_000);
+  const requestLimit = boundedInteger(requestTimeoutMs, 15_000);
+  const deadline = now() + totalLimit;
+  const deadlineSignal = AbortSignal.timeout(totalLimit);
+  const attempts = boundedInteger(maxAttempts, 3);
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    signal?.throwIfAborted();
+    deadlineSignal.throwIfAborted();
+    const remaining = deadline - now();
+    if (remaining <= 0) throw new DOMException("SQM request recovery deadline exceeded.", "TimeoutError");
+    const attemptSignal = AbortSignal.any([
+      deadlineSignal, AbortSignal.timeout(Math.min(requestLimit, remaining)),
+      ...(signal ? [signal] : []),
+    ]);
+    try {
+      const response = await withAbort(fetchImpl(url, { method: "GET", headers, signal: attemptSignal }), attemptSignal);
+      if (!TRANSIENT_STATUSES.has(response.status)) return response;
+      const error = new Error(`SQM Cloud returned HTTP ${response.status}.`);
+      error.status = response.status;
+      if (attempt === attempts) return response;
+      await response.body?.cancel().catch(() => {});
+      throw error;
+    } catch (error) {
+      if (signal?.aborted) throw signal.reason;
+      const diagnostic = sqmDiagnostic(error, "knowledge_loading");
+      if (!diagnostic.retryable || attempt === attempts || deadlineSignal.aborted) throw error;
+      await onRecoveryEvent({ ...diagnostic, attempt, recovery: "retrying" });
+      const delay = Math.min(250 * 2 ** (attempt - 1), Math.max(0, deadline - now()));
+      if (delay <= 0) throw new DOMException("SQM request recovery deadline exceeded.", "TimeoutError");
+      await sleep(delay, AbortSignal.any([deadlineSignal, ...(signal ? [signal] : [])]));
+    }
+  }
+}
+
+function boundedInteger(value, maximum) {
+  return Number.isFinite(value) && value > 0 ? Math.min(maximum, Math.max(1, Math.floor(value))) : maximum;
+}
+
+function withAbort(promise, signal) {
+  return new Promise((resolve, reject) => {
+    const abort = () => { signal.removeEventListener("abort", abort); reject(signal.reason); };
+    if (signal.aborted) abort();
+    else signal.addEventListener("abort", abort, { once: true });
+    Promise.resolve(promise).then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+  });
+}
+
+function abortableSleep(milliseconds, signal) {
+  signal.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    const finish = () => { signal.removeEventListener("abort", abort); resolve(); };
+    const timer = setTimeout(finish, milliseconds);
+    const abort = () => { clearTimeout(timer); signal.removeEventListener("abort", abort); reject(signal.reason); };
+    signal.addEventListener("abort", abort, { once: true });
+  });
+}