@cassiomc1/forgeloop 1.3.0 → 1.6.0

package/src/core/policy-engine.js

@@ -136,13 +136,15 @@ export async function detectPolicyCapability(target, packageRoot) {
   const baselineRel = PROJECT_ARTIFACT_PATHS.policyBaseline;
   const discoveryRel = PROJECT_ARTIFACT_PATHS.policyDiscovery;
   const lockRel = PROJECT_ARTIFACT_PATHS.policyLock;
+  const capabilityRel = PROJECT_ARTIFACT_PATHS.capabilityPolicy;
 
   const hasRules = await fileExists(path.join(target, rulesRel));
   const hasBaseline = await fileExists(path.join(target, baselineRel));
   const hasDiscovery = await fileExists(path.join(target, discoveryRel));
   const hasLock = await fileExists(path.join(target, lockRel));
+  const hasCapabilityPolicy = await fileExists(path.join(target, capabilityRel));
 
-  if (!hasRules && !hasBaseline && !hasDiscovery && !hasLock) {
+  if (!hasRules && !hasBaseline && !hasDiscovery && !hasLock && !hasCapabilityPolicy) {
     return "NOT_PRESENT";
   }
 
@@ -151,6 +153,13 @@ export async function detectPolicyCapability(target, packageRoot) {
     if (hasBaseline) await readBaseline(target, packageRoot);
     if (hasDiscovery) await readDiscoveryReport(target, packageRoot);
     if (hasLock) await readPolicyLock(target, packageRoot);
+    // A capability policy is policy configuration: its presence makes the
+    // executable-policy subsystem applicable and it must fail closed when
+    // malformed.
+    if (hasCapabilityPolicy) {
+      const { loadCapabilityPolicy } = await import("./capability-policy.js");
+      await loadCapabilityPolicy(target, packageRoot);
+    }
     return "AVAILABLE";
   } catch {
     return "INVALID";
@@ -190,12 +199,22 @@ export function canonicalizeBaseline(baseline) {
   };
 }
 
-export function computePolicyLockData(rules, baseline) {
+export function computePolicyLockData(rules, baseline, capabilityPolicy = null) {
   const canonicalRules = canonicalizeRules(rules);
   const canonicalBase = canonicalizeBaseline(baseline);
   const rulesDigest = sha256(canonicalFingerprint(canonicalRules));
   const baselineDigest = sha256(canonicalFingerprint(canonicalBase));
-  const fullDigest = sha256(`${rulesDigest}:${baselineDigest}`);
+  // The capability policy participates in the lock only when the artifact
+  // exists, keeping historical locks stable for projects that never adopt
+  // durable actions.
+  const capabilityPolicyDigest =
+    capabilityPolicy && typeof capabilityPolicy === "object"
+      ? sha256(canonicalFingerprint(capabilityPolicy))
+      : null;
+  const fullDigest =
+    capabilityPolicyDigest === null
+      ? sha256(`${rulesDigest}:${baselineDigest}`)
+      : sha256(`${rulesDigest}:${baselineDigest}:${capabilityPolicyDigest}`);
 
   return {
     schemaVersion: 1,
@@ -203,10 +222,78 @@ export function computePolicyLockData(rules, baseline) {
     digest: `sha256:${fullDigest}`,
     rulesDigest: `sha256:${rulesDigest}`,
     baselineDigest: `sha256:${baselineDigest}`,
+    ...(capabilityPolicyDigest === null
+      ? {}
+      : { capabilityPolicyDigest: `sha256:${capabilityPolicyDigest}` }),
     capturedAt: new Date().toISOString(),
   };
 }
 
+export async function readCapabilityPolicyIdentityForLock(target, packageRoot) {
+  const { readCapabilityPolicyIdentity } = await import("./capability-policy.js");
+  return readCapabilityPolicyIdentity(target, packageRoot);
+}
+
+/**
+ * Canonical policy identity for durable-action authorization. Fails closed
+ * with deterministic codes whenever the capability policy, the persisted
+ * lock, or the task snapshot do not agree.
+ */
+export async function loadPolicyIdentity(target, packageRoot, taskId) {
+  const { E_ACTION_POLICY_DRIFT, E_ACTION_POLICY_LOCK_REQUIRED } = await import("./error-codes.js");
+  const capability = await readCapabilityPolicyIdentityForLock(target, packageRoot);
+  const lock = await verifyPolicyLock(target, packageRoot);
+  const snapshot = taskId ? await readTaskPolicySnapshot(target, taskId, packageRoot) : null;
+
+  if (capability.policy && lock.status !== "VALID") {
+    return {
+      status: lock.status === "MISMATCH" ? "DRIFT" : "INVALID",
+      code: lock.status === "MISMATCH" ? E_ACTION_POLICY_DRIFT : E_ACTION_POLICY_LOCK_REQUIRED,
+      ...(lock.status === "MISMATCH" ? { mismatches: lock.mismatches } : {}),
+    };
+  }
+
+  // A modern task snapshot must bind the current capability policy before any
+  // side-effecting action may be authorized.
+  if (
+    capability.digest
+    && snapshot
+    && snapshot.capabilityPolicyDigest !== capability.digest
+  ) {
+    return {
+      status: "DRIFT",
+      code: E_ACTION_POLICY_DRIFT,
+    };
+  }
+
+  // A modern capability policy without a task snapshot has no epoch to bind:
+  // authorization cannot proceed for a task-scoped action.
+  if (capability.digest && taskId && !snapshot) {
+    return {
+      status: "INVALID",
+      code: E_ACTION_POLICY_LOCK_REQUIRED,
+    };
+  }
+
+  return {
+    status: "VALID",
+    lockDigest: lock.digest ?? null,
+    taskPolicyDigest: snapshot?.policyDigest ?? null,
+    capabilityPolicyFingerprint: capability.fingerprint,
+    capabilityPolicyDigest: capability.digest,
+  };
+}
+
+/**
+ * Compute policy-lock data for persistence, binding the current capability
+ * policy whenever it exists so locks, snapshots, and authorization evidence
+ * share one policy identity.
+ */
+export async function computePersistedPolicyLockData(target, packageRoot, rules, baseline) {
+  const identity = await readCapabilityPolicyIdentityForLock(target, packageRoot);
+  return computePolicyLockData(rules, baseline, identity.policy);
+}
+
 export async function verifyPolicyLock(target, packageRoot) {
   const capability = await detectPolicyCapability(target, packageRoot);
   if (capability === "NOT_PRESENT") {
@@ -223,7 +310,18 @@ export async function verifyPolicyLock(target, packageRoot) {
 
   const rules = await loadEffectiveRules(target, packageRoot);
   const baseline = await readBaseline(target, packageRoot);
-  const expectedLock = computePolicyLockData(rules, baseline);
+  let capabilityPolicy = null;
+  try {
+    const { loadCapabilityPolicy } = await import("./capability-policy.js");
+    const loadedCapabilityPolicy = await loadCapabilityPolicy(target, packageRoot);
+    capabilityPolicy = loadedCapabilityPolicy?.policy ?? null;
+  } catch (error) {
+    if (error.code === "E_POLICY_INVALID") {
+      return { status: "INVALID", error: "Capability policy artifact is malformed" };
+    }
+    throw error;
+  }
+  const expectedLock = computePolicyLockData(rules, baseline, capabilityPolicy);
 
   const mismatches = [];
   if (persistedLock.algorithm !== expectedLock.algorithm) {
@@ -238,6 +336,12 @@ export async function verifyPolicyLock(target, packageRoot) {
   if (persistedLock.baselineDigest !== expectedLock.baselineDigest) {
     mismatches.push("baselineDigest");
   }
+  if (
+    expectedLock.capabilityPolicyDigest !== undefined &&
+    persistedLock.capabilityPolicyDigest !== expectedLock.capabilityPolicyDigest
+  ) {
+    mismatches.push("capabilityPolicyDigest");
+  }
 
   if (mismatches.length > 0) {
     return {
@@ -254,6 +358,9 @@ export async function verifyPolicyLock(target, packageRoot) {
         digest: persistedLock.digest ?? null,
         rulesDigest: persistedLock.rulesDigest ?? null,
         baselineDigest: persistedLock.baselineDigest ?? null,
+        ...(expectedLock.capabilityPolicyDigest === undefined
+          ? {}
+          : { capabilityPolicyDigest: persistedLock.capabilityPolicyDigest ?? null }),
       },
     };
   }
@@ -476,7 +583,7 @@ export async function evaluateTargetPolicy({
   if (taskId) {
     const taskSnapshot = await readTaskPolicySnapshot(target, taskId, packageRoot);
     if (taskSnapshot) {
-      const currentLock = computePolicyLockData(rules, baseline);
+      const currentLock = await computePersistedPolicyLockData(target, packageRoot, rules, baseline);
       if (taskSnapshot.policyDigest !== currentLock.digest) {
         const policyDiff = diffPolicies(
           { rules: taskSnapshot.rules, baseline: taskSnapshot.baseline, baselineDigest: taskSnapshot.baselineDigest },
@@ -513,7 +620,7 @@ export async function evaluateTargetPolicy({
     }
   }
 
-  const currentLock = computePolicyLockData(rules, baseline);
+  const currentLock = await computePersistedPolicyLockData(target, packageRoot, rules, baseline);
 
   return {
     status: errors.length === 0 ? "VALID" : "INVALID",

package/src/core/preflight-consistency.js

@@ -165,10 +165,34 @@ function sameBlockedPreflightEvent(event, result) {
     && event.details?.routingFingerprint === result.fingerprints.routing;
 }
 
+/**
+ * Returns the latest recorded preflight outcome event (READY or BLOCKED) for
+ * the task. An append-only lifecycle may legitimately contain an older READY
+ * event that was superseded by a later BLOCKED outcome (for example after the
+ * contract evolved or a gate requirement was added); the binding chronology is
+ * the latest outcome, not the first READY ever recorded.
+ */
+function latestPreflightOutcomeEvent(events, taskId) {
+  let latest = null;
+  for (const event of events) {
+    if ((event.event === "PREFLIGHT_READY" || event.event === "PREFLIGHT_BLOCKED")
+      && event.taskId === taskId) {
+      latest = event;
+    }
+  }
+  return latest;
+}
+
 export function assertExistingReadyLifecycleCompatibility(ledger, result) {
   if (result.status !== "READY") return;
-  const existingReady = ledger?.events?.find((event) => event.event === "PREFLIGHT_READY" && event.taskId === result.taskId);
-  if (existingReady && !sameReadyPreflightEvent(existingReady, result)) {
+  const events = ledger?.events ?? [];
+  const existingReady = events.findLast((event) => event.event === "PREFLIGHT_READY" && event.taskId === result.taskId);
+  if (!existingReady) return;
+  const latestOutcome = latestPreflightOutcomeEvent(events, result.taskId);
+  // A READY outcome superseded by a later BLOCKED outcome may be replaced by a
+  // fresh READY with different details once the blocked preflight is resolved.
+  if (latestOutcome?.event === "PREFLIGHT_BLOCKED") return;
+  if (!sameReadyPreflightEvent(existingReady, result)) {
     throw preflightError(
       "E_PHASE_CHRONOLOGY_INVALID",
       "PREFLIGHT_READY already exists with different READY preflight details; repair the contract, route, or gate lifecycle before refreshing preflight",
@@ -200,16 +224,18 @@ export async function appendActivationEvents(target, packageRoot, ledger, result
     }
   }
 
-  const existingReady = events.find((event) => event.event === "PREFLIGHT_READY" && event.taskId === result.taskId);
+  const existingReady = events.findLast((event) => event.event === "PREFLIGHT_READY" && event.taskId === result.taskId);
+  const latestOutcome = latestPreflightOutcomeEvent(events, result.taskId);
+  const readySupersededByBlocked = existingReady && latestOutcome?.event === "PREFLIGHT_BLOCKED";
   if (result.status === "READY") {
-    if (existingReady && !sameReadyPreflightEvent(existingReady, result)) {
+    if (existingReady && !readySupersededByBlocked && !sameReadyPreflightEvent(existingReady, result)) {
       throw preflightError(
         "E_PHASE_CHRONOLOGY_INVALID",
         "PREFLIGHT_READY already exists with different READY preflight details; repair the contract, route, or gate lifecycle before refreshing preflight",
         [ARTIFACT_PATHS.preflight, ARTIFACT_PATHS.events, ARTIFACT_PATHS.contract, ARTIFACT_PATHS.route, ARTIFACT_PATHS.gates],
       );
     }
-    if (!existingReady) {
+    if (!existingReady || readySupersededByBlocked) {
       await append({
         taskId: result.taskId,
         event: "PREFLIGHT_READY",

package/src/core/preflight.js

@@ -200,7 +200,7 @@ export async function runPreflight({
       detectPolicyCapability,
       loadEffectiveRules,
       readBaseline,
-      computePolicyLockData,
+      computePersistedPolicyLockData,
       readTaskPolicySnapshot,
       writeTaskPolicySnapshot,
     } = await import("./policy-engine.js");
@@ -225,13 +225,30 @@ export async function runPreflight({
         if (!existingSnapshot) {
           const rules = await loadEffectiveRules(target, packageRoot);
           const baseline = await readBaseline(target, packageRoot);
-          const lock = computePolicyLockData(rules, baseline);
+          const lock = await computePersistedPolicyLockData(target, packageRoot, rules, baseline);
+          // Bind the current capability policy into the snapshot so policy
+          // drift is detectable before any side-effecting action launch.
+          const { readCapabilityPolicyIdentity } = await import("./capability-policy.js");
+          const capabilityIdentity = await readCapabilityPolicyIdentity(target, packageRoot);
+          if (capabilityIdentity.policy && !lock.capabilityPolicyDigest) {
+            throw preflightError(
+              "E_POLICY_SNAPSHOT_WRITE_FAILED",
+              "Capability policy identity could not be bound to the task policy snapshot",
+              [taskArtifactPath(result.taskId, "policySnapshot")],
+            );
+          }
           const snapshot = {
             schemaVersion: 1,
             policyDigest: lock.digest,
             rules,
             baseline: baseline ?? { schemaVersion: 1, entries: [] },
             baselineDigest: lock.baselineDigest,
+            ...(capabilityIdentity.digest
+              ? {
+                  capabilityPolicyDigest: capabilityIdentity.digest,
+                  capabilityPolicyFingerprint: capabilityIdentity.fingerprint,
+                }
+              : {}),
             capturedAt: new Date().toISOString(),
           };
           await writeTaskPolicySnapshot(target, result.taskId, snapshot, packageRoot);

package/src/core/prepared-execution.js

@@ -0,0 +1,227 @@
+import { randomUUID } from "node:crypto";
+import {
+  resolveExecutionResolution,
+  validateVerificationAuthority,
+  E_COMMAND_RESOLUTION_AMBIGUOUS,
+} from "./verification-capability.js";
+
+export { E_COMMAND_RESOLUTION_AMBIGUOUS };
+
+function executionError(code, message, artifacts = []) {
+  const error = new Error(message);
+  error.code = code;
+  error.artifacts = artifacts;
+  return error;
+}
+
+/**
+ * Deterministic pre-launch preparation. Normalizes exact argv, resolves the
+ * command, rejects ambiguous resolution contexts, and validates installation
+ * authority. Performs no process launch and writes no execution artifact
+ * (INV-EXEC-01): ACTION_STARTED is only meaningful after all of these checks
+ * succeed.
+ */
+export async function prepareCommandExecution({
+  target,
+  taskId,
+  argv,
+  details,
+  authorityContext,
+  runtimeContext,
+}) {
+  if (!Array.isArray(argv) || argv.length === 0 || argv.some((item) => typeof item !== "string" || item.trim() === "")) {
+    throw executionError("E_EXECUTION_INVALID", "Execution argv must contain at least one non-empty string");
+  }
+  const commandArgv = [...argv];
+  const resolution = await resolveExecutionResolution({
+    argv: commandArgv,
+    cwd: target,
+  });
+
+  if (
+    resolution.resolutionMode === "UNKNOWN"
+    && resolution.mayInstall === true
+    && (
+      resolution.reason === "NPM_WORKSPACE_SCRIPT_UNRESOLVED"
+      || resolution.reason === "NPM_SUBCOMMAND_AMBIGUOUS"
+      || resolution.reason === "NPM_COMMAND_UNCLASSIFIED"
+      || resolution.reason === "NPM_OPTION_VALUE_AMBIGUOUS"
+    )
+  ) {
+    const error = new Error(
+      resolution.reason === "NPM_WORKSPACE_SCRIPT_UNRESOLVED"
+        ? "npm workspace script execution cannot be proven from the current target. Run ForgeLoop against the selected workspace directory."
+        : "Command execution context could not be proven safe before launch."
+    );
+    error.code = E_COMMAND_RESOLUTION_AMBIGUOUS;
+    error.resolution = resolution;
+    throw error;
+  }
+
+  if (resolution.mayInstall) {
+    const check = {
+      kind: "command",
+      source: commandArgv[0],
+      details: {
+        ...(details ?? {}),
+        execution: { resolution },
+      },
+    };
+    const authority = validateVerificationAuthority(check, {
+      target,
+      taskId,
+      authorityContext,
+      runtimeContext,
+    });
+    if (!authority.valid) {
+      throw executionError(authority.error.code ?? "E_INSTALLATION_AUTHORITY_REQUIRED", authority.error.message);
+    }
+  }
+
+  return { argv: commandArgv, resolution };
+}
+
+const MAX_CAPTURED_OUTPUT_BYTES = 64 * 1024;
+
+async function executePreparedProcess(argv, cwd, { timeoutMs = null } = {}) {
+  const { spawn } = await import("node:child_process");
+  return new Promise((resolve) => {
+    let spawnError = null;
+    let timedOut = false;
+    let settled = false;
+    let timeout = null;
+    let forceTermination = null;
+    const stdout = [];
+    const stderr = [];
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let outputTruncated = false;
+    const capture = (chunks, chunk, total) => {
+      const available = MAX_CAPTURED_OUTPUT_BYTES - total;
+      if (available <= 0) {
+        outputTruncated = true;
+        return total;
+      }
+      if (chunk.length > available) {
+        chunks.push(chunk.subarray(0, available));
+        outputTruncated = true;
+        return total + available;
+      }
+      chunks.push(chunk);
+      return total + chunk.length;
+    };
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      if (timeout) clearTimeout(timeout);
+      if (forceTermination) clearTimeout(forceTermination);
+      resolve({
+        ...result,
+        timedOut,
+        stdout: Buffer.concat(stdout),
+        stderr: Buffer.concat(stderr),
+        stdoutBytes,
+        stderrBytes,
+        outputTruncated,
+      });
+    };
+    try {
+      const child = spawn(argv[0], argv.slice(1), {
+        cwd,
+        shell: false,
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+      child.stdout?.on("data", (chunk) => { stdoutBytes = capture(stdout, chunk, stdoutBytes); });
+      child.stderr?.on("data", (chunk) => { stderrBytes = capture(stderr, chunk, stderrBytes); });
+      child.once("error", (error) => {
+        spawnError = error;
+      });
+      child.once("close", (exitCode, signal) => {
+        finish({ exitCode, signal, spawnError });
+      });
+      if (Number.isInteger(timeoutMs) && timeoutMs > 0) {
+        timeout = setTimeout(() => {
+          timedOut = true;
+          child.kill("SIGTERM");
+          forceTermination = setTimeout(() => {
+            child.kill("SIGKILL");
+          }, TERMINATION_GRACE_MS_PREPARED);
+        }, timeoutMs);
+      }
+    } catch (error) {
+      finish({ exitCode: null, signal: null, spawnError: error });
+    }
+  });
+}
+
+export const TERMINATION_GRACE_MS_PREPARED = 1_000;
+
+/**
+ * Launch a prepared execution. The caller must have already recorded
+ * ACTION_STARTED; this function never performs deterministic pre-launch
+ * validation again.
+ */
+export async function runPreparedCommandExecution({
+  target,
+  packageRoot,
+  taskId,
+  checkId,
+  requirement,
+  verificationCycle = 1,
+  prepared,
+  timeoutMs = null,
+  executionPath,
+}) {
+  const { createHash } = await import("node:crypto");
+  const digest = (bytes) => createHash("sha256").update(bytes).digest("hex");
+  const executionId = `exec-${randomUUID()}`;
+  const startedAt = new Date().toISOString();
+  const processResult = await executePreparedProcess(prepared.argv, target, { timeoutMs });
+  const finishedAt = new Date().toISOString();
+  const execution = {
+    schemaVersion: 1,
+    protocolVersion: 1,
+    executionId,
+    taskId,
+    checkId,
+    requirement,
+    verificationCycle,
+    kind: "COMMAND_EXECUTION",
+    argv: prepared.argv,
+    cwd: target,
+    resolution: {
+      resolutionMode: prepared.resolution.resolutionMode,
+      mayInstall: prepared.resolution.mayInstall,
+      installer: prepared.resolution.installer,
+      tool: prepared.resolution.tool,
+    },
+    ...(prepared.resolution.dispatch ? { dispatch: prepared.resolution.dispatch } : {}),
+    startedAt,
+    finishedAt,
+    status: processResult.exitCode === 0 && !processResult.spawnError && !processResult.timedOut ? "passed" : "failed",
+    exitCode: processResult.exitCode,
+    durationMs: Math.max(0, Date.parse(finishedAt) - Date.parse(startedAt)),
+    termination: processResult.spawnError ? "spawn-error" : processResult.timedOut ? "timeout" : processResult.signal ? "signal" : "exit",
+    signal: processResult.signal ?? null,
+    stdoutSha256: digest(processResult.stdout),
+    stderrSha256: digest(processResult.stderr),
+    stdoutBytes: processResult.stdoutBytes,
+    stderrBytes: processResult.stderrBytes,
+    outputTruncated: processResult.outputTruncated,
+    ...(Number.isInteger(timeoutMs) && timeoutMs > 0 ? { timeoutMs, terminationGraceMs: TERMINATION_GRACE_MS_PREPARED } : {}),
+  };
+  const { writeJsonArtifact } = await import("./artifacts.js");
+  const written = await writeJsonArtifact(target, executionPath ?? await resolveExecutionArtifactPathFor(target, taskId, executionId), execution, "execution", packageRoot);
+  return {
+    path: written.path,
+    execution: written.value,
+    result: processResult.spawnError
+      ? "process failed to start"
+      : `process exited with code ${processResult.exitCode}`,
+  };
+}
+
+async function resolveExecutionArtifactPathFor(target, taskId, executionId) {
+  const { resolveExecutionArtifactPath } = await import("./execution.js");
+  return resolveExecutionArtifactPath(target, taskId, executionId);
+}

package/src/core/progress.js

@@ -1,4 +1,9 @@
 import { diagnosisEventsForTask } from "./diagnosis-model.js";
+import { resolveCurrentCycleDiagnostic } from "./diagnostic-projection.js";
+import {
+  buildInformationGainProjection,
+  evaluateStructuredDiagnosticStall,
+} from "./information-gain-projection.js";
 
 export const PROGRESS_STATUS = Object.freeze({
   ADVANCING: "ADVANCING",
@@ -32,7 +37,25 @@ export function evaluateProgress({ state, events = [] } = {}) {
 
   const taskEvents = Array.isArray(events) ? events.filter((e) => !state.taskId || e.taskId === state.taskId) : [];
   const diagEvents = diagnosisEventsForTask(taskEvents, state.taskId);
-  const latestDiag = diagEvents.at(-1)?.details ?? null;
+  const resolvedDiagnostic = resolveCurrentCycleDiagnostic(taskEvents, state.taskId, state.verificationCycle ?? null);
+  const latestDiag = resolvedDiagnostic?.details ?? diagEvents.at(-1)?.details ?? null;
+
+  let latestGainClassification = latestDiag?.informationGain ?? null;
+  let structuredStall = null;
+  if (resolvedDiagnostic?.sourceModel === "STRUCTURED_DIAGNOSTIC_CASE_V1") {
+    if (!Array.isArray(latestDiag.evidenceRefs)) {
+      latestDiag.evidenceRefs = [...new Set(
+        (latestDiag.hypotheses ?? []).flatMap((hypothesis) => hypothesis.evidenceRefs ?? []),
+      )];
+    }
+    // Canonical structured-stall truth; compatibility classification is presentation only.
+    structuredStall = evaluateStructuredDiagnosticStall(
+      buildInformationGainProjection(taskEvents, state.taskId),
+      { verificationCycle: state.verificationCycle ?? null },
+    );
+    latestDiag.effectiveInformationGain = !(structuredStall.stalled);
+    latestGainClassification = structuredStall.latestGain?.classification ?? null;
+  }
 
   // Build checksById index for resolving requirement from check IDs
   const checksById = new Map();
@@ -48,13 +71,27 @@ export function evaluateProgress({ state, events = [] } = {}) {
   }
 
   // 1. Check if latest diagnosis has NO information gain (global stall)
-  if (latestDiag && latestDiag.informationGain === "NONE") {
+  const legacyStalled = resolvedDiagnostic?.sourceModel !== "STRUCTURED_DIAGNOSTIC_CASE_V1"
+    && Boolean(latestDiag) && latestGainClassification === "NONE";
+  // Single normalized diagnostic-stall truth: structured diagnostics defer to
+  // the canonical structured stall evaluator; legacy diagnoses keep their
+  // compatibility rule (informationGain NONE).
+  const diagnosticStalled =
+    resolvedDiagnostic?.sourceModel === "STRUCTURED_DIAGNOSTIC_CASE_V1"
+      ? Boolean(structuredStall?.stalled)
+      : Boolean(legacyStalled);
+  if (diagnosticStalled) {
     status = PROGRESS_STATUS.STALLED;
     signals.push({
       code: PROGRESS_SIGNAL.NO_DIAGNOSTIC_INFORMATION_GAIN,
       severity: "BLOCKING_FOR_RETRY",
-      message: "Latest diagnosis repeats the prior hypothesis with the same evidence.",
+      message: resolvedDiagnostic?.sourceModel === "STRUCTURED_DIAGNOSTIC_CASE_V1"
+        ? "Latest diagnostic state introduces no effective new information relative to the prior comparable diagnostic state."
+        : "Latest diagnosis repeats the prior hypothesis with the same evidence.",
       verificationCycles: [latestDiag.verificationCycle],
+      ...(structuredStall?.latestGain
+        ? { classification: structuredStall.latestGain.classification, effectiveGain: false }
+        : {}),
     });
   }
 
@@ -88,7 +125,7 @@ export function evaluateProgress({ state, events = [] } = {}) {
   for (const [req, cyclesSet] of [...reqCycles.entries()].sort(([a], [b]) => a.localeCompare(b))) {
     if (cyclesSet.size >= 3) {
       const sortedCycles = [...cyclesSet].sort((a, b) => a - b);
-      const isLatestStalledForThisReq = latestDiag && latestDiag.informationGain === "NONE" && latestDiagReqs.includes(req);
+      const isLatestStalledForThisReq = diagnosticStalled && latestDiagReqs.includes(req);
       if (isLatestStalledForThisReq) {
         if (!signals.some((s) => s.code === PROGRESS_SIGNAL.REPEATED_FAILURE_WITH_SAME_DIAGNOSIS && s.requirement === req)) {
           signals.push({

package/src/core/project-root.js

@@ -0,0 +1,21 @@
+import path from "node:path";
+import { realpath } from "node:fs/promises";
+
+import { resolveTarget } from "./filesystem.js";
+
+/**
+ * Canonical project-root resolution for integrations. Applies exactly the
+ * same semantics as the CLI target resolver — the path must exist, must be a
+ * real directory (not a symlink), and is returned as an absolute path.
+ *
+ * Symlinked roots are rejected so that every transport agrees on whether a
+ * given project path is acceptable; use the resolved real directory instead.
+ */
+export async function resolveForgeLoopProjectRoot(projectPath, { cwd = process.cwd() } = {}) {
+  const target = await resolveTarget(cwd, projectPath);
+  return realpath(target);
+}
+
+export function defaultIntegrationProjectPath() {
+  return path.resolve(".");
+}

package/src/core/protocol-info.js

@@ -33,6 +33,67 @@ export function protocolInfo({ packageVersion = null } = {}) {
     readsSchemaVersions: schemaVersions,
     writesSchemaVersions: schemaVersions,
     compatibility: SCHEMA_COMPATIBILITY_POLICY,
+    features: {
+      taskClaimRecovery: {
+        version: 1,
+        durableRecoveryState: true,
+        explicitResume: true,
+        validatedClaimProjection: true,
+      },
+      integrationApi: {
+        version: 1,
+        structuredCommandRuntime: true,
+        canonicalResources: true,
+      },
+      executionHistory: {
+        version: 1,
+        supported: true,
+        schemaVersion: 1,
+      },
+      structuredTrace: {
+        version: 1,
+        supported: true,
+        schemaVersion: 1,
+      },
+      taskInspection: {
+        version: 1,
+        supported: true,
+        schemaVersion: 1,
+      },
+      reflection: {
+        version: 1,
+        supported: true,
+        schemaVersion: 1,
+      },
+      diagnostics: {
+        legacyDiagnosis: true,
+        structuredDiagnosticCase: true,
+        multifactorContributors: true,
+        hypothesisDisposition: true,
+        interventionLedger: true,
+        informationGainV2: true,
+        strategyOscillationDetection: true,
+      },
+      durableActions: {
+        version: 1,
+        supported: true,
+        states: ["PROPOSED", "AUTHORIZED", "STARTED", "COMMITTED", "VERIFIED", "FAILED", "COMMIT_UNKNOWN", "CANCELLED"],
+        reconciliation: true,
+        exactlyOnce: false,
+      },
+      capabilityPolicy: { version: 1, supported: true, decisions: ["ALLOW", "DENY", "REQUIRE_AUTHORITY", "REQUIRE_APPROVAL"] },
+      durableApprovals: { version: 1, supported: true, fingerprintBound: true, hostAttestationMinting: false },
+      trajectoryMetrics: { version: 1, supported: true, usageUnknownWhenUnreported: true, overallScore: false },
+      trajectoryEvaluation: { version: 1, supported: true, requiresReferenceScenario: true, source: "PROJECT_LOCAL_REFERENCE" },
+      observabilityStability: {
+        executionHistory: "stable",
+        structuredTrace: "stable",
+        taskInspection: "stable",
+        reflection: "stable",
+        informationGainV2: "stable",
+        strategyOscillationDetection: "stable",
+      },
+    },
     lifecycle: { phases: WORK_PHASES, transitions: WORK_TRANSITIONS },
     guides: Object.values(GUIDE_REGISTRY),
     commands: Object.values(CLI_COMMAND_DEFINITIONS).map(({ name, category, mutation, description }) => ({ name, category, mutation, description })),