dev-loops 0.1.0

package/scripts/loop/_stale-runner-detection.mjs

@@ -0,0 +1,145 @@
+import {
+  loadRunnerCoordinationState,
+} from "./_pr-runner-coordination.mjs";
+export const STALE_RUNNER_ERROR = Object.freeze({
+  STALE_RUNNER: "stale_runner",
+  EXIT_SIGNAL_RECORDED: "exit_signal_recorded",
+});
+export const STALE_RUNNER_DEFAULT_MAX_AGE_MS = 30 * 60 * 1000;
+function parsePositiveIntegerMs(value, fallback) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return fallback;
+  }
+  return Math.floor(parsed);
+}
+export function resolveStaleRunnerMaxAgeMs(options = {}, env = process.env) {
+  const explicit = options?.staleRunnerMaxAgeMs;
+  if (Number.isFinite(explicit) && explicit > 0) {
+    return Math.floor(explicit);
+  }
+  const fromEnv = parsePositiveIntegerMs(env?.PI_DEV_LOOP_STALE_RUNNER_MAX_AGE_MS, NaN);
+  if (Number.isFinite(fromEnv) && fromEnv > 0) {
+    return fromEnv;
+  }
+  return STALE_RUNNER_DEFAULT_MAX_AGE_MS;
+}
+function normalizeRunIdForSignal(runId) {
+  return typeof runId === "string" && runId.trim().length > 0 ? runId.trim() : null;
+}
+function isExitSignalForRun(state, runId) {
+  if (!state || !Array.isArray(state.exitSignals) || runId === null) {
+    return false;
+  }
+  return state.exitSignals.some((entry) => {
+    if (!entry || typeof entry !== "object") return false;
+    return normalizeRunIdForSignal(entry.runId) === runId;
+  });
+}
+function findStaleRunnerMatch(state, { now, maxAgeMs }) {
+  if (!state || !state.activeRun) return null;
+  const active = state.activeRun;
+  if (!active.runId) return null;
+  const claimedAt = typeof active.claimedAt === "string" ? Date.parse(active.claimedAt) : NaN;
+  const updatedAt = typeof active.updatedAt === "string" ? Date.parse(active.updatedAt) : NaN;
+  const claimedCorrupt = !Number.isFinite(claimedAt);
+  const updatedCorrupt = !Number.isFinite(updatedAt);
+  if (claimedCorrupt || updatedCorrupt) {
+    return {
+      runId: active.runId,
+      claimedAt: active.claimedAt ?? "(corrupt)",
+      updatedAt: active.updatedAt ?? "(corrupt)",
+      claimedAgeMs: claimedCorrupt ? -1 : now - claimedAt,
+      updatedAgeMs: updatedCorrupt ? -1 : now - updatedAt,
+      maxAgeMs,
+      corruptedTimestamp: true,
+    };
+  }
+  const claimedAgeMs = now - claimedAt;
+  const updatedAgeMs = now - updatedAt;
+  if (claimedAgeMs > maxAgeMs && updatedAgeMs > maxAgeMs) {
+    return {
+      runId: active.runId,
+      claimedAt: active.claimedAt,
+      updatedAt: active.updatedAt,
+      claimedAgeMs,
+      updatedAgeMs,
+      maxAgeMs,
+    };
+  }
+  return null;
+}
+export async function detectStaleRunner({ repo, pr, now = Date.now(), maxAgeMs, cwd = process.cwd() } = {}) {
+  if (!repo || typeof repo !== "string") {
+    throw new Error("detectStaleRunner requires a non-empty repo slug");
+  }
+  if (pr === undefined || pr === null) {
+    throw new Error("detectStaleRunner requires a PR number");
+  }
+  const effectiveMaxAgeMs = resolveStaleRunnerMaxAgeMs({ staleRunnerMaxAgeMs: maxAgeMs });
+  const loaded = await loadRunnerCoordinationState({ repo, pr, cwd });
+  if (loaded.state === null) {
+    return {
+      ok: true,
+      status: "no_owner_record",
+      repo,
+      pr,
+      activeRun: null,
+      staleRunner: null,
+      exitSignal: null,
+      filePath: loaded.filePath,
+      maxAgeMs: effectiveMaxAgeMs,
+    };
+  }
+  const state = loaded.state;
+  const active = state.activeRun;
+  const staleMatch = findStaleRunnerMatch(state, { now, maxAgeMs: effectiveMaxAgeMs });
+  const exitSignal = isExitSignalForRun(state, active?.runId ?? null)
+    ? {
+        runId: active.runId,
+        signals: (state.exitSignals || []).filter((entry) =>
+          normalizeRunIdForSignal(entry?.runId) === active.runId),
+      }
+    : null;
+  if (exitSignal !== null) {
+    return {
+      ok: false,
+      error: STALE_RUNNER_ERROR.EXIT_SIGNAL_RECORDED,
+      status: "exit_signal_recorded",
+      repo,
+      pr,
+      activeRun: active,
+      staleRunner: null,
+      exitSignal,
+      filePath: loaded.filePath,
+      maxAgeMs: effectiveMaxAgeMs,
+      message: `Run ${active.runId} has an exit signal recorded for ${repo}#${pr}; refuse to proceed with merge.`,
+    };
+  }
+  if (staleMatch !== null) {
+    return {
+      ok: false,
+      error: STALE_RUNNER_ERROR.STALE_RUNNER,
+      status: "stale_runner",
+      repo,
+      pr,
+      activeRun: active,
+      staleRunner: staleMatch,
+      exitSignal: null,
+      filePath: loaded.filePath,
+      maxAgeMs: effectiveMaxAgeMs,
+      message: `Active run ${staleMatch.runId} for ${repo}#${pr} is stale (claimed ${staleMatch.claimedAgeMs}ms ago, last updated ${staleMatch.updatedAgeMs}ms ago, max age ${staleMatch.maxAgeMs}ms).`,
+    };
+  }
+  return {
+    ok: true,
+    status: "fresh_runner",
+    repo,
+    pr,
+    activeRun: active,
+    staleRunner: null,
+    exitSignal: null,
+    filePath: loaded.filePath,
+    maxAgeMs: effectiveMaxAgeMs,
+  };
+}

