paseo-req-kit 0.0.0-stage → 1.8.0-beta.3

package/engine/src/playbooks.ts

@@ -0,0 +1,46 @@
+// Requirement types with their own playbook (spec "- 类型："). A playbook keeps the
+// pipeline's steps but changes what some of them do, through a prompt file with one
+// section per step, and the flow skips what the type does not need. See ADR 0023.
+//
+//   缺陷 (defect)       design becomes "reproduce and locate": a failing reproduction first;
+//                        cannot reproduce → stop and ask. The fix must turn it green.
+//   重构 (refactor)     behavior is locked first (characterization tests), then small steps,
+//                        each keeping every check green; review checks that behavior did not change.
+//   评估 (assessment)   read-only: research → assessment.md → independent review → report. No code.
+
+import type { RequirementType } from "./config.js";
+import { type PromptSources, readToolPrompt } from "./prompts.js";
+import { STEPS, type StepId } from "./steps.js";
+
+const TITLES: Record<RequirementType, Partial<Record<StepId, string>>> = {
+  defect: { design: "复现与定位" },
+  refactor: { design: "方案设计与行为锁定" },
+  assessment: { design: "调研评估", design_review: "评估审阅", design_revise: "评估修订", report: "评估报告" },
+};
+
+/** The step's title for this requirement type. */
+export function stepTitle(type: RequirementType | null | undefined, id: StepId): string {
+  return (type && TITLES[type][id]) || STEPS[id].title;
+}
+
+/**
+ * The playbook's guidance for one step: the "## 所有步骤" section plus the section whose
+ * heading names the step id in parentheses, e.g. "## 代码实现（implement）". Null when the
+ * playbook has nothing for this step.
+ */
+export function playbookSection(sources: PromptSources, type: RequirementType, id: StepId): string | null {
+  return promptSections(sources, `types/${type}.md`, id);
+}
+
+/** The same section picking for any prompt file written that way (e.g. joint.md). */
+export function promptSections(sources: PromptSources, file: string, id: StepId): string | null {
+  const text = readToolPrompt(sources, file);
+  const [intro, ...sections] = text.split(/^## /m);
+  const picked = sections.filter((s) => {
+    const heading = s.split("\n", 1)[0];
+    return heading.startsWith("所有步骤") || heading.includes(`（${id}）`) || heading.includes(`(${id})`);
+  });
+  // The common part alone is still worth giving: the type changes what every step looks for.
+  if (picked.length === 0) return null;
+  return [intro.trim(), ...picked.map((s) => `## ${s.trim()}`)].join("\n\n");
+}

package/engine/src/preflight.ts

@@ -0,0 +1,337 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import {
+  type DefectHandling,
+  PHASE_MODE_LABELS,
+  PHASE_MODES,
+  type PhaseMode,
+  PROFILE_LABELS,
+  PROFILE_NAMES,
+  type ProfileName,
+  type RequirementType,
+  type VerifyEnvironment,
+} from "./config.js";
+import { gitInfo } from "./git.js";
+import { samePath } from "./paths.js";
+import { currentLockHolder, type PipelineState, readState, statePath } from "./state.js";
+
+export interface LaunchArgs {
+  repo: string;
+  featureDir: string;
+  originAgentId: string | null;
+  resume: boolean;
+  restart: boolean;
+  configPath: string | null;
+  /** Explicit --profile; otherwise the spec's "档位" line, then the configured default. */
+  profile: ProfileName | null;
+  status: boolean;
+  stop: boolean;
+  /** --list: print every requirement in this repository's worktrees. */
+  list: boolean;
+  /** --spec-review: independent review of the draft spec, before confirmation. */
+  specReview: boolean;
+  /** --worktree: create a Paseo worktree workspace for this requirement and develop there. */
+  worktree: boolean;
+  /**
+   * The checkout the chat works in, when the pipeline runs in a worktree created for it
+   * (repo is then that worktree). Set by the launcher; the chat's cwd must be this.
+   */
+  sourceRepo: string | null;
+  /** Paseo workspace of that worktree. */
+  workspaceId: string | null;
+  /** --at: schedule the start for later instead of starting now. */
+  at: string | null;
+  /** --phases: execution mode for this run; otherwise the spec's "执行方式" line, then the config. */
+  phases: PhaseMode | null;
+  /** --phase verify: start (or continue) the verify phase. Implies --resume. */
+  phase: "verify" | null;
+  /** --verify-at: once development is done, start the verify phase at this time. */
+  verifyAt: string | null;
+  /** --verify-env: where the verify phase checks the result (overrides phases.verify.environment). */
+  verifyEnv: VerifyEnvironment | null;
+  /** --defects: what the verify phase does with defects (overrides phases.verify.defects). */
+  defects: DefectHandling | null;
+  /** --approve: the requester confirmed the design waiting at the confirmation point. Implies --resume. */
+  approve: boolean;
+}
+
+export class PreflightError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "PreflightError";
+  }
+}
+
+function gitCommonDir(dir: string): string | null {
+  try {
+    const out = execFileSync("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], {
+      cwd: dir,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    return out ? fs.realpathSync(out) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Whether `worktree` is a git worktree of the same repository as `source`. */
+export function sameRepository(worktree: string, source: string): boolean {
+  const a = gitCommonDir(worktree);
+  const b = gitCommonDir(source);
+  return a !== null && b !== null && samePath(a, b);
+}
+
+/**
+ * Step agents run under the launching chat. Normally they work in the chat's own
+ * directory, so the repository must be it. A requirement developed in a worktree
+ * created for it (--worktree) runs in that worktree instead; the chat must then be
+ * in the checkout the worktree was created from.
+ */
+export function checkChatCwd(args: Pick<LaunchArgs, "originAgentId" | "sourceRepo">, repo: string, env: NodeJS.ProcessEnv = process.env): void {
+  const chatCwd = env.PASEO_AGENT_CWD?.trim();
+  if (!args.originAgentId || !chatCwd || env.PASEO_AGENT_ID?.trim() !== args.originAgentId) return;
+  const chat = fs.existsSync(chatCwd) ? fs.realpathSync(chatCwd) : chatCwd;
+  if (args.sourceRepo) {
+    const source = fs.existsSync(args.sourceRepo) ? fs.realpathSync(args.sourceRepo) : args.sourceRepo;
+    if (samePath(chat, source) && sameRepository(repo, source)) return;
+    throw new PreflightError(
+      `这个需求在为它新建的工作区 ${repo} 中开发，只能从 ${source} 的对话中操作，当前对话的工作目录是 ${chatCwd}。`,
+    );
+  }
+  if (!samePath(chat, repo)) {
+    throw new PreflightError(
+      `仓库目录 ${repo} 与当前对话的工作目录 ${chatCwd} 不一致。` +
+        "流水线的步骤会挂在这个对话下、在对话的工作目录中进行，所以只能为对话所在的项目启动。" +
+        "请在该仓库对应的项目中打开对话后再启动；对话过程中不要切换工作目录。",
+    );
+  }
+}
+
+/** The spec must carry the line written by the kickoff skill after the user confirms it. */
+export function isSpecConfirmed(specText: string): boolean {
+  return /^\s*-\s*状态\s*[:：]\s*已确认/m.test(specText);
+}
+
+export function normalizeFeatureDir(repo: string, featureDir: string): string {
+  const absolute = path.resolve(repo, featureDir);
+  const relative = path.relative(repo, absolute);
+  if (relative === "" || relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new PreflightError(`功能目录必须位于仓库目录之内：${featureDir}`);
+  }
+  return relative.split(path.sep).join("/");
+}
+
+export type StartMode =
+  | { kind: "fresh" }
+  | { kind: "restart"; previous: PipelineState }
+  | { kind: "resume-reuse"; previous: PipelineState }
+  | { kind: "resume-from-design"; previous: PipelineState; reason: string };
+
+export interface PreflightResult {
+  repo: string;
+  featureDir: string;
+  specPath: string;
+  mode: StartMode;
+  /** Branch the run will commit to; null outside a git repository. */
+  branch: string | null;
+  /** Profile named in the spec, if any. */
+  specProfile: ProfileName | null;
+  /** Execution mode named in the spec, if any. */
+  specPhases: PhaseMode | null;
+  /** Requirement type with its own playbook named in the spec, if any. */
+  specType: RequirementType | null;
+  /** Related repositories the spec says this requirement also changes. */
+  specJoint: string[];
+  /** This start begins the verify phase (the develop phase is done). */
+  entersVerify: boolean;
+}
+
+/** Reads "- 执行方式：分阶段" (连续 / 分阶段 / 只做研发, or the English names) from the spec header. */
+export function specPhases(specText: string): PhaseMode | null {
+  const match = /^\s*-\s*执行方式\s*[:：]\s*(\S+)/m.exec(specText);
+  if (!match) return null;
+  for (const mode of PHASE_MODES) {
+    if (match[1].startsWith(PHASE_MODE_LABELS[mode]) || match[1].toLowerCase().startsWith(mode)) return mode;
+  }
+  return null;
+}
+
+const TYPE_WORDS: Array<[RequirementType, RegExp]> = [
+  ["defect", /^(缺陷|bug|defect|fix|问题修复)/i],
+  ["refactor", /^(重构|技术改进|refactor)/i],
+  ["assessment", /^(评估|调研|assessment|spike)/i],
+];
+
+/** Reads "- 类型：缺陷" (缺陷 / 重构 / 评估, or the English names); 新需求 and 小改动 give null. */
+export function specType(specText: string): RequirementType | null {
+  const match = /^\s*-\s*类型\s*[:：]\s*(\S+)/m.exec(specText);
+  if (!match) return null;
+  return TYPE_WORDS.find(([, re]) => re.test(match[1]))?.[0] ?? null;
+}
+
+/** Reads "- 联合开发：后端、支付" (related repositories this requirement also changes). */
+export function specJoint(specText: string): string[] {
+  const match = /^\s*-\s*联合开发\s*[:：]\s*(.+)$/m.exec(specText);
+  if (!match) return [];
+  const names = match[1].split(/[、,，;；\s]+/).map((n) => n.replace(/[（(].*$/, "").trim()).filter((n) => n && n !== "无");
+  return [...new Set(names)];
+}
+
+/** Whether a run has finished its develop phase, so the verify phase can start. */
+export function developDone(state: PipelineState): boolean {
+  return state.status === "phase_done" || (state.status === "completed" && state.phases?.mode === "develop-only");
+}
+
+/** Reads "- 档位：快速" / "- 档位：标准" from the spec header. */
+export function specProfile(specText: string): ProfileName | null {
+  const match = /^\s*-\s*档位\s*[:：]\s*(\S+)/m.exec(specText);
+  if (!match) return null;
+  for (const name of PROFILE_NAMES) {
+    if (match[1].startsWith(PROFILE_LABELS[name]) || match[1].toLowerCase().startsWith(name)) return name;
+  }
+  return null;
+}
+
+/**
+ * Checks everything that can be checked without talking to the daemon.
+ * The launcher runs this before detaching so the chat agent gets an immediate,
+ * readable error; the pipeline process runs it again before taking the lock.
+ */
+export function preflight(
+  args: LaunchArgs,
+  currentSpecHash: (file: string) => string,
+  env: NodeJS.ProcessEnv = process.env,
+): PreflightResult {
+  if (!fs.existsSync(args.repo) || !fs.statSync(args.repo).isDirectory()) {
+    throw new PreflightError(`仓库目录不存在：${args.repo}`);
+  }
+  const repo = fs.realpathSync(args.repo);
+  checkChatCwd(args, repo, env);
+  const featureDir = normalizeFeatureDir(repo, args.featureDir);
+  const featureAbs = path.join(repo, featureDir);
+  if (!fs.existsSync(featureAbs) || !fs.statSync(featureAbs).isDirectory()) {
+    throw new PreflightError(`功能目录不存在：${featureDir}`);
+  }
+  const specPath = path.join(featureAbs, "spec.md");
+  if (!fs.existsSync(specPath)) {
+    throw new PreflightError(`功能目录中没有 spec.md：${featureDir}`);
+  }
+  const specText = fs.readFileSync(specPath, "utf8");
+  if (!isSpecConfirmed(specText)) {
+    throw new PreflightError(
+      'spec.md 还没有被确认（顶部需要有 "- 状态：已确认" 这一行）。请先和用户确认需求说明。',
+    );
+  }
+  if (args.resume && args.restart) {
+    throw new PreflightError("--resume 和 --restart 不能同时使用");
+  }
+
+  const holder = currentLockHolder(repo);
+  if (holder) {
+    throw new PreflightError(
+      `这个仓库目录已有一条流水线在运行（进程 ${holder.pid}，功能目录 ${holder.featureDir}）。同一个目录一次只能运行一条。`,
+    );
+  }
+
+  const previous = readState(statePath(repo, featureDir));
+  let mode: StartMode;
+  if (!previous) {
+    if (args.resume) throw new PreflightError("没有找到之前的运行记录，无法继续。去掉 --resume 重新启动即可。");
+    mode = { kind: "fresh" };
+  } else if (args.restart) {
+    mode = { kind: "restart", previous };
+  } else if (!args.resume) {
+    const hint =
+      previous.status === "phase_done"
+        ? "这个需求的研发阶段已经完成，正在等待测试验证。开始测试验证请加 --resume --phase verify（或只加 --resume）；要从头开始请加 --restart。"
+        : previous.status === "completed"
+        ? "这个需求的流水线已经完成。如需重新完整运行，请加 --restart。"
+        : `这个需求已有运行记录（状态：${previous.status}）。从中断处继续请加 --resume，从头开始请加 --restart。`;
+    throw new PreflightError(hint);
+  } else if (args.approve && previous.status !== "waiting_for_approval") {
+    throw new PreflightError(`这个需求没有等待确认的方案（状态：${previous.status}），不需要 --approve。继续开发请用 --resume。`);
+  } else if (previous.status === "waiting_for_approval" && currentSpecHash(specPath) !== previous.specHash) {
+    mode = { kind: "resume-from-design", previous, reason: "方案确认时需求方提出了修改，需求说明已更新，从方案设计开始增量处理" };
+  } else if (previous.status === "waiting_for_approval") {
+    if (!args.approve) {
+      throw new PreflightError(
+        "方案正在等待需求方确认（见功能目录中的 preview.md）。需求方确认后用 --approve 继续开发；要修改的话，先更新并重新确认需求说明，再用 --resume。",
+      );
+    }
+    mode = { kind: "resume-reuse", previous };
+  } else if (args.phase === "verify" && !developDone(previous) && previous.phase !== "verify") {
+    throw new PreflightError(
+      previous.status === "completed"
+        ? "这个需求已经完整走完了研发和测试验证，没有单独的测试阶段可以开始。要重新验证，请更新需求说明后用 --resume，或用 --restart。"
+        : `这个需求的研发阶段还没有完成（状态：${previous.status}），还不能开始测试验证。请先用 --resume 继续研发。`,
+    );
+  } else if (args.phase === "verify" && developDone(previous) && currentSpecHash(specPath) === previous.specHash) {
+    // Development is done and the requirement has not changed since: the verify phase starts.
+    mode = { kind: "resume-reuse", previous };
+  } else if (previous.status === "phase_done" && currentSpecHash(specPath) === previous.specHash) {
+    // A plain --resume at the gate starts the verify phase too.
+    mode = { kind: "resume-reuse", previous };
+  } else if (previous.status === "completed") {
+    // A completed requirement is reopened by changing its spec (a requirement change, or
+    // problems found during acceptance). Without such a change there is nothing to continue.
+    if (currentSpecHash(specPath) === previous.specHash) {
+      if (previous.phases?.mode === "develop-only") {
+        throw new PreflightError(
+          "这个需求按\"只做研发\"完成了研发，没有可继续的步骤。要让流水线做测试验证，请用 --resume --phase verify；要修改需求，请先更新并重新确认 spec.md。",
+        );
+      }
+      throw new PreflightError(
+        "这个需求的流水线已经完成，没有可继续的步骤。要修改需求或修复验收中发现的问题，请先更新并重新确认 spec.md；要原样重跑一遍，请用 --restart。",
+      );
+    }
+    mode = { kind: "resume-from-design", previous, reason: "流水线完成后 spec.md 被修改过（需求变更或验收发现的问题），从方案设计开始增量处理" };
+  } else if (previous.status === "waiting_for_business") {
+    mode = { kind: "resume-from-design", previous, reason: "上次因等待需求方决定而停止，需求可能已更新，从方案设计开始增量处理" };
+  } else if (currentSpecHash(specPath) !== previous.specHash) {
+    mode = { kind: "resume-from-design", previous, reason: "spec.md 在上次运行后被修改过，从方案设计开始增量处理" };
+  } else {
+    // "failed", or "running" left behind by a process that died without cleanup.
+    mode = { kind: "resume-reuse", previous };
+  }
+  const git = gitInfo(repo);
+  if (args.worktree) {
+    // The run will happen in a new worktree on its own branch, cut from what is checked out here.
+    if (mode.kind !== "fresh") {
+      throw new PreflightError("这个需求已经在这里运行过，不能再改为在新工作区中开发。请用 --resume 继续，或去掉 --worktree。");
+    }
+    if (!git.isRepo) throw new PreflightError("--worktree 需要 git 仓库。");
+    return { repo, featureDir, specPath, mode, branch: git.branch, specProfile: specProfile(specText), specPhases: specPhases(specText), specType: specType(specText), specJoint: specJoint(specText), entersVerify: false };
+  }
+  // The run commits to the branch that is checked out now, and never to the default branch.
+  if (git.isRepo && git.detached) {
+    throw new PreflightError("当前没有处在任何分支上（detached HEAD）。请切换到这个需求的工作分支后再启动。");
+  }
+  if (git.branch && git.protectedBranches.includes(git.branch)) {
+    throw new PreflightError(
+      `当前在默认分支 ${git.branch} 上，流水线不会在默认分支上提交代码。` +
+        "可以加 --worktree，让流水线为这个需求新建一个 worktree 工作区并在那里开发（这个对话不用动）；" +
+        "或者在 Paseo 中自己新建一个 worktree 工作区（New workspace → Isolation 选 New worktree），在那里的对话中重新开始；" +
+        "或者先切换到这个需求的功能分支。",
+    );
+  }
+  if (mode.kind === "resume-reuse" && mode.previous.branch && git.branch !== mode.previous.branch) {
+    throw new PreflightError(
+      `这个需求之前在分支 ${mode.previous.branch} 上进行，现在的分支是 ${git.branch ?? "（无）"}。请切回原分支后继续，或用 --restart 在当前分支上从头开始。`,
+    );
+  }
+  const entersVerify = mode.kind === "resume-reuse" && developDone(mode.previous);
+  return { repo, featureDir, specPath, mode, branch: git.branch, specProfile: specProfile(specText), specPhases: specPhases(specText), specType: specType(specText), specJoint: specJoint(specText), entersVerify };
+}
+
+/** Why the verify phase cannot start in this environment, or null. */
+export function verifyPhaseProblem(repo: string, featureDir: string, environment: VerifyEnvironment): string | null {
+  if (environment !== "deployed") return null;
+  if (fs.existsSync(path.join(repo, featureDir, "test-env.md"))) return null;
+  return (
+    `要在已部署的测试环境中验证，但功能目录中还没有 test-env.md（${featureDir}/test-env.md）。` +
+    "请先和用户确认测试环境，写好这个文件（地址、账号从哪里取、可以用的测试数据和账号；只写口令在哪里取，不写口令本身），再开始测试验证；" +
+    "或者用 --verify-env local 在本地验证。"
+  );
+}

package/engine/src/prompts.ts

@@ -0,0 +1,72 @@
+import fs from "node:fs";
+import path from "node:path";
+
+// Prompt sources, from least to most specific:
+//   <kit>/engine/prompts/<file>                    shipped with this version
+//   <kit home>/prompts.local/<file>                machine-wide override; replaces the shipped file, survives upgrades
+//   <kit>/principles/INDEX.md                      principles, also read by the chat skills
+//   <repo>/.requirement-pipeline/project-notes.md  appended to every step of this project
+//   <repo>/.requirement-pipeline/verify.md         appended to the steps that build, start or test the project
+//   <repo>/.requirement-pipeline/steps/<step>.md   appended to one step of this project
+
+export const PROJECT_DIR = ".requirement-pipeline";
+
+export interface PromptLocations {
+  promptsDir: string;
+  localPromptsDir: string;
+  principlesFile: string;
+}
+
+export interface PromptSources extends PromptLocations {
+  repo: string;
+}
+
+export function readToolPrompt(sources: PromptSources, file: string): string {
+  const local = path.join(sources.localPromptsDir, file);
+  const shipped = path.join(sources.promptsDir, file);
+  return fs.readFileSync(fs.existsSync(local) ? local : shipped, "utf8").trim();
+}
+
+/** The shared principles, as a prompt section, or null when the index is missing. */
+export function principlesSection(sources: PromptSources): string | null {
+  const text = readIfPresent(sources.principlesFile);
+  if (!text) return null;
+  // The index starts with its own title; give it a heading that fits inside the prompt.
+  const body = text.replace(/^#\s+.*\n+/, "");
+  return ["# 工作原则", "", "以下原则在需求对齐阶段和流水线各步骤中通用。具体要求以前文和\"本步骤任务\"为准，这里说明背后的取舍。", "", body].join("\n");
+}
+
+function readIfPresent(file: string): string | null {
+  if (!fs.existsSync(file)) return null;
+  const text = fs.readFileSync(file, "utf8").trim();
+  return text === "" ? null : text;
+}
+
+/** Steps that build, start or test the project, and so need the project's verification instructions. */
+export const VERIFY_STEPS: readonly string[] = ["implement", "review_fix", "service_start", "verify", "defect_fix", "reverify"];
+
+/** Project-specific additions for one step, ready to append, or null when there are none. */
+export function projectAdditions(sources: PromptSources, stepId: string): string | null {
+  const notes = readIfPresent(path.join(sources.repo, PROJECT_DIR, "project-notes.md"));
+  const verify = VERIFY_STEPS.includes(stepId) ? readIfPresent(path.join(sources.repo, PROJECT_DIR, "verify.md")) : null;
+  const step = readIfPresent(path.join(sources.repo, PROJECT_DIR, "steps", `${stepId}.md`));
+  if (!notes && !verify && !step) return null;
+  const parts = [
+    "# 本项目的补充说明",
+    "",
+    "以下内容由项目维护者编写，说明这个项目的约定和要求。与前文的通用要求冲突时，以这里为准；但\"如实报告\"和安全方面的要求始终有效。",
+  ];
+  if (notes) parts.push("", notes);
+  if (verify) {
+    parts.push(
+      "",
+      "## 本项目的验证方法",
+      "",
+      "来自 `.requirement-pipeline/verify.md`，其中的命令已由项目维护者实际运行过。安装依赖、启动服务、运行测试时优先照此执行；发现它过时或不准确时，照常完成本步骤，并在你的产物里写明哪里不对、实际可行的做法是什么。",
+      "",
+      verify,
+    );
+  }
+  if (step) parts.push("", "## 针对本步骤", "", step);
+  return parts.join("\n");
+}

package/engine/src/queue.ts

@@ -0,0 +1,61 @@
+// Machine-wide limit on pipelines running at once (maxConcurrentPipelines).
+// A pipeline takes one of N slot files in ~/.req-kit/slots; creating a file with "wx"
+// is atomic, so two pipelines starting together cannot both take the last slot.
+// A slot whose process is gone is free again.
+
+import fs from "node:fs";
+import path from "node:path";
+import { kitHome } from "./locations.js";
+import { isAlive } from "./state.js";
+
+export interface SlotHolder {
+  pid: number;
+  repo: string;
+  featureDir: string;
+  since: string;
+}
+
+export function slotsDir(env: NodeJS.ProcessEnv = process.env): string {
+  return path.join(kitHome(env), "slots");
+}
+
+function readHolder(file: string): SlotHolder | null {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8")) as SlotHolder;
+  } catch {
+    return null;
+  }
+}
+
+/** Pipelines holding a slot now (dead holders are cleared on the way). */
+export function slotHolders(dir: string): SlotHolder[] {
+  if (!fs.existsSync(dir)) return [];
+  const holders: SlotHolder[] = [];
+  for (const name of fs.readdirSync(dir)) {
+    const file = path.join(dir, name);
+    const holder = readHolder(file);
+    if (holder && isAlive(holder.pid)) holders.push(holder);
+    else fs.rmSync(file, { force: true });
+  }
+  return holders;
+}
+
+/** Takes a free slot; returns a release function, or null when all `max` slots are taken. */
+export function tryAcquireSlot(dir: string, max: number, holder: SlotHolder): (() => void) | null {
+  fs.mkdirSync(dir, { recursive: true });
+  for (let i = 0; i < max; i++) {
+    const file = path.join(dir, `slot-${i}.json`);
+    const current = readHolder(file);
+    if (current && current.pid !== holder.pid && isAlive(current.pid)) continue;
+    if (current) fs.rmSync(file, { force: true });
+    try {
+      fs.writeFileSync(file, JSON.stringify(holder), { flag: "wx" });
+    } catch {
+      continue; // taken a moment ago by another pipeline
+    }
+    return () => {
+      if (readHolder(file)?.pid === holder.pid) fs.rmSync(file, { force: true });
+    };
+  }
+  return null;
+}

package/engine/src/runtime-loader.ts

@@ -0,0 +1,14 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import type { RuntimeFactory } from "./runtime.js";
+
+export async function loadRuntimeFactory(): Promise<RuntimeFactory> {
+  // Test hook: run the real orchestration against a scripted fake daemon.
+  const fake = process.env.REQ_PIPELINE_FAKE_RUNTIME;
+  if (fake) {
+    const module = (await import(pathToFileURL(path.resolve(fake)).href)) as { createRuntime: RuntimeFactory };
+    return module.createRuntime;
+  }
+  const module = await import("./paseo-runtime.js");
+  return module.createRuntime;
+}