p-dev-harness 0.3.1 → 0.4.0

package/workspace-snapshot/files/src/artifacts/write-json-out-manifest.ts

@@ -0,0 +1,90 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { MILESTONE } from "../config/defaults.js";
+import { emptyMergeManifestFields } from "./manifest-fields.js";
+import { redactSecrets } from "./redact.js";
+import { createRunId } from "./run-id.js";
+import type { ErrorClassification, RunManifest, RunPhase } from "../types/run.js";
+
+export interface FallbackManifestInput {
+  issueKey: string;
+  runId?: string;
+  phase?: RunPhase;
+  errorClassification?: ErrorClassification;
+  message?: string;
+  deliveryId?: string | null;
+  runGeneration?: number | null;
+  linearStatusBefore?: string | null;
+  runOwnedStatuses?: string[] | null;
+}
+
+export function buildFallbackRunManifest(input: FallbackManifestInput): RunManifest {
+  const startedAt = new Date().toISOString();
+  const runId = input.runId ?? createRunId(input.issueKey, new Date(startedAt));
+
+  return {
+    runId,
+    issueKey: input.issueKey,
+    phase: input.phase ?? "none",
+    phaseInferredFromStatus: input.linearStatusBefore ?? null,
+    linearStatusBefore: input.linearStatusBefore ?? null,
+    linearStatusAfter: input.linearStatusBefore ?? null,
+    targetRepo: null,
+    baseBranch: null,
+    resolutionSource: null,
+    dryRun: false,
+    finalOutcome: "failed",
+    errorClassification: input.errorClassification ?? null,
+    startedAt,
+    finishedAt: startedAt,
+    milestone: MILESTONE,
+    promptVersion: null,
+    cursorAgentId: null,
+    cursorRunId: null,
+    branch: null,
+    prUrl: null,
+    previewUrl: null,
+    validationSummary: input.message ?? null,
+    changedFiles: null,
+    checkSummary: null,
+    previousImplementationRunId: null,
+    previousHandoffRunId: null,
+    pmFeedbackCommentId: null,
+    ...emptyMergeManifestFields(),
+    model: null,
+    deliveryId: input.deliveryId ?? null,
+    runGeneration: input.runGeneration ?? null,
+    runOwnedStatuses: input.runOwnedStatuses ?? null,
+  };
+}
+
+export async function writeJsonOutManifest(
+  outputPath: string,
+  manifest: unknown,
+): Promise<void> {
+  const redacted = redactSecrets(manifest);
+  await mkdir(dirname(outputPath), { recursive: true });
+  await writeFile(outputPath, `${JSON.stringify(redacted, null, 2)}\n`, "utf8");
+}
+
+export async function readJsonOutManifest(outputPath: string): Promise<RunManifest | null> {
+  try {
+    const raw = await readFile(outputPath, "utf8");
+    return JSON.parse(raw) as RunManifest;
+  } catch {
+    return null;
+  }
+}
+
+export async function ensureJsonOutManifest(
+  outputPath: string,
+  fallback: FallbackManifestInput,
+): Promise<RunManifest> {
+  const existing = await readJsonOutManifest(outputPath);
+  if (existing) {
+    return existing;
+  }
+  const manifest = buildFallbackRunManifest(fallback);
+  await writeJsonOutManifest(outputPath, manifest);
+  return manifest;
+}

package/workspace-snapshot/files/src/cli/commands/canary-runner-config.ts

@@ -0,0 +1,6 @@
+import { runRunnerConfigCanary } from "../../setup/runner-upgrade-canary.js";
+
+export async function runCanaryRunnerConfigCommand(): Promise<number> {
+  const result = await runRunnerConfigCanary(process.cwd());
+  return result.ok ? 0 : 1;
+}

package/workspace-snapshot/files/src/cli/commands/doctor.ts

@@ -3,12 +3,26 @@ import path from "node:path";
 import { Cursor } from "@cursor/sdk";
 import { loadHarnessConfig, validateRepoClosure } from "../../config/load-config.js";
 import type { HarnessConfig } from "../../config/types.js";