package/scripts/loop/_steering-state-file.mjs

@@ -0,0 +1,134 @@
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { parseRepoSlugParts } from "@dev-loops/core/github/repo-slug";
+const STATE_FILE_LOCK_TIMEOUT_MS = 5000;
+const STATE_FILE_LOCK_RETRY_MS = 50;
+function normalizeRepoSlug(repo) {
+  return typeof repo === "string" ? repo.trim().toLowerCase() : "";
+}
+function assertSafeRepoSlug(repo) {
+  return parseRepoSlugParts(repo, {
+    errorMessage: `Invalid repo slug for steering target path: ${JSON.stringify(repo)}`,
+    lowercase: true,
+  });
+}
+export function defaultStateFilePath(runId, cwd = process.cwd()) {
+  return path.join(cwd, ".pi", "steering", `${runId}.json`);
+}
+export function defaultStateFilePathForTarget({ repo, pr }, cwd = process.cwd()) {
+  const { owner, name } = assertSafeRepoSlug(repo);
+  return path.join(cwd, ".pi", "steering", owner, name, `pr-${pr}.json`);
+}
+export function validateSteeringStateTarget(steeringState, { repo, pr, runId }) {
+  if (!steeringState || typeof steeringState !== "object") {
+    return { ok: false, reason: "steering state must be an object" };
+  }
+  if (typeof runId === "string" && steeringState.runId !== runId) {
+    return {
+      ok: false,
+      reason: `steering state runId ${JSON.stringify(steeringState.runId)} does not match expected run ${JSON.stringify(runId)}`,
+    };
+  }
+  const target = steeringState.target;
+  const expectedRepo = normalizeRepoSlug(repo);
+  if (expectedRepo.length > 0) {
+    if (!target || typeof target !== "object") {
+      return {
+        ok: false,
+        reason: "steering state target metadata is missing",
+      };
+    }
+    const actualRepo = normalizeRepoSlug(target.repo);
+    const actualPr = typeof target.pr === "number" ? target.pr : Number(target.pr);
+    if (actualRepo !== expectedRepo || actualPr !== pr) {
+      return {
+        ok: false,
+        reason: `steering state target ${JSON.stringify({ repo: target.repo, pr: target.pr })} does not match expected target ${JSON.stringify({ repo: expectedRepo, pr })}`,
+      };
+    }
+    return { ok: true, reason: null };
+  } else if (target && typeof target === "object") {
+    if (pr !== undefined) {
+      const actualPr = typeof target.pr === "number" ? target.pr : Number(target.pr);
+      if (actualPr !== pr) {
+        return {
+          ok: false,
+          reason: `steering state target pr ${JSON.stringify(target.pr)} does not match expected pr ${JSON.stringify(pr)}`,
+        };
+      }
+    }
+    return {
+      ok: false,
+      reason: "repo identity cannot be proven for the supplied steering state in snapshot mode",
+    };
+  }
+  if (pr !== undefined) {
+    return {
+      ok: false,
+      reason: "steering state target metadata is missing; repo identity cannot be proven for the supplied steering state in snapshot mode",
+    };
+  }
+  return { ok: true, reason: null };
+}
+export async function loadStateFile(filePath) {
+  try {
+    const text = await readFile(filePath, "utf8");
+    return JSON.parse(text);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return null;
+    }
+    throw new Error(`Failed to read steering state file '${filePath}': ${error.message}`);
+  }
+}
+async function sleep(ms) {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function readLockMetadata(lockPath) {
+  try {
+    const text = await readFile(path.join(lockPath, "owner.json"), "utf8");
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+export async function withStateFileLock(filePath, callback) {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  const lockPath = `${filePath}.lock`;
+  const deadline = Date.now() + STATE_FILE_LOCK_TIMEOUT_MS;
+  while (true) {
+    try {
+      await mkdir(lockPath);
+      await writeFile(
+        path.join(lockPath, "owner.json"),
+        `${JSON.stringify({ pid: process.pid, acquiredAt: new Date().toISOString() }, null, 2)}\n`,
+        "utf8",
+      );
+      break;
+    } catch (error) {
+      if (error.code !== "EEXIST") {
+        throw new Error(`Failed to acquire steering state lock '${lockPath}': ${error.message}`);
+      }
+      if (Date.now() >= deadline) {
+        const metadata = await readLockMetadata(lockPath);
+        const ownerSuffix = metadata
+          ? ` (current lock owner pid=${metadata.pid ?? "unknown"}, acquiredAt=${metadata.acquiredAt ?? "unknown"})`
+          : "";
+        throw new Error(`Timed out waiting for steering state lock '${lockPath}'${ownerSuffix}. If the owning process crashed, remove the stale lock directory and retry.`);
+      }
+      await sleep(STATE_FILE_LOCK_RETRY_MS);
+    }
+  }
+  try {
+    return await callback();
+  } finally {
+    await rm(lockPath, { recursive: true, force: true });
+  }
+}
+export async function saveStateFile(filePath, steeringState) {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+  await writeFile(tempPath, `${JSON.stringify(steeringState, null, 2)}\n`, "utf8");
+  await rename(tempPath, filePath);
+}

package/scripts/loop/build-handoff-envelope.mjs

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+/**
+ * CLI wrapper for buildDevLoopHandoffEnvelope().
+ *
+ * Subagents and shell scripts should call this instead of writing ad-hoc
+ * inline Node.js to import from the @dev-loops/core subpath. Using the
+ * bare `@dev-loops/core` specifier fails because the package has no
+ * default export — only named subpath exports.
+ *
+ * Typical usage (pipeline):
+ *   dev-loops loop startup --issue 42 > resolver-output.json
+ *   dev-loops loop build-envelope --input resolver-output.json
+ *
+ * Or via npx:
+ *   npx dev-loops loop build-envelope --input resolver-output.json
+ */
+import { readFile } from "node:fs/promises";
+import { detectRepoSlug } from "@dev-loops/core/github/repo-slug";
+import path from "node:path";
+import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
+import { requireOptionValue } from "../_cli-primitives.mjs";
+import { buildDevLoopHandoffEnvelope } from "@dev-loops/core/loop/handoff-envelope";
+import { loadDevLoopConfig } from "@dev-loops/core/config";
+import { createPiAdapter } from "@dev-loops/core/harness";
+
+const USAGE = `Usage: build-handoff-envelope.mjs --input <path>
+Build a deterministic handoff envelope from startup resolver output and settings.
+Required:
+  --input <path>         Path to resolver output JSON (from resolve-dev-loop-startup.mjs)
+Optional:
+  --gate-state <json>    Gate state JSON string
+                           { currentHeadSha?, ciStatus?, unresolvedThreadCount?, copilotRoundCount? }
+  --overrides <json>     Overrides JSON string
+                           { mergeAuthorized?, preferLocal?, scopeConstraint?, customStopAt? }
+  --repo <owner/name>    Repository slug override (falls back to bundle.repoSlug or bundle.repo)
+Output (stdout, JSON):
+  Handoff envelope object — see workflow-handoff-contract.md for schema.
+Error output (stderr, JSON):
+  Argument/usage errors:
+    { "ok": false, "error": "...", "usage": "..." }
+  Runtime failures:
+    { "ok": false, "error": "..." }
+Exit codes:
+  0  Success
+  1  Argument error or runtime failure`.trim();
+
+const parseError = buildParseError(USAGE);
+
+function parseFlagJson(raw, flagName, parseErrorFn) {
+  try {
+    return parseJsonText(raw);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw parseErrorFn(`Invalid JSON for ${flagName}: ${message}`);
+  }
+}
+
+export function parseBuildHandoffEnvelopeCliArgs(argv) {
+  const args = [...argv];
+  const options = {
+    help: false,
+    inputPath: undefined,
+    gateState: undefined,
+    overrides: undefined,
+    repo: undefined,
+  };
+
+  while (args.length > 0) {
+    const token = args.shift();
+    if (token === "--help" || token === "-h") {
+      options.help = true;
+      return options;
+    }
+    if (token === "--input") {
+      options.inputPath = requireOptionValue(args, "--input", parseError);
+      continue;
+    }
+    if (token === "--gate-state") {
+      options.gateState = requireOptionValue(args, "--gate-state", parseError);
+      continue;
+    }
+    if (token === "--overrides") {
+      options.overrides = requireOptionValue(args, "--overrides", parseError);
+      continue;
+    }
+    if (token === "--repo") {
+      options.repo = requireOptionValue(args, "--repo", parseError);
+      continue;
+    }
+    throw parseError(`Unknown argument: ${token}`);
+  }
+
+  if (!options.inputPath) {
+    throw parseError("--input <path> is required");
+  }
+
+  return options;
+}
+
+
+export async function buildHandoffEnvelopeCli(
+  options,
+  { adapter = createPiAdapter() } = {},
+) {
+  // Resolve repo root via the adapter so envelope construction stays harness-agnostic.
+  const cwd = adapter.getCwd();
+  const repoRoot = adapter.getRepoRoot();
+
+  // Load resolver output from file
+  const inputPath = path.resolve(cwd, options.inputPath);
+  const inputText = await readFile(inputPath, "utf8");
+  const resolverOutput = parseJsonText(inputText);
+
+  // Load dev-loop settings from repo config
+  const configLoadResult = await loadDevLoopConfig({ repoRoot });
+  const hasConfigErrors = Array.isArray(configLoadResult.errors) && configLoadResult.errors.length > 0;
+  const settings = hasConfigErrors ? {} : (configLoadResult.config ?? {});
+
+  // Parse optional gate state
+  let gateState = {};
+  if (options.gateState) {
+    gateState = parseFlagJson(options.gateState, "--gate-state", parseError);
+  }
+
+  // Build options for envelope builder
+  const envelopeOptions = {};
+
+  // Repo slug: explicit --repo, then resolver output bundle, then git remote
+  const bundleSlug = resolverOutput?.bundle?.repoSlug ?? resolverOutput?.bundle?.repo ?? null;
+  const repoSlug = options.repo ?? bundleSlug ?? detectRepoSlug(repoRoot);
+  if (repoSlug) {
+    envelopeOptions.repoSlug = repoSlug;
+  } else {
+    throw parseError(
+      "Repository slug could not be resolved. " +
+      "Pass --repo <owner/name>, ensure the resolver output includes a repo slug, " +
+      "or configure a git remote 'origin'.",
+    );
+  }
+  envelopeOptions.repoRoot = repoRoot;
+
+  // Parse optional overrides
+  if (options.overrides) {
+    envelopeOptions.overrides = parseFlagJson(options.overrides, "--overrides", parseError);
+  }
+
+  const envelope = buildDevLoopHandoffEnvelope(resolverOutput, settings, gateState, envelopeOptions);
+  return envelope;
+}
+
+export async function runCli(
+  argv = process.argv.slice(2),
+  { stdout = process.stdout, stderr = process.stderr, adapter = createPiAdapter() } = {},
+) {
+  let options;
+  try {
+    options = parseBuildHandoffEnvelopeCliArgs(argv);
+  } catch (err) {
+    stderr.write(`${formatCliError(err)}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (options.help) {
+    stdout.write(`${USAGE}\n`);
+    return;
+  }
+
+  try {
+    const envelope = await buildHandoffEnvelopeCli(options, { adapter });
+    stdout.write(`${JSON.stringify(envelope)}\n`);
+  } catch (err) {
+    const msg = formatCliError(err);
+    stderr.write(`${msg}\n`);
+    process.exitCode = 1;
+  }
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  await runCli();
+}

package/scripts/loop/checkpoint-contract.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { defineSubcommand, isDirectCliRun } from "@dev-loops/core/cli/subcommand-runner";
+
+const CHECKPOINT_FILE = ".pi/dev-loop-retrospective-checkpoint.json";
+const ALLOWED_STATES = new Set(["required", "complete", "skipped", "none", "missing"]);
+
+export function buildRetrospectiveCheckpointPayload({ state, notes = null, reason = null }, now = new Date()) {
+  const timestamp = now.toISOString();
+  if (state === "complete") return { state, completedAt: timestamp, notes };
+  if (state === "skipped") return { state, skippedAt: timestamp, reason };
+  if (state === "required") return { state, triggeredAt: timestamp };
+  if (state === "missing") return { state, triggeredAt: timestamp };
+  if (state === "none") return { state };
+  throw new Error(`Unsupported state: ${state}`);
+}
+
+const { runAsScript } = defineSubcommand({
+  name: "checkpoint-contract --state <state>",
+  description: "Write .pi/dev-loop-retrospective-checkpoint.json using the retrospective contract format.",
+  options: [
+    { flag: "--state", type: "string", required: true, choices: [...ALLOWED_STATES],
+      description: "Checkpoint state (required, complete, skipped, none, missing)" },
+    { flag: "--notes", type: "string", description: "Required when --state is complete" },
+    { flag: "--reason", type: "string", description: "Required when --state is skipped" },
+  ],
+  async run({ state, notes, reason }, { args: _args, usage }) {
+    if (!ALLOWED_STATES.has(state)) {
+      throw Object.assign(new Error(`Invalid --state: "${state}". Allowed: ${[...ALLOWED_STATES].join(", ")}.`), { usage });
+    }
+    if (state === "complete" && !notes) {
+      throw Object.assign(new Error('state "complete" requires --notes'), { usage });
+    }
+    if (state === "skipped" && !reason) {
+      throw Object.assign(new Error('state "skipped" requires --reason'), { usage });
+    }
+
+    const cwd = process.cwd();
+    const payload = buildRetrospectiveCheckpointPayload({ state, notes, reason });
+    const checkpointPath = path.join(cwd, CHECKPOINT_FILE);
+    await mkdir(path.dirname(checkpointPath), { recursive: true });
+    await writeFile(checkpointPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+    process.stdout.write(JSON.stringify({ ok: true, path: CHECKPOINT_FILE, checkpoint: payload }) + "\n");
+    return 0;
+  },
+});
+
+if (isDirectCliRun(import.meta.url)) { runAsScript(); }