@abelxiaoxing/cadence 1.4.1 → 1.5.0

package/src/operator-tools.ts

@@ -0,0 +1,249 @@
+import { spawnSync } from "node:child_process";
+import { lstatSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { executionProfile } from "./execution-profile.ts";
+import { resolveOpenSpecInvocation } from "./openspec-cli.ts";
+import { resolveStateRoot } from "./state-root.ts";
+import { requestBounds } from "./transport-budget.ts";
+import { validateVerificationAdapterCapability } from "./verification-capability.ts";
+
+export interface DoctorCheck {
+  name: string;
+  ok: boolean;
+  detail: string;
+  nextStep?: string;
+}
+export function inspectConsumer(root: string) {
+  root = realpathSync(root);
+  const checks: DoctorCheck[] = [];
+  const check = (name: string, action: () => string, nextStep: string) => {
+    try {
+      checks.push({ name, ok: true, detail: action() });
+    } catch (error) {
+      checks.push({
+        name,
+        ok: false,
+        detail: error instanceof Error ? error.message : "unavailable",
+        nextStep,
+      });
+    }
+  };
+  check(
+    "node",
+    () => {
+      if (
+        Number(process.versions.node.split(".")[0]) < 22 ||
+        (Number(process.versions.node.split(".")[0]) === 22 &&
+          Number(process.versions.node.split(".")[1]) < 13)
+      )
+        throw new Error("Node 22.13+ required");
+      return process.versions.node;
+    },
+    "Install Node >=22.13.",
+  );
+  check(
+    "git",
+    () => {
+      const result = spawnSync("git", ["rev-parse", "--show-toplevel"], {
+        cwd: root,
+        encoding: "utf8",
+        timeout: 5000,
+        maxBuffer: 65536,
+      });
+      if (result.status !== 0) throw new Error("git-repository-unavailable");
+      return result.stdout.trim();
+    },
+    "Install Git and initialize the consumer repository.",
+  );
+  check(
+    "openspec",
+    () => {
+      resolveOpenSpecInvocation(root);
+      return "resolved (protocol not executed)";
+    },
+    "Install @fission-ai/openspec@1.5.0, or configure ABEL_OPENSPEC_PACKAGE_ROOT / ABEL_OPENSPEC_NODE before launching the host.",
+  );
+  check(
+    "execution",
+    () => {
+      const profile = executionProfile();
+      if (process.platform !== "linux")
+        throw new Error("linux-pid-isolation-required");
+
+      const result = spawnSync(
+        profile.bwrapPath,
+        [
+          "--ro-bind",
+          "/",
+          "/",
+          profile.mode === "local-trusted" ? "--unshare-pid" : "--unshare-all",
+          "--",
+          "/bin/true",
+        ],
+        { timeout: 5000, encoding: "utf8", maxBuffer: 65536 },
+      );
+      if (result.status !== 0) throw new Error("bubblewrap-probe-failed");
+      return `${profile.mode}: Bubblewrap PID namespace probe passed`;
+    },
+    "On Linux install/enable Bubblewrap; set ABEL_BWRAP_PATH for a custom install. Trusted Linux projects may explicitly set ABEL_EXECUTION_MODE=local-trusted; Windows should use WSL.",
+  );
+  check(
+    "request-budgets",
+    () => JSON.stringify(requestBounds()),
+    "Set ABEL_FIRST_PROGRESS_MS and ABEL_STREAM_IDLE_MS to positive milliseconds <=1200000.",
+  );
+  check(
+    "state-root",
+    () =>
+      resolveStateRoot({
+        consumerRoot: root,
+        xdgStateHome: process.env.XDG_STATE_HOME,
+      }).rootDir,
+    "Use an absolute repository-external XDG_STATE_HOME.",
+  );
+  check(
+    "workspace-dependencies",
+    () => {
+      const dependencies = path.join(root, "node_modules");
+      if (!lstatSync(dependencies, { throwIfNoEntry: false }))
+        return "no node_modules; prepare dependencies before verification";
+      const names = readdirSync(dependencies).flatMap((name) =>
+        name.startsWith("@") &&
+        lstatSync(path.join(dependencies, name)).isDirectory()
+          ? readdirSync(path.join(dependencies, name)).map(
+              (child) => `${name}/${child}`,
+            )
+          : [name],
+      );
+      if (names.length > 20_000) throw new Error("dependency-view-too-large");
+      let links = 0;
+      for (const name of names) {
+        const file = path.join(dependencies, name);
+        if (!lstatSync(file).isSymbolicLink()) continue;
+        const resolved = realpathSync(file);
+        const relative = path.relative(root, resolved);
+        if (
+          relative === ".." ||
+          relative.startsWith(`..${path.sep}`) ||
+          path.isAbsolute(relative)
+        )
+          throw new Error("dependency-link-outside-consumer");
+        if (!resolved.startsWith(`${dependencies}${path.sep}`)) links++;
+      }
+      return `${links} repository workspace link(s); their targets must be included in the candidate baseline`;
+    },
+    "Repair dangling/external workspace links and ensure local package sources are tracked or admitted in the candidate.",
+  );
+  const manifest = path.join(root, "package.json");
+  if (lstatSync(manifest, { throwIfNoEntry: false })?.isFile()) {
+    check(
+      "manifest",
+      () => {
+        const parsed = JSON.parse(readFileSync(manifest, "utf8"));
+        if (!parsed || typeof parsed !== "object")
+          throw new Error("manifest-invalid");
+        return (
+          Object.keys(parsed.scripts ?? {}).join(", ") || "no package scripts"
+        );
+      },
+      "Repair package.json.",
+    );
+    const parsed = (() => {
+      try {
+        return JSON.parse(readFileSync(manifest, "utf8"));
+      } catch {
+        return {};
+      }
+    })();
+    for (const script of ["test", "check", "build"].filter(
+      (name) => typeof parsed.scripts?.[name] === "string",
+    )) {
+      check(
+        `script:${script}`,
+        () => {
+          const manager =
+            ["bun", "pnpm", "yarn", "npm"].find((name) =>
+              lstatSync(
+                path.join(
+                  root,
+                  (
+                    {
+                      bun: "bun.lock",
+                      pnpm: "pnpm-lock.yaml",
+                      yarn: "yarn.lock",
+                      npm: "package-lock.json",
+                    } as Record<string, string>
+                  )[name],
+                ),
+                { throwIfNoEntry: false },
+              ),
+            ) ?? "npm";
+          const result = validateVerificationAdapterCapability(root, {
+            kind: "package-script",
+            id: `doctor-${script}`,
+            packageManager: manager as "bun" | "pnpm" | "yarn" | "npm",
+            script,
+            command: parsed.scripts[script],
+            args: [],
+            classification: "expected-green",
+          });
+          if (!result.ok) throw new Error(result.diagnostic.code);
+          return "statically admitted; tests not executed";
+        },
+        "Check the runner, installed dependencies and execution configuration; this probe does not execute your tests.",
+      );
+    }
+  }
+  return { root, ok: checks.every((entry) => entry.ok), checks };
+}
+
+/** Bounded metadata traversal, no symlink following and no automatic deletion. */
+export function storageUsage(root: string, maximum = 100_000) {
+  let entries = 0;
+  let bytes = 0;
+  let truncated = false;
+  const visit = (file: string) => {
+    if (entries >= maximum) {
+      truncated = true;
+      return;
+    }
+    const stat = lstatSync(file, { throwIfNoEntry: false });
+    if (!stat) return;
+    entries++;
+    if (stat.isFile()) bytes += stat.size;
+    else if (stat.isDirectory())
+      for (const name of readdirSync(file)) {
+        visit(path.join(file, name));
+        if (truncated) break;
+      }
+  };
+  visit(root);
+  return { entries, bytes, truncated };
+}
+
+export function inspectRuns(root: string) {
+  const state = resolveStateRoot({
+    consumerRoot: root,
+    xdgStateHome: process.env.XDG_STATE_HOME,
+  });
+  const usage = storageUsage(state.rootDir);
+  if (!lstatSync(state.databasePath, { throwIfNoEntry: false }))
+    return { stateRoot: state.rootDir, usage, runs: [], truncated: false };
+  const db = new DatabaseSync(state.databasePath, { readOnly: true });
+  try {
+    const rows = db
+      .prepare(
+        "SELECT run_id, stage, change_name, state, sequence FROM runs ORDER BY run_id LIMIT 1001",
+      )
+      .all();
+    return {
+      stateRoot: state.rootDir,
+      usage,
+      runs: rows.slice(0, 1000),
+      truncated: rows.length > 1000,
+    };
+  } finally {
+    db.close();
+  }
+}

package/src/package-candidate.ts

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import path from "node:path";
 import { runChildSession } from "./child-session.ts";
+import type { VerificationFailureSummary } from "./contracts.ts";
 import { LIMITS } from "./contracts.ts";
 import type { DurableWorkflowEngineOptions } from "./durable-contracts.ts";
 import type { ParentModelSource } from "./model-source.ts";
@@ -25,6 +26,7 @@ export async function proposePackageCandidate(
   input: Parameters<DurableWorkflowEngineOptions["proposeCandidate"]>[0],
   context: ParentModelSource | undefined,
   implementationAgent: { content: string },
+  verificationDiagnostics: VerificationFailureSummary[] = [],
 ): Promise<DurableCandidateProposal> {
   if (!context) {
     return { kind: "paused", code: "parent-context-unavailable" };
@@ -88,6 +90,7 @@ export async function proposePackageCandidate(
     ]),
   ].sort();
   const phaseContract = {
+    verificationDiagnostics,
     candidateId: input.candidateArtifact.identity.candidateId,
     taskId: input.taskId,
     phase: input.phase,

package/src/package-verification.ts

@@ -7,6 +7,7 @@ import {
   type VerificationObservation,
   verificationSteps,
 } from "./contracts.ts";
+import { executionProfile } from "./execution-profile.ts";
 import { canonicalJson } from "./implement-graph.ts";
 import { BubblewrapIsolationBackend } from "./isolation-backend.ts";
 import { observeSafePath } from "./safe-path.ts";
@@ -15,6 +16,7 @@ import {
   isVerificationCapabilityCurrent,
   type VerificationRunnerBinding,
 } from "./verification-capability.ts";
+import { diagnosticText } from "./verification-diagnostics.ts";
 import { prepareVerificationEnvironment } from "./verification-environment.ts";
 
 function sha256(value: Uint8Array | string): string {
@@ -247,7 +249,7 @@ function normalizedFailureIdentities(input: {
     .replace(new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "gu"), "")
     .replace(/\r\n?/gu, "\n")
     .replace(/\b\d+(?:\.\d+)?(?:ms|s)\b/gu, "<duration>")
-    .slice(0, 64 * 1024);
+    .replace(/\b\d{4}-\d{2}-\d{2}T[\d:.]+Z\b/gu, "<timestamp>");
   return [
     sha256(
       canonicalJson({
@@ -313,6 +315,9 @@ export async function executePackageVerification(input: {
   maxReportBytes?: number;
   executionWritePaths?: readonly string[];
 }): Promise<VerificationObservation> {
+  let executionDiagnostic:
+    | import("./contracts.ts").VerificationFailureSummary
+    | undefined;
   const unavailable = (
     code: string,
     category: "environment" | "adapter" | "resource" = "adapter",
@@ -321,6 +326,16 @@ export async function executePackageVerification(input: {
     category,
     code,
     verificationId: input.verification.id,
+    ...(executionDiagnostic
+      ? {
+          diagnostic: {
+            ...executionDiagnostic,
+            code,
+            nextStep:
+              "Repair the runner, environment or report adapter; do not treat missing evidence as a product failure.",
+          },
+        }
+      : {}),
   });
   if (input.signal.aborted) return { kind: "cancelled" };
   const maxReportBytes = input.maxReportBytes ?? VERIFICATION_REPORT_LIMIT;
@@ -335,18 +350,37 @@ export async function executePackageVerification(input: {
     },
   );
   if (!capability.ok) return unavailable(capability.diagnostic.code);
-  let environment: ReturnType<typeof prepareVerificationEnvironment>;
+  let environment: Awaited<ReturnType<typeof prepareVerificationEnvironment>>;
   try {
-    environment = prepareVerificationEnvironment(
+    environment = await prepareVerificationEnvironment(
       input.root,
       input.dependencyOwner,
       capability.value.runnerBindings,
+      input.signal,
     );
-  } catch {
-    return unavailable("verification-environment-unavailable", "environment");
+  } catch (error) {
+    if (input.signal.aborted) return { kind: "cancelled" };
+    const code =
+      error instanceof Error &&
+      [
+        "workspace-dependency-missing",
+        "dependency-path-unsafe",
+        "execution-mode-invalid",
+        "verification-timeout-invalid",
+        "verification-environment-names-invalid",
+        "verification-environment-requires-trusted-mode",
+      ].includes(error.message)
+        ? error.message
+        : "verification-environment-unavailable";
+    return unavailable(code, "environment");
   }
   try {
-    const isolation = new BubblewrapIsolationBackend();
+    const profile = executionProfile();
+    const isolation = new BubblewrapIsolationBackend({
+      bwrapPath: profile.bwrapPath,
+      timeoutMs: profile.timeoutMs,
+      localTrusted: profile.mode === "local-trusted",
+    });
     let final: VerificationObservation | undefined;
     let sequence = 0;
     for (const step of verificationSteps(input.verification)) {
@@ -354,9 +388,17 @@ export async function executePackageVerification(input: {
       const invocation = verificationInvocation(
         step,
         environment.bindings,
-        `/cadence/${relative}`,
+        `${environment.reportRoot}/${relative}`,
       );
       if (!invocation) return unavailable("runner-missing");
+      if (profile.mode === "local-trusted") {
+        const translate = (value: string) =>
+          value.startsWith("/workspace/")
+            ? path.join(input.root, value.slice(11))
+            : value;
+        invocation.executable = translate(invocation.executable);
+        invocation.args = invocation.args.map(translate);
+      }
       const executed = await isolation.run({
         root: input.root,
         ...invocation,
@@ -376,6 +418,20 @@ export async function executePackageVerification(input: {
             : "environment",
         );
       }
+      executionDiagnostic = {
+        verificationId: step.id,
+        code: "verification-rejected",
+        exitCode: executed.exitCode,
+        failures: [],
+        stdout: diagnosticText(executed.stdout),
+        stderr: diagnosticText(executed.stderr),
+        truncated:
+          executed.logs.stdout.truncated ||
+          executed.logs.stderr.truncated ||
+          executed.stdout.length > 4096 ||
+          executed.stderr.length > 4096,
+        nextStep: "Inspect the reported verification failure.",
+      };
       let report: ReturnType<typeof vitestReport>;
       if (step.kind === "vitest") {
         try {
@@ -426,6 +482,7 @@ export async function executePackageVerification(input: {
         classification: step.classification,
         policy: "report-file-v3" as const,
         ...(report ? { tests: report.total } : {}),
+        attributionReliable: step.kind === "vitest",
         failureIdentities: accepted
           ? []
           : normalizedFailureIdentities({
@@ -443,12 +500,31 @@ export async function executePackageVerification(input: {
               ? "red-not-witnessed"
               : "verification-rejected",
           evidence,
+          diagnostic: {
+            verificationId: step.id,
+            code: "verification-rejected",
+            exitCode: executed.exitCode,
+            failures: (report?.failedText ?? [])
+              .slice(0, 16)
+              .map((text) => diagnosticText(text, 1024)),
+            stdout: diagnosticText(executed.stdout),
+            stderr: diagnosticText(executed.stderr),
+            truncated:
+              executed.logs.stdout.truncated ||
+              executed.logs.stderr.truncated ||
+              executed.stdout.length > 4096 ||
+              executed.stderr.length > 4096,
+            nextStep:
+              step.classification === "expected-red"
+                ? "Make the approved regression fail for the expected assertion, not an environment error."
+                : "Fix the reported failure in the candidate; preserve the accepted verification contract.",
+          },
         };
       final = { kind: "accepted", evidence };
     }
     return final ?? unavailable("verification-contract-unsupported");
   } finally {
-    environment.cleanup();
+    await environment.cleanup();
   }
 }
 
@@ -469,6 +545,7 @@ export function phaseVerificationResult(result: VerificationObservation) {
       kind: "retryable" as const,
       code: result.code,
       failureIdentities: result.evidence.failureIdentities,
+      attributionReliable: result.evidence.attributionReliable,
     };
   return {
     ok: false as const,
@@ -497,6 +574,7 @@ export function changeVerificationResult(result: VerificationObservation) {
       kind: "verification" as const,
       code: result.code,
       failureIdentities: result.evidence.failureIdentities,
+      attributionReliable: result.evidence.attributionReliable,
     };
   return {
     ok: false as const,

package/src/package-workflow.ts

@@ -9,6 +9,7 @@ import type {
 } from "./contracts.ts";
 import { validateControlCommand } from "./control-contracts.ts";
 import { DesignController } from "./design-control.ts";
+import { executionProfile } from "./execution-profile.ts";
 import type { PackageContext } from "./model-source.ts";
 import { inspectOpenSpecDelivery } from "./openspec-cli.ts";
 import { proposePackageCandidate } from "./package-candidate.ts";
@@ -25,7 +26,9 @@ import {
   unavailableRoutePolicy,
 } from "./route-policy.ts";
 import { resolveStateRoot } from "./state-root.ts";
+import { VerificationFeedback } from "./verification-diagnostics.ts";
 import { captureVerificationEnvironmentIdentity } from "./verification-environment.ts";
+import { coalesceVerificationScans } from "./verification-scan.ts";
 import { openDurableWorkflowEngine } from "./workflow-engine.ts";
 export interface PackageWorkflowService {
   execute(
@@ -88,6 +91,12 @@ export function openPackageWorkflowService(
     xdgStateHome: process.env.XDG_STATE_HOME,
   });
   const contexts = new AsyncLocalStorage<PackageContext>();
+  const feedback = new AsyncLocalStorage<VerificationFeedback>();
+  const verify: typeof executePackageVerification = async (input) => {
+    const result = await executePackageVerification(input);
+    feedback.getStore()?.observe(result);
+    return result;
+  };
   const design = DesignController.open({
     consumerRoot,
     stateRoot,
@@ -113,25 +122,27 @@ export function openPackageWorkflowService(
   const workHardLimit = hostLimit("ABEL_WORK_MAX_UNITS", 512);
   const engine = openDurableWorkflowEngine({
     workHardLimit,
-    verificationPolicy: "report-file-v4",
-    verificationEnvironment: (plan, signal) =>
-      captureVerificationEnvironmentIdentity(
-        consumerRoot,
-        [
-          ...plan.tasks.flatMap((task) => [
-            ...Object.values(task.phases).map((phase) => phase.verification),
-            task.affectedVerification,
-            task.repairVerification,
-          ]),
-          plan.verification.baseline.fullSuite,
-          plan.verification.change.fullSuite,
-          plan.verification.change.postApply,
-          ...(plan.verification.agentsCheckpoint.verification
-            ? [plan.verification.agentsCheckpoint.verification]
-            : []),
-        ],
-        signal,
-      ),
+    verificationPolicy: `report-file-v5:${JSON.stringify(executionProfile())}`,
+    verificationEnvironment: coalesceVerificationScans(
+      (plan: import("./implement-plan.ts").ImplementPlan, signal) =>
+        captureVerificationEnvironmentIdentity(
+          consumerRoot,
+          [
+            ...plan.tasks.flatMap((task) => [
+              ...Object.values(task.phases).map((phase) => phase.verification),
+              task.affectedVerification,
+              task.repairVerification,
+            ]),
+            plan.verification.baseline.fullSuite,
+            plan.verification.change.fullSuite,
+            plan.verification.change.postApply,
+            ...(plan.verification.agentsCheckpoint.verification
+              ? [plan.verification.agentsCheckpoint.verification]
+              : []),
+          ],
+          signal,
+        ),
+    ),
     consumerRoot,
     stateRoot,
     deliverySource: packageDeliverySource(consumerRoot, {
@@ -142,10 +153,15 @@ export function openPackageWorkflowService(
       ? routeResolution.policy
       : unavailableRoutePolicy(),
     proposeCandidate: (input) =>
-      proposePackageCandidate(input, contexts.getStore(), implementationAgent),
+      proposePackageCandidate(
+        input,
+        contexts.getStore(),
+        implementationAgent,
+        feedback.getStore()?.current(),
+      ),
     verifyPhase: async (input) =>
       phaseVerificationResult(
-        await executePackageVerification({
+        await verify({
           maxReportBytes,
           executionWritePaths: input.executionWritePaths,
           root: input.root,
@@ -158,8 +174,9 @@ export function openPackageWorkflowService(
       const verifications = input.verification
         ? [input.verification]
         : input.plan.tasks.map((task) => affectedVerification(task));
+      let failure: ReturnType<typeof changeVerificationResult> | undefined;
       for (const verification of verifications) {
-        const result = await executePackageVerification({
+        const result = await verify({
           maxReportBytes,
           executionWritePaths: input.plan.tasks.flatMap((task) =>
             Object.values(task.phases).flatMap((phase) => [
@@ -173,8 +190,22 @@ export function openPackageWorkflowService(
           signal: input.signal,
         });
         const observed = changeVerificationResult(result);
-        if (!observed.ok) return observed;
+        if (!observed.ok) {
+          if (observed.kind !== "verification") return observed;
+          if (failure && !failure.ok && failure.kind === "verification") {
+            failure.failureIdentities = [
+              ...new Set([
+                ...(failure.failureIdentities ?? []),
+                ...(observed.failureIdentities ?? []),
+              ]),
+            ];
+            failure.attributionReliable =
+              failure.attributionReliable !== false &&
+              observed.attributionReliable !== false;
+          } else failure = observed;
+        }
       }
+      if (failure) return failure;
       return {
         ok: true,
         exitCode: 0,
@@ -205,18 +236,24 @@ export function openPackageWorkflowService(
         error.name = "ControlCommandError";
         throw error;
       }
-      return contexts.run(context, async () => {
-        const outcome = await engine.execute(
-          validation.value,
-          signal,
-          onActivity,
-        );
-        const routePolicy = visibleRoutePolicyStatus(
-          operationRouteResolution,
-          engine.routePolicyStatus(),
-        );
-        return { ...outcome, routePolicy };
-      });
+      return feedback.run(new VerificationFeedback(), () =>
+        contexts.run(context, async () => {
+          const outcome = await engine.execute(
+            validation.value,
+            signal,
+            onActivity,
+          );
+          const routePolicy = visibleRoutePolicyStatus(
+            operationRouteResolution,
+            engine.routePolicyStatus(),
+          );
+          return {
+            ...outcome,
+            routePolicy,
+            verificationDiagnostics: feedback.getStore()?.current() ?? [],
+          };
+        }),
+      );
     },
     executeDesign(request: unknown) {
       return design.execute(request);
@@ -235,6 +272,7 @@ export function openPackageWorkflowService(
     async close() {
       contexts.disable();
       await engine.close();
+      feedback.disable();
       design.close();
     },
   };

package/src/plan-draft-summary.ts

@@ -1,5 +1,6 @@
 import { isValidRelativePath } from "./contracts.ts";
 import type { ImplementPlan } from "./implement-plan.ts";
+import { expandSingleTaskDraft } from "./single-task-draft.ts";
 
 /** Review data only: no executable callbacks, evidence cache or approval authority. */
 function record(value: unknown): Record<string, unknown> {
@@ -11,7 +12,8 @@ export function planAuthoringSummary(
   plan: ImplementPlan,
   authoredDraft?: unknown,
 ) {
-  const authored = record(authoredDraft);
+  const quick = record(authoredDraft).singleTask !== undefined;
+  const authored = record(expandSingleTaskDraft(authoredDraft));
   const derivations: Array<{ field: string; source: string; taskId?: string }> =
     [];
   let derivationsTruncated = false;
@@ -22,6 +24,7 @@ export function planAuthoringSummary(
     }
     derivations.push({ field, source, ...(taskId ? { taskId } : {}) });
   };
+  if (quick) derived("singleTask", "single-task-author-input");
   if (authoredDraft !== undefined) {
     if (!Object.hasOwn(authored, "tracking")) derived("tracking", "task-ids");
     if (plan.changeContract && !Object.hasOwn(authored, "changeContract"))