+import { roleModelsSchema } from "../../config/role-models.js";
+import {
+  resolveBuilderModel,
+  resolveModelForRole,
+  resolvePlannerModel,
+  summarizeRoleModelSource,
+} from "../../cursor/model.js";
+import {
+  isWorkflowCloudConfigSynchronized,
+  readWorkflowModelsSyncEvidence,
+} from "../../setup/workflow-models-sync-evidence.js";
+import { resolveLocalFilePaths } from "../../setup/setup-state.js";
+import { formatHarnessDispatchRepo, resolveHarnessDispatchRepo } from "../../setup/harness-dispatch-repo.js";
 import {
   assertBaseBranchExists,
   assertHeadBranchWritePermission,
 } from "../../github/base-branch.js";
 import { GitHubClient, pingGitHub } from "../../github/client.js";
 import { pingLinear } from "../../linear/client.js";
+import { detectNoncanonicalConfigOverrides } from "../../workflow/canonical-workflow-validation.js";
 import {
   doctorChecksFailed,
   formatDoctorCheckLine,
@@ -41,6 +55,16 @@ export async function runDoctor(options: DoctorOptions): Promise<number> {
       ok: true,
     });
 
+    const overrideViolations = detectNoncanonicalConfigOverrides(config);
+    checks.push({
+      label: "canonical workflow status names",
+      ok: overrideViolations.length === 0,
+      detail:
+        overrideViolations.length === 0
+          ? "no noncanonical linear status overrides"
+          : overrideViolations.map((violation) => violation.message).join("; "),
+    });
+
     const runsDir = path.resolve(config.logDirectory);
     await mkdir(runsDir, { recursive: true });
     await access(runsDir, constants.W_OK);
@@ -49,6 +73,116 @@ export async function runDoctor(options: DoctorOptions): Promise<number> {
       ok: true,
       detail: runsDir,
     });
