@ryanfw/prompt-orchestration-pipeline 1.3.3 → 1.3.4

package/src/ui/server/__tests__/job-control-endpoints.test.ts

@@ -56,8 +56,9 @@ async function setupPipelineConfig(
   await mkdir(configDir, { recursive: true });
   await writeFile(path.join(configDir, "pipeline.json"), JSON.stringify({ name: slug, tasks }));
   await writeFile(path.join(root, "pipeline-config", "registry.json"), JSON.stringify({
+    version: 1,
     pipelines: {
-      [slug]: {},
+      [slug]: { name: slug, description: "test pipeline" },
     },
   }));
 }
@@ -123,6 +124,7 @@ afterEach(async () => {
   resetPATHS();
   delete process.env["PO_MAX_RUNNING_JOBS"];
   delete process.env["PO_STALE_RUNNING_GRACE_MS"];
+  delete process.env["PO_STALE_LEASE_TIMEOUT_MS"];
   resetConfig();
   for (const proc of childProcs.splice(0)) {
     try { proc.kill(); } catch {}
@@ -515,6 +517,120 @@ describe("handleJobStop", () => {
   });
 });
 
+describe("handleJobStop slot release (AC-1, AC-9)", () => {
+  it("releases the active slot lease after stopping (AC-1)", async () => {
+    const root = await makeTempRoot();
+    initPATHS(root);
+
+    await setupJob(root, "stop-release-active", {
+      id: "stop-release-active",
+      state: "running",
+      current: "research",
+      currentStage: null,
+      tasks: { research: { state: "running", currentStage: null } },
+      files: { artifacts: [], logs: [], tmp: [] },
+    }, 999999);
+
+    const acquired = await tryAcquireJobSlot({
+      dataDir: path.join(root, "pipeline-data"),
+      jobId: "stop-release-active",
+      maxConcurrentJobs: 2,
+      source: "task-start",
+      pid: 999999,
+    });
+    expect(acquired.ok).toBe(true);
+
+    const { runningJobsDir } = getConcurrencyRuntimePaths(path.join(root, "pipeline-data"));
+    const leasePath = path.join(runningJobsDir, "stop-release-active.json");
+    expect(await Bun.file(leasePath).exists()).toBe(true);
+
+    const req = new Request("http://localhost/api/jobs/stop-release-active/stop", { method: "POST" });
+    const res = await handleJobStop(req, "stop-release-active", root);
+    const body = await res.json() as Record<string, unknown>;
+
+    expect(res.status).toBe(202);
+    expect(body["ok"]).toBe(true);
+    expect(body["stopped"]).toBe(true);
+
+    expect(await Bun.file(leasePath).exists()).toBe(false);
+  });
+
+  it("does not throw and returns 202 when no lease exists (AC-9)", async () => {
+    const root = await makeTempRoot();
+    initPATHS(root);
+
+    await setupJob(root, "stop-release-no-lease", {
+      id: "stop-release-no-lease",
+      state: "running",
+      current: "research",
+      currentStage: null,
+      tasks: { research: { state: "running", currentStage: null } },
+      files: { artifacts: [], logs: [], tmp: [] },
+    });
+
+    const req = new Request("http://localhost/api/jobs/stop-release-no-lease/stop", { method: "POST" });
+    const res = await handleJobStop(req, "stop-release-no-lease", root);
+    const body = await res.json() as Record<string, unknown>;
+
+    expect(res.status).toBe(202);
+    expect(body["ok"]).toBe(true);
+    expect(body["stopped"]).toBe(false);
+  });
+
+  it("does not throw and returns 202 when stopping a complete/ job (AC-9)", async () => {
+    const root = await makeTempRoot();
+    initPATHS(root);
+
+    const completeDir = path.join(root, "pipeline-data", "complete", "stop-release-complete");
+    await mkdir(completeDir, { recursive: true });
+    await writeFile(path.join(completeDir, "tasks-status.json"), JSON.stringify({
+      id: "stop-release-complete",
+      state: "complete",
+      current: null,
+      currentStage: null,
+      tasks: { research: { state: "done", currentStage: null } },
+      files: { artifacts: [], logs: [], tmp: [] },
+    }));
+
+    const req = new Request("http://localhost/api/jobs/stop-release-complete/stop", { method: "POST" });
+    const res = await handleJobStop(req, "stop-release-complete", root);
+    const body = await res.json() as Record<string, unknown>;
+
+    expect(res.status).toBe(202);
+    expect(body["ok"]).toBe(true);
+  });
+
+  it("still releases the slot when the status is corrupt (AC-1)", async () => {
+    const root = await makeTempRoot();
+    initPATHS(root);
+
+    const jobDir = path.join(root, "pipeline-data", "current", "stop-release-corrupt");
+    await mkdir(jobDir, { recursive: true });
+    await writeFile(path.join(jobDir, "tasks-status.json"), "not-valid-json{{{");
+
+    const acquired = await tryAcquireJobSlot({
+      dataDir: path.join(root, "pipeline-data"),
+      jobId: "stop-release-corrupt",
+      maxConcurrentJobs: 2,
+      source: "task-start",
+    });
+    expect(acquired.ok).toBe(true);
+
+    const { runningJobsDir } = getConcurrencyRuntimePaths(path.join(root, "pipeline-data"));
+    const leasePath = path.join(runningJobsDir, "stop-release-corrupt.json");
+    expect(await Bun.file(leasePath).exists()).toBe(true);
+
+    const req = new Request("http://localhost/api/jobs/stop-release-corrupt/stop", { method: "POST" });
+    const res = await handleJobStop(req, "stop-release-corrupt", root);
+    const body = await res.json() as Record<string, unknown>;
+
+    expect(res.status).toBe(409);
+    expect(body["code"]).toBe("STATUS_CORRUPT");
+
+    expect(await Bun.file(leasePath).exists()).toBe(false);
+  });
+});
+
 describe("handleJobRestart", () => {
   it("returns 409 when runner PID is alive", async () => {
     const root = await makeTempRoot();
@@ -841,6 +957,265 @@ describe("handleJobRestart", () => {
   });
 });
 
+describe("handleJobRestart dependency gate (AC-5 restart, AC-8, AC-9)", () => {
+  it("returns 412 and leaves status/lease untouched when a from-task predecessor is pending", async () => {
+    const root = await makeTempRoot();
+    initPATHS(root);
+    await setupPipelineConfig(root, "restart-deps-pending-pipeline", ["research", "analysis"]);
+
+    const statusObj = {
+      id: "restart-deps-pending",
+      pipeline: "restart-deps-pending-pipeline",
+      state: "failed",
+      current: "analysis",
+      currentStage: null,
+      lastUpdated: "2026-04-01T10:00:00.000Z",
+      tasks: {
+        research: { state: "pending", currentStage: null },
+        analysis: { state: "pending", currentStage: null },
+      },
+      files: { artifacts: [], logs: [], tmp: [] },
+    };
+    const jobDir = await setupJob(root, "restart-deps-pending", statusObj);
+
+    const statusPath = path.join(jobDir, "tasks-status.json");
+    const snapshotBefore = await Bun.file(statusPath).text();
+    const spawnSpy = vi.spyOn(Bun, "spawn");
+
+    const req = new Request("http://localhost/api/jobs/restart-deps-pending/restart", {
+      method: "POST",
+      body: JSON.stringify({ fromTask: "analysis" }),
+    });
+    const res = await handleJobRestart(req, "restart-deps-pending", root);
+    const body = await res.json() as Record<string, unknown>;
+
+    expect(res.status).toBe(412);
+    expect(body["code"]).toBe("dependencies_not_satisfied");
+    expect(body["message"]).toContain("research");
+
+    expect(await Bun.file(statusPath).text()).toBe(snapshotBefore);
+    expect(spawnSpy).not.toHaveBeenCalled();
+
+    const { runningJobsDir } = getConcurrencyRuntimePaths(path.join(root, "pipeline-data"));
+    expect(await Bun.file(path.join(runningJobsDir, "restart-deps-pending.json")).exists()).toBe(false);
+  });
+
+  it("proceeds when from-task predecessor is done", async () => {
+    const root = await makeTempRoot();
+    initPATHS(root);
+    await setupPipelineConfig(root, "restart-deps-done-pipeline", ["research", "analysis"]);
+    mockRunnerSpawn();
+
+    await setupJob(root, "restart-deps-done", {
+      id: "restart-deps-done",
+      pipeline: "restart-deps-done-pipeline",
+      state: "failed",
+      current: "analysis",
+      currentStage: null,
+      lastUpdated: "2026-04-01T10:00:00.000Z",
+      tasks: {
+        research: { state: "done", currentStage: null },
+        analysis: { state: "pending", currentStage: null },
+      },
+      files: { artifacts: [], logs: [], tmp: [] },
+    });
+
+    const req = new Request("http://localhost/api/jobs/restart-deps-done/restart", {
+      method: "POST",
+      body: JSON.stringify({ fromTask: "analysis" }),
+    });
+    const res = await handleJobRestart(req, "restart-deps-done", root);
+    const body = await res.json() as Record<string, unknown>;
+
+    expect(res.status).toBe(202);
+    expect(body["ok"]).toBe(true);
+    expect(body["mode"]).toBe("from-task");
+  });
+
+  it("proceeds when from-task predecessor is skipped", async () => {
+    const root = await makeTempRoot();
+    initPATHS(root);
+    await setupPipelineConfig(root, "restart-deps-skipped-pipeline", ["research", "analysis"]);
+    mockRunnerSpawn();
+
+    await setupJob(root, "restart-deps-skipped", {
+      id: "restart-deps-skipped",
+      pipeline: "restart-deps-skipped-pipeline",
+      state: "failed",
+      current: "analysis",
+      currentStage: null,
+      lastUpdated: "2026-04-01T10:00:00.000Z",
+      tasks: {
+        research: { state: "skipped", currentStage: null },
+        analysis: { state: "pending", currentStage: null },
+      },
+      files: { artifacts: [], logs: [], tmp: [] },
+    });
+
+    const req = new Request("http://localhost/api/jobs/restart-deps-skipped/restart", {
+      method: "POST",
+      body: JSON.stringify({ fromTask: "analysis" }),
+    });
+    const res = await handleJobRestart(req, "restart-deps-skipped", root);
+    const body = await res.json() as Record<string, unknown>;
+
+    expect(res.status).toBe(202);
+    expect(body["ok"]).toBe(true);
+    expect(body["mode"]).toBe("from-task");
+  });
+
+  it("gates single-task restart identically when a predecessor is pending", async () => {
+    const root = await makeTempRoot();
+    initPATHS(root);
+    await setupPipelineConfig(root, "restart-single-deps-pending-pipeline", ["review", "deploy"]);
+
+    const statusObj = {
+      id: "restart-single-deps-pending",
+      pipeline: "restart-single-deps-pending-pipeline",
+      state: "failed",
+      current: "deploy",
+      currentStage: null,
+      lastUpdated: "2026-04-01T10:00:00.000Z",
+      tasks: {
+        review: { state: "pending", currentStage: null },
+        deploy: { state: "pending", currentStage: null },
+      },
+      files: { artifacts: [], logs: [], tmp: [] },
+    };
+    const jobDir = await setupJob(root, "restart-single-deps-pending", statusObj);
+
+    const statusPath = path.join(jobDir, "tasks-status.json");
+    const snapshotBefore = await Bun.file(statusPath).text();
+    const spawnSpy = vi.spyOn(Bun, "spawn");
+
+    const req = new Request("http://localhost/api/jobs/restart-single-deps-pending/restart", {
+      method: "POST",
+      body: JSON.stringify({ fromTask: "deploy", singleTask: true }),
+    });
+    const res = await handleJobRestart(req, "restart-single-deps-pending", root);
+    const body = await res.json() as Record<string, unknown>;
+
+    expect(res.status).toBe(412);
+    expect(body["code"]).toBe("dependencies_not_satisfied");
+    expect(body["message"]).toContain("review");
+
+    expect(await Bun.file(statusPath).text()).toBe(snapshotBefore);
+    expect(spawnSpy).not.toHaveBeenCalled();
+
+    const { runningJobsDir } = getConcurrencyRuntimePaths(path.join(root, "pipeline-data"));
+    expect(await Bun.file(path.join(runningJobsDir, "restart-single-deps-pending.json")).exists()).toBe(false);
+  });
+
+  it("does not gate clean-slate restart (no fromTask) even when a predecessor is pending", async () => {
+    const root = await makeTempRoot();
+    initPATHS(root);
+    await setupPipelineConfig(root, "restart-clean-ungated-pipeline", ["research", "analysis"]);
+    mockRunnerSpawn();
+
+    await setupJob(root, "restart-clean-ungated", {
+      id: "restart-clean-ungated",
+      pipeline: "restart-clean-ungated-pipeline",
+      state: "failed",
+      current: "analysis",
+      currentStage: null,
+      lastUpdated: "2026-04-01T10:00:00.000Z",
+      tasks: {
+        research: { state: "pending", currentStage: null },
+        analysis: { state: "pending", currentStage: null },
+      },
+      files: { artifacts: [], logs: [], tmp: [] },
+    });
+
+    const req = new Request("http://localhost/api/jobs/restart-clean-ungated/restart", { method: "POST" });
+    const res = await handleJobRestart(req, "restart-clean-ungated", root);
+    const body = await res.json() as Record<string, unknown>;
+
+    expect(res.status).toBe(202);
+    expect(body["ok"]).toBe(true);
+    expect(body["mode"]).toBe("clean-slate");
+  });
+
+  it("returns 500 status_unavailable when the pipeline task order cannot be loaded", async () => {
+    const root = await makeTempRoot();
+    initPATHS(root);
+
+    const statusObj = {
+      id: "restart-no-order",
+      state: "failed",
+      current: "analysis",
+      currentStage: null,
+      lastUpdated: "2026-04-01T10:00:00.000Z",
+      tasks: {
+        research: { state: "done", currentStage: null },
+        analysis: { state: "pending", currentStage: null },
+      },
+      files: { artifacts: [], logs: [], tmp: [] },
+    };
+    const jobDir = await setupJob(root, "restart-no-order", statusObj);
+
+    const statusPath = path.join(jobDir, "tasks-status.json");
+    const snapshotBefore = await Bun.file(statusPath).text();
+    const spawnSpy = vi.spyOn(Bun, "spawn");
+
+    const req = new Request("http://localhost/api/jobs/restart-no-order/restart", {
+      method: "POST",
+      body: JSON.stringify({ fromTask: "analysis" }),
+    });
+    const res = await handleJobRestart(req, "restart-no-order", root);
+    const body = await res.json() as Record<string, unknown>;
+
+    expect(res.status).toBe(500);
+    expect(body["code"]).toBe("status_unavailable");
+
+    expect(await Bun.file(statusPath).text()).toBe(snapshotBefore);
+    expect(spawnSpy).not.toHaveBeenCalled();
+
+    const { runningJobsDir } = getConcurrencyRuntimePaths(path.join(root, "pipeline-data"));
+    expect(await Bun.file(path.join(runningJobsDir, "restart-no-order.json")).exists()).toBe(false);
+  });
+
+  it("returns 404 task_not_found when fromTask is absent from the pipeline order", async () => {
+    const root = await makeTempRoot();
+    initPATHS(root);
+    await setupPipelineConfig(root, "restart-unknown-task-pipeline", ["research", "analysis"]);
+
+    const statusObj = {
+      id: "restart-unknown-task",
+      pipeline: "restart-unknown-task-pipeline",
+      state: "failed",
+      current: "analysis",
+      currentStage: null,
+      lastUpdated: "2026-04-01T10:00:00.000Z",
+      tasks: {
+        research: { state: "done", currentStage: null },
+        analysis: { state: "pending", currentStage: null },
+      },
+      files: { artifacts: [], logs: [], tmp: [] },
+    };
+    const jobDir = await setupJob(root, "restart-unknown-task", statusObj);
+
+    const statusPath = path.join(jobDir, "tasks-status.json");
+    const snapshotBefore = await Bun.file(statusPath).text();
+    const spawnSpy = vi.spyOn(Bun, "spawn");
+
+    const req = new Request("http://localhost/api/jobs/restart-unknown-task/restart", {
+      method: "POST",
+      body: JSON.stringify({ fromTask: "synthesis" }),
+    });
+    const res = await handleJobRestart(req, "restart-unknown-task", root);
+    const body = await res.json() as Record<string, unknown>;
+
+    expect(res.status).toBe(404);
+    expect(body["code"]).toBe("task_not_found");
+
+    expect(await Bun.file(statusPath).text()).toBe(snapshotBefore);
+    expect(spawnSpy).not.toHaveBeenCalled();
+
+    const { runningJobsDir } = getConcurrencyRuntimePaths(path.join(root, "pipeline-data"));
+    expect(await Bun.file(path.join(runningJobsDir, "restart-unknown-task.json")).exists()).toBe(false);
+  });
+});
+
 describe("handleTaskStart", () => {
   it("allows restart/start when snapshot has no valid lastUpdated and no live PID (crashed runner scenario)", async () => {
     // A runner that crashed before writing a valid lastUpdated should not permanently block
@@ -1295,6 +1670,7 @@ describe("handleTaskStart", () => {
 
     expect(res.status).toBe(412);
     expect(body["code"]).toBe("dependencies_not_satisfied");
+    expect(body["message"]).toContain("research");
   });
 
   it("returns 412 dependencies_not_satisfied when an earlier task is \"failed\"", async () => {
@@ -1321,6 +1697,80 @@ describe("handleTaskStart", () => {
 
     expect(res.status).toBe(412);
     expect(body["code"]).toBe("dependencies_not_satisfied");
+    expect(body["message"]).toContain("research");
+  });
+
+  it("returns 202 when an earlier task is \"skipped\" (done-or-skipped dependency rule)", async () => {
+    const root = await makeTempRoot();
+    initPATHS(root);
+    await setupPipelineConfig(root, "task-start-skipped-deps-pipeline", ["research", "analysis"]);
+    const spawnSpy = mockRunnerSpawn(88888);
+
+    await setupJob(root, "task-start-skipped-deps", {
+      id: "task-start-skipped-deps",
+      pipeline: "task-start-skipped-deps-pipeline",
+      state: "pending",
+      current: null,
+      currentStage: null,
+      tasks: {
+        research: { state: "skipped", currentStage: null },
+        analysis: { state: "pending", currentStage: null },
+      },
+      files: { artifacts: [], logs: [], tmp: [] },
+    });
+
+    const req = new Request("http://localhost/api/jobs/task-start-skipped-deps/tasks/analysis/start", { method: "POST" });
+    const res = await handleTaskStart(req, "task-start-skipped-deps", "analysis", root);
+    const body = await res.json() as Record<string, unknown>;
+
+    expect(res.status).toBe(202);
+    expect(body["ok"]).toBe(true);
+    expect(body["taskId"]).toBe("analysis");
+    expect(spawnSpy).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("acquireConcurrencySlot stale-lease age (AC-5)", () => {
+  it("does not prune a fresh null-pid lease when lockFileTimeout is short relative to PO_STALE_LEASE_TIMEOUT_MS", async () => {
+    const root = await makeTempRoot();
+    initPATHS(root);
+    process.env["PO_STALE_LEASE_TIMEOUT_MS"] = "60000";
+    resetConfig();
+
+    const now = Date.parse("2026-04-01T10:01:00.000Z");
+    vi.spyOn(Date, "now").mockReturnValue(now);
+
+    const jobDir = await setupJob(root, "ac-5-held", {
+      id: "ac-5-held",
+      state: "running",
+      current: "research",
+      currentStage: "prompt",
+      lastUpdated: "2026-04-01T10:00:15.000Z",
+      tasks: {
+        research: { state: "running", currentStage: "prompt" },
+      },
+      files: { artifacts: [], logs: [], tmp: [] },
+    }, 999999);
+
+    const runningJobsDir = path.join(root, "pipeline-data", "runtime", "running-jobs");
+    await mkdir(runningJobsDir, { recursive: true });
+    const slotPath = path.join(runningJobsDir, "ac-5-held.json");
+    await writeFile(slotPath, JSON.stringify({
+      jobId: "ac-5-held",
+      pid: null,
+      acquiredAt: new Date(now - 40_000).toISOString(),
+      source: "restart",
+      slotPath,
+    }));
+
+    const req = new Request("http://localhost/api/jobs/ac-5-held/restart", { method: "POST" });
+    const res = await handleJobRestart(req, "ac-5-held", root);
+    const body = await res.json() as Record<string, unknown>;
+
+    expect(res.status).toBe(409);
+    expect(body["code"]).toBe("job_running");
+
+    expect(await Bun.file(slotPath).text()).toBeDefined();
   });
 });
 
@@ -1867,6 +2317,10 @@ describe("corrupt status handling", () => {
       tasks: { research: { state: "pending" } },
       files: { artifacts: [], logs: [], tmp: [] },
     });
+    await writeFile(path.join(jobDir, "pipeline.json"), JSON.stringify({
+      name: "write-corrupt-restart-pipeline",
+      tasks: [{ name: "research" }],
+    }));
     const statusPath = path.join(jobDir, "tasks-status.json");
     corruptStatusOnTextRead(statusPath, 3);
 

package/src/ui/server/__tests__/job-endpoints.test.ts

@@ -25,7 +25,12 @@ async function writePipelineRegistry(root: string): Promise<void> {
   await mkdir(tasksDir, { recursive: true });
   await writeFile(
     path.join(root, "pipeline-config", "registry.json"),
-    JSON.stringify({ pipelines: { demo: { configDir, tasksDir } } }),
+    JSON.stringify({
+      version: 1,
+      pipelines: {
+        demo: { name: "Demo", description: "demo pipeline", configDir, tasksDir },
+      },
+    }),
   );
   await writeFile(
     path.join(configDir, "pipeline.json"),
@@ -121,6 +126,43 @@ describe("job endpoints pipeline config loading", () => {
     expect(body.data.pipelineConfig?.["marker"]).toBe("shared");
     expect(body.data.pipelineConfig?.["tasks"]).toEqual([{ name: "shared-task" }]);
   });
+
+  it("preserves per-task costs in job detail responses", async () => {
+    const root = await makeTempRoot();
+    process.env["PO_ROOT"] = root;
+    resetConfig();
+    initPATHS(root);
+    await writePipelineRegistry(root);
+    const jobDir = await writeJob(root, "current", "job-costs");
+    await writeFile(
+      path.join(jobDir, "tasks-status.json"),
+      JSON.stringify({
+        id: "job-costs",
+        name: "job-costs",
+        pipeline: "demo",
+        createdAt: "2026-06-12T12:00:00.000Z",
+        state: "done",
+        tasks: {
+          build: {
+            state: "done",
+            tokenUsage: [["openai:gpt-4o", 10, 5, 0.25, "estimated", false, true]],
+          },
+        },
+      }),
+    );
+
+    const res = await handleJobDetail("job-costs");
+    const body = await res.json() as {
+      data: { costs?: Record<string, Record<string, unknown>> };
+    };
+
+    expect(res.status).toBe(200);
+    expect(body.data.costs?.["build"]).toMatchObject({
+      source: "estimated",
+      totalCost: 0.25,
+      costEstimated: true,
+    });
+  });
 });
 
 describe("handleJobDetail corrupt status", () => {

package/src/ui/server/__tests__/read-static-path-guard.test.ts

@@ -0,0 +1,94 @@
+// Source-scan guard (AC-8 / spec §7 Step 6).
+//
+// Asserts that none of the four read/static HTTP boundary files builds its final
+// filesystem read path via a bare `path.join`/`join` from URL-derived params
+// outside the containment helpers `resolveUnderRoot` / `resolveWithin`. The
+// current code is clean; this test exists so a future edit like
+// `const p = path.join(root, slug); await Bun.file(p).text()` fails CI.
+//
+// The scan is span-based, not line-based: each join call's full balanced-paren
+// argument span is evaluated as one unit, so a join split across multiple lines
+// (`path.join(\n  root,\n  slug,\n)`) is still checked. A join whose call site is
+// lexically enclosed by a `resolveUnderRoot(...)`/`resolveWithin(...)` argument
+// span is allowed — the param is being contained.
+//
+// Known lexical-guard limitation: a URL param first copied to a local variable
+// and then joined (`const s = slug; path.join(root, s)`) is not detected — that
+// needs dataflow, which is out of scope for a source scan.
+
+import { describe, expect, it } from "vitest";
+
+import path from "node:path";
+
+const BOUNDARY_FILES = [
+  "../endpoints/schema-file-endpoint.ts",
+  "../endpoints/file-endpoints.ts",
+  "../endpoints/task-analysis-endpoint.ts",
+  "../router.ts",
+];
+
+// Identifiers treated as URL-derived when they appear in a join argument span.
+// Documented exclusions: `type`/`params`/`jobId`/`location` are intentionally
+// omitted (see subspec 6-spec.md) — those inputs are out of this guard's scope
+// because they are not part of the encoded-path containment boundary.
+const URL_DERIVED = /\b(slug|filename|taskId|taskName|pathname|searchParams)\b/;
+// Matches `path.join(`, `path.posix.join(`, `path.win32.join(`, or a bare `join(`
+// not preceded by a word char, `$`, or `.` (the `.` exclusion skips array `.join(`).
+const JOIN_CALL = /(?:path(?:\.posix|\.win32)?\.join|(?<![\w$.])join)\s*\(/g;
+// Containment helpers whose argument span makes a join nested inside them safe.
+const CONTAINMENT_CALL = /(?:resolveUnderRoot|resolveWithin)\s*\(/g;
+
+type Span = { open: number; close: number };
+type Violation = { file: string; line: number; snippet: string };
+
+// Given the index of an opening `(`, return the index of its matching `)`.
+function matchingParen(src: string, openIndex: number): number {
+  let depth = 0;
+  for (let i = openIndex; i < src.length; i++) {
+    if (src[i] === "(") depth++;
+    else if (src[i] === ")") {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+  return src.length - 1;
+}
+
+// All call spans for a regex that matches up to and including the `(`.
+function callSpans(src: string, callRe: RegExp): Span[] {
+  const spans: Span[] = [];
+  callRe.lastIndex = 0;
+  for (let m = callRe.exec(src); m !== null; m = callRe.exec(src)) {
+    const open = m.index + m[0].length - 1; // index of the `(`
+    spans.push({ open, close: matchingParen(src, open) });
+  }
+  return spans;
+}
+
+async function scan(filePath: string): Promise<Violation[]> {
+  const src = await Bun.file(filePath).text();
+  const containment = callSpans(src, CONTAINMENT_CALL);
+  const violations: Violation[] = [];
+  for (const join of callSpans(src, JOIN_CALL)) {
+    const args = src.slice(join.open + 1, join.close);
+    if (!URL_DERIVED.test(args) && !args.includes("${")) continue;
+    // Allowed when the join call sits inside a containment call's argument span.
+    const contained = containment.some((c) => c.open < join.open && join.close <= c.close);
+    if (contained) continue;
+    const line = src.slice(0, join.open).split("\n").length;
+    violations.push({ file: path.basename(filePath), line, snippet: args.replace(/\s+/g, " ").trim() });
+  }
+  return violations;
+}
+
+describe("read/static path-building source guard (AC-8)", () => {
+  it("no boundary file builds a final read path via bare path.join(<root>, <url-param>)", async () => {
+    const base = import.meta.dirname;
+    const all: Violation[] = [];
+    for (const rel of BOUNDARY_FILES) {
+      const full = path.resolve(base, rel);
+      all.push(...(await scan(full)));
+    }
+    expect(all, all.map((v) => `${v.file}:${v.line} → ${v.snippet}`).join("\n")).toEqual([]);
+  });
+});