+
+    if (config) {
+      const roleModelsParse = roleModelsSchema.safeParse(config.roleModels ?? {});
+      checks.push({
+        label: "roleModels durable shape",
+        ok: roleModelsParse.success,
+        detail: roleModelsParse.success
+          ? "planner/builder selections structurally valid"
+          : roleModelsParse.error.issues
+              .map((issue: { message: string }) => issue.message)
+              .join("; "),
+      });
+
+      const planner = resolvePlannerModel(config);
+      const builder = resolveBuilderModel(config);
+      checks.push({
+        label: "Planner model resolves",
+        ok: Boolean(planner.id),
+        detail: `configured (${planner.id}) via ${summarizeRoleModelSource(config, "planner")}`,
+      });
+      checks.push({
+        label: "Builder model resolves",
+        ok: Boolean(builder.id),
+        detail: `configured (${builder.id}) via ${summarizeRoleModelSource(config, "builder")}`,
+      });
+
+      const obsoleteKeys = ["revisionModel", "repairModel"].filter(
+        (key) => key in (config as Record<string, unknown>),
+      );
+      checks.push({
+        label: "obsolete revision/repair model keys absent",
+        ok: obsoleteKeys.length === 0,
+        detail:
+          obsoleteKeys.length === 0
+            ? "no legacy per-phase model keys"
+            : `found: ${obsoleteKeys.join(", ")}`,
+      });
+
+      try {
+        const cwd = path.dirname(path.resolve(options.configPath));
+        const localPaths = resolveLocalFilePaths(cwd);
+        let packagedConfigPresent = false;
+        try {
+          await access(localPaths.configLocal);
+          packagedConfigPresent = true;
+        } catch {
+          packagedConfigPresent = false;
+        }
+
+        if (!packagedConfigPresent) {
+          checks.push({
+            label: "Workflow cloud configuration",
+            ok: true,
+            skipped: true,
+            detail: "skipped for explicit config path without .harness/config.local.json",
+          });
+          checks.push({
+            label: "Workflow sync evidence",
+            ok: true,
+            skipped: true,
+            detail: "skipped for explicit config path without packaged local config",
+          });
+          checks.push({
+            label: "Harness dispatch repository",
+            ok: true,
+            skipped: true,
+            detail: "skipped for explicit config path without packaged local config",
+          });
+        } else {
+          const { readCurrentConfigFingerprint } = await import(
+            "../../setup/workflow-model-sync.js"
+          );
+          const fingerprint = await readCurrentConfigFingerprint(cwd);
+          const evidence = await readWorkflowModelsSyncEvidence(cwd);
+          const synchronized = isWorkflowCloudConfigSynchronized({
+            currentFingerprint: fingerprint,
+            evidence,
+          });
+          checks.push({
+            label: "Workflow cloud configuration",
+            ok: synchronized,
+            detail: synchronized
+              ? "synchronized"
+              : evidence
+                ? "needs synchronization"
+                : "needs synchronization (no sync evidence)",
+          });
+          checks.push({
+            label: "Workflow sync evidence",
+            ok: Boolean(evidence),
+            detail: evidence
+              ? `recorded at ${evidence.syncedAt}`
+              : "needs reconstruction (bookkeeping may be missing)",
+          });
+
+          const dispatchRepo = await resolveHarnessDispatchRepo({ cwd });
+          checks.push({
+            label: "Harness dispatch repository",
+            ok: dispatchRepo.resolved,
+            detail: formatHarnessDispatchRepo(dispatchRepo),
+          });
+        }
+      } catch (error) {
+        checks.push({
+          label: "Workflow cloud configuration",
+          ok: false,
+          detail: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
   } catch (error) {
     checks.push({
       label: "harness.config.json valid",
@@ -96,6 +230,20 @@ export async function runDoctor(options: DoctorOptions): Promise<number> {
         ok: true,
         detail: `${count} model(s) available`,
       });
+
+      if (config) {
+        for (const role of ["planner", "builder"] as const) {
+          const selection = resolveModelForRole(config, role);
+          const knownModel = models.some((model) => model.id === selection.id);
+          checks.push({
+            label: `${role} model catalog validation`,
+            ok: knownModel,
+            detail: knownModel
+              ? "model available in current Cursor catalog"
+              : `model "${selection.id}" not found in current catalog`,
+          });
+        }
+      }
     } catch (error) {
       checks.push({
         label: "Cursor models.list()",

package/workspace-snapshot/files/src/cli/commands/resolve-route.ts

@@ -1,4 +1,5 @@
 import { EXIT_CONFIG, EXIT_PLANNING_FAILURE, EXIT_RUN_FAILURE } from "../exit-codes.js";
+import { CloudConfigStaleError } from "../../config/assert-cloud-config-fingerprint.js";
 import { isDispatchPhase } from "../../runner/phase-args.js";
 import { resolveRoute, type ResolveRoutePhaseArg, LinearAuthError } from "../../runner/resolve-route.js";
 import { ResolverError } from "../../resolver/errors.js";
@@ -67,6 +68,10 @@ export async function runResolveRouteCommand(
 
     return 0;
   } catch (error) {
+    if (error instanceof CloudConfigStaleError) {
+      console.error(error.message);
+      return EXIT_CONFIG;
+    }
     if (error instanceof LinearAuthError) {
       console.error(error.message);
       return EXIT_PLANNING_FAILURE;

package/workspace-snapshot/files/src/cli/commands/run.ts

@@ -1,5 +1,11 @@
 import { EXIT_CONFIG } from "../exit-codes.js";
+import {
+  buildFallbackRunManifest,
+  writeJsonOutManifest,
+} from "../../artifacts/write-json-out-manifest.js";
+import { resolveRunGeneration } from "../../runner/run-generation.js";
 import { runOrchestrator, type RunPhaseArg } from "../../runner/orchestrator.js";
+import type { RunManifest } from "../../types/run.js";
 
 export interface RunCommandOptions {
   issueKey: string;
@@ -7,10 +13,18 @@ export interface RunCommandOptions {
   dryRun?: boolean;
   fixturePath?: string;
   json?: boolean;
+  jsonOut?: string;
   phase?: RunPhaseArg;
   force?: boolean;
 }
 
+async function writeRunJsonOut(
+  jsonOut: string,
+  manifest: RunManifest,
+): Promise<void> {
+  await writeJsonOutManifest(jsonOut, manifest);
+}
+
 export async function runRunCommand(options: RunCommandOptions): Promise<number> {
   if (!options.issueKey) {
     console.error("--issue <KEY> is required.");
@@ -22,23 +36,57 @@ export async function runRunCommand(options: RunCommandOptions): Promise<number>
     return EXIT_CONFIG;
   }
 
-  const result = await runOrchestrator({
-    issueKey: options.issueKey,
-    configPath: options.configPath,
-    dryRun: options.dryRun,
-    fixturePath: options.fixturePath,
-    phase: options.dryRun ? "dry-run" : options.phase,
-    force: options.force,
-  });
-
-  if (options.json && result.manifest) {
-    console.log(JSON.stringify(result.manifest, null, 2));
-  } else if (result.manifest && typeof result.manifest === "object") {
-    const manifest = result.manifest as {
-      finalOutcome: string;
-      errorClassification?: string | null;
-      dryRun?: boolean;
-    };
+  const deliveryId = process.env.LINEAR_DELIVERY_ID ?? null;
+  const runGeneration = resolveRunGeneration();
+
+  let result: { exitCode: number; runDirectory?: string; manifest?: unknown };
+  try {
+    result = await runOrchestrator({
+      issueKey: options.issueKey,
+      configPath: options.configPath,
+      dryRun: options.dryRun,
+      fixturePath: options.fixturePath,
+      phase: options.dryRun ? "dry-run" : options.phase,
+      force: options.force,
+    });
+  } catch (error) {
+    if (options.jsonOut) {
+      const fallback = buildFallbackRunManifest({
+        issueKey: options.issueKey,
+        errorClassification: "run_crash",
+        message: error instanceof Error ? error.message : String(error),
+        deliveryId,
+        runGeneration,
+      });
+      await writeRunJsonOut(options.jsonOut, fallback);
+    }
+    throw error;
+  }
+
+  const manifest = result.manifest as RunManifest | undefined;
+
+  if (options.jsonOut) {
+    if (manifest) {
+      await writeRunJsonOut(options.jsonOut, {
+        ...manifest,
+        deliveryId: manifest.deliveryId ?? deliveryId,
+        runGeneration: manifest.runGeneration ?? runGeneration,
+      });
+    } else {
+      const fallback = buildFallbackRunManifest({
+        issueKey: options.issueKey,
+        errorClassification: "run_crash",
+        message: "Harness run finished without a manifest",
+        deliveryId,
+        runGeneration,
+      });
+      await writeRunJsonOut(options.jsonOut, fallback);
+    }
+  }
+
+  if (options.json && manifest) {
+    console.log(JSON.stringify(manifest, null, 2));
+  } else if (manifest && typeof manifest === "object") {
     const label = manifest.dryRun ? "Dry run" : "Run";
     console.log(`${label} finished: ${manifest.finalOutcome}`);
     if (result.runDirectory) {

package/workspace-snapshot/files/src/cli/commands/sync-managed-runner.ts

@@ -0,0 +1,126 @@
+import path from "node:path";
+import { loadHarnessDotenv } from "../../config/load-dotenv.js";
+import { EXIT_CONFIG, EXIT_RUN_FAILURE, EXIT_SUCCESS } from "../exit-codes.js";
+import {
+  hasGithubTokenConfigured,
+  loadGithubTokenFromEnvLocal,
+} from "../../setup/setup-github-auth.js";
+import { createLiveRunnerUpgradeProvider } from "../../setup/runner-upgrade-provider-live.js";
+import { tryCreateHarnessTestRunnerUpgradeProvider } from "../../setup/test-only-runner-upgrade-provider.js";
+import {
+  RELEASE_SYNC_CANARY_POLL_INTERVAL_MS,
+  RELEASE_SYNC_CANARY_POLL_TIMEOUT_MS,
+  RELEASE_SYNC_OVERALL_TIMEOUT_MS,
+  ReleaseSyncManagedRunnerError,
+  runReleaseSyncManagedRunner,
+} from "../../setup/release-sync-managed-runner.js";
+import { RUNNER_UPGRADE_WORKER_PROVIDER_TIMEOUT_MS } from "../../setup/runner-upgrade-timeouts.js";
+import { resolveWorkspaceDir } from "../../p-dev/workspace.js";
+
+export async function runSyncManagedRunnerCommand(options: {
+  pDevHome?: string;
+  apply?: boolean;
+  cancelPending?: boolean;
+  json?: boolean;
+}): Promise<number> {
+  const resolved = resolveWorkspaceDir({
+    cliWorkspace: options.pDevHome,
+    envWorkspace: process.env.P_DEV_HOME,
+  });
+  const cwd = path.resolve(resolved.workspaceDir);
+  process.env.P_DEV_HOME = cwd;
+  loadHarnessDotenv(cwd);
+
+  const testProvider = await tryCreateHarnessTestRunnerUpgradeProvider();
+  let provider = testProvider;
+  if (!provider) {
+    const token = await loadGithubTokenFromEnvLocal({ cwd });
+    if (!hasGithubTokenConfigured(token)) {
+      console.error(
+        "release:sync-managed-runner failed: GITHUB_TOKEN is required in the target P_DEV_HOME .env.local",
+      );
+      return EXIT_CONFIG;
+    }
+    provider = createLiveRunnerUpgradeProvider(token!, {
+      timeoutMs: RUNNER_UPGRADE_WORKER_PROVIDER_TIMEOUT_MS,
+    });
+  }
+
+  try {
+    const result = await runReleaseSyncManagedRunner(provider, {
+      cwd,
+      apply: options.apply === true,
+      cancelPending: options.cancelPending !== false,
+      overallTimeoutMs: RELEASE_SYNC_OVERALL_TIMEOUT_MS,
+      canaryPollIntervalMs: RELEASE_SYNC_CANARY_POLL_INTERVAL_MS,
+      canaryPollTimeoutMs: RELEASE_SYNC_CANARY_POLL_TIMEOUT_MS,
+    });
+
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(`p-dev-home: ${cwd}`);
+      if (result.cancel?.cancelled) {
+        console.log(
+          `cancelled pending upgrade (archived: ${result.cancel.archivedDir ?? "n/a"})`,
+        );
+        const evidence = result.cancel.remoteMutationEvidence;
+        console.log(
+          `prior remote evidence: branch=${evidence.hadBranchName} pr=${evidence.hadPrUrl} canary=${evidence.hadCanaryRunUrl} codeUpdateComplete=${evidence.codeUpdateComplete}`,
+        );
+      }
+      console.log(`repo: ${result.repoSlug} (id ${result.repositoryId})`);
+      console.log(
+        `packaged snapshot: ${result.packagedSnapshotContentId.slice(0, 12)}…`,
+      );
+      if (result.remoteSnapshotContentId) {
+        console.log(
+          `remote snapshot: ${result.remoteSnapshotContentId.slice(0, 12)}…`,
+        );
+      }
+      console.log(
+        `code update: ${
+          result.codeUpdateSkippedBecauseAlreadyCurrent
+            ? "skipped (already current)"
+            : options.apply
+              ? "applied"
+              : "would apply"
+        }`,
+      );
+      if (result.fingerprint) {
+        console.log(`HARNESS_CONFIG_FINGERPRINT: ${result.fingerprint}`);
+      }
+      if (result.canaryRunUrl) {
+        console.log(`canary: ${result.canaryRunUrl}`);
+      }
+      console.log(`phase: ${result.phase}`);
+      console.log(result.message);
+    }
+
+    return result.ok ? EXIT_SUCCESS : EXIT_RUN_FAILURE;
+  } catch (error) {
+    if (error instanceof ReleaseSyncManagedRunnerError) {
+      if (options.json) {
+        console.log(
+          JSON.stringify(
+            {
+              ok: false,
+              phase: error.phase,
+              message: error.message,
+            },
+            null,
+            2,
+          ),
+        );
+      } else {
+        console.error(
+          `release:sync-managed-runner failed at phase=${error.phase}: ${error.message}`,
+        );
+      }
+      return EXIT_RUN_FAILURE;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`release:sync-managed-runner failed: ${message}`);
+    return EXIT_CONFIG;
+  }
+}

package/workspace-snapshot/files/src/cli/program.ts

@@ -12,6 +12,8 @@ import { runResolveRouteCommand } from "./commands/resolve-route.js";
 import { runRedactOutputCommand } from "./commands/redact-output.js";
 import { runDiagnoseVercelBridgeCommand } from "./commands/diagnose-vercel-bridge.js";
 import { runOperatorInit } from "./commands/operator-init.js";
+import { runCanaryRunnerConfigCommand } from "./commands/canary-runner-config.js";
+import { runSyncManagedRunnerCommand } from "./commands/sync-managed-runner.js";
 
 export function createProgram(): Command {
   const program = new Command();
@@ -53,6 +55,7 @@ export function createProgram(): Command {
     .option("--force", "Re-run planning even when idempotency markers exist", false)
     .option("--fixture <path>", "Load issue description from a local markdown fixture")
     .option("--json", "Print manifest JSON to stdout", false)
+    .option("--json-out <path>", "Write redacted manifest JSON to a file")
     .action(async (opts) => {
       const configPath = program.opts<{ config: string }>().config;
       const exitCode = await runRunCommand({
@@ -61,6 +64,7 @@ export function createProgram(): Command {
         dryRun: opts.dryRun,
         fixturePath: opts.fixture,
         json: opts.json,
+        jsonOut: opts.jsonOut,
         phase: opts.phase,
         force: opts.force,
       });
@@ -158,6 +162,49 @@ export function createProgram(): Command {
       process.exitCode = exitCode;
     });
 
+  program
+    .command("canary-runner-config")
+    .description("Validate managed runner marker and cloud config fingerprint pairing")
+    .action(async () => {
+      const exitCode = await runCanaryRunnerConfigCommand();
+      process.exitCode = exitCode;
+    });
+
+  program
+    .command("sync-managed-runner")
+    .description(
+      "Release unblocker: sync one known managed harness runner, cloud config, and config canary",
+    )
+    .option(
+      "--p-dev-home <path>",
+      "Operator workspace (P_DEV_HOME) containing .env.local and .harness/",
+    )
+    .option(
+      "--apply",
+      "Perform remote sync (default is dry-run verification only)",
+      false,
+    )
+    .option(
+      "--keep-pending",
+      "Do not archive/clear an existing local runner-upgrade pending file",
+      false,
+    )
+    .option("--json", "Print JSON result to stdout", false)
+    .action(async (opts: {
+      pDevHome?: string;
+      apply?: boolean;
+      keepPending?: boolean;
+      json?: boolean;
+    }) => {
+      const exitCode = await runSyncManagedRunnerCommand({
+        pDevHome: opts.pDevHome,
+        apply: opts.apply === true,
+        cancelPending: opts.keepPending !== true,
+        json: opts.json === true,
+      });
+      process.exitCode = exitCode;
+    });
+
   program
     .command("redact-output")
     .description("Read stdin and write redacted JSON or text to stdout")

package/workspace-snapshot/files/src/config/assert-cloud-config-fingerprint.ts

@@ -0,0 +1,36 @@
+import {
+  checkCloudConfigFingerprint,
+  HARNESS_CONFIG_FINGERPRINT_VARIABLE,
+  shouldEnforceCloudConfigFingerprint,
+} from "./cloud-config-fingerprint.js";
+
+export class CloudConfigStaleError extends Error {
+  readonly errorClassification = "cloud_config_stale" as const;
+
+  constructor(message: string) {
+    super(message);
+    this.name = "CloudConfigStaleError";
+  }
+}
+
+/**
+ * Fail before routing/execution when the Actions secret and paired fingerprint
+ * variable disagree. No-op outside GitHub Actions (or when skip env is set).
+ */
+export function assertCloudConfigFingerprintFromEnv(
+  env: NodeJS.ProcessEnv = process.env,
+): void {
+  if (!shouldEnforceCloudConfigFingerprint(env)) {
+    return;
+  }
+
+  const result = checkCloudConfigFingerprint({
+    configJsonB64: env.HARNESS_CONFIG_JSON_B64,
+    expectedFingerprint: env[HARNESS_CONFIG_FINGERPRINT_VARIABLE],
+    enforce: true,
+  });
+
+  if (!result.ok) {
+    throw new CloudConfigStaleError(result.message);
+  }
+}