gsd-pi 2.77.0 → 2.78.0-dev.aeeb2ca00

package/src/resources/extensions/gsd/tests/stop-auto-race-null-unit.test.ts

@@ -13,7 +13,7 @@
 
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import { createTestContext } from "./test-helpers.ts";
+import { createTestContext, extractSourceRegion } from "./test-helpers.ts";
 
 const { assertTrue, report } = createTestContext();
 
@@ -35,7 +35,7 @@ assertTrue(
 );
 
 // Extract the region from the closeout comment to the next section comment
-const closeoutRegion = phasesSrc.slice(closeoutIdx, closeoutIdx + 500);
+const closeoutRegion = extractSourceRegion(phasesSrc, closeoutComment);
 assertTrue(
   closeoutRegion.includes("if (s.currentUnit)"),
   "closeoutUnit call is guarded by `if (s.currentUnit)` check (#2939)",
@@ -52,7 +52,7 @@ assertTrue(
   "phases.ts contains the 'Zero tool-call guard' comment block",
 );
 
-const zeroToolRegion = phasesSrc.slice(zeroToolIdx, zeroToolIdx + 600);
+const zeroToolRegion = extractSourceRegion(phasesSrc, zeroToolComment);
 
 // The non-null assertion `s.currentUnit!.startedAt` must be replaced with
 // optional chaining `s.currentUnit?.startedAt`

package/src/resources/extensions/gsd/tests/structured-data-formatter.test.ts

@@ -271,96 +271,15 @@ describe("structured-data-formatter: measureSavings", () => {
 });
 
 // ---------------------------------------------------------------------------
-// Realistic token savings measurement
+// Dropped (#4836): the previous "realistic savings" suite asserted that the
+// compact formatter beat hand-authored "typical markdown" baselines by 30%+.
+// Those baselines were written by the test author to make the assertion pass
+// — they are not the format GSD actually emits anywhere else, so shifting
+// the compact output by any amount could be absorbed by padding the baseline.
+// There was no regression signal.
+//
+// The unit tests above already pin the compact format's structure byte for
+// byte; a genuine regression changes one of those exact-string assertions.
+// If a size-budget guarantee is needed later, capture a real production
+// baseline into a fixture file and assert against a checked-in byte count.
 // ---------------------------------------------------------------------------
-
-describe("structured-data-formatter: realistic savings", () => {
-  it("decisions compact format saves 30%+ vs markdown table", () => {
-    const decisions = [sampleDecision, sampleDecision2];
-
-    // Simulate a typical markdown table
-    const markdownTable = [
-      "| ID   | When       | Scope        | Decision                | Choice                 | Rationale                | Revisable |",
-      "|------|------------|--------------|-------------------------|------------------------|--------------------------|-----------|",
-      "| D001 | M001/S01   | architecture | Use SQLite for storage  | WAL mode, single-writer | Built-in, no external deps | yes       |",
-      "| D002 | M001/S02   | testing      | Unit test all parsers   | node:test framework    | Fast, zero-dependency    | no        |",
-    ].join("\n");
-
-    const compactOutput = formatDecisionsCompact(decisions);
-    const savings = measureSavings(compactOutput, markdownTable);
-    assert.ok(
-      savings >= 30,
-      `expected >=30% savings, got ${savings.toFixed(1)}%`,
-    );
-  });
-
-  it("requirements compact format saves 30%+ vs markdown sections", () => {
-    const requirements = [sampleRequirement, sampleRequirement2];
-
-    // Simulate verbose markdown format with all fields
-    const markdownSections = [
-      "## R001",
-      "",
-      "- **Class:** functional",
-      "- **Status:** active",
-      "- **Description:** Response latency < 200ms for API endpoints",
-      "- **Why:** Critical for user experience",
-      "- **Source:** architecture review",
-      "- **Primary Owner:** S01",
-      "- **Supporting Slices:** S02, S03",
-      "- **Validation:** Load test confirms P99 < 200ms",
-      "- **Notes:** Monitor in production",
-      "",
-      "## R002",
-      "",
-      "- **Class:** non-functional",
-      "- **Status:** active",
-      "- **Description:** Data consistency across writes",
-      "- **Why:** Prevents data loss",
-      "- **Source:** data team review",
-      "- **Primary Owner:** S02",
-      "- **Supporting Slices:** S01",
-      "- **Validation:** Integration test suite",
-      "- **Notes:** Requires WAL mode",
-    ].join("\n");
-
-    const compactOutput = formatRequirementsCompact(requirements);
-    const savings = measureSavings(compactOutput, markdownSections);
-    assert.ok(
-      savings >= 30,
-      `expected >=30% savings, got ${savings.toFixed(1)}%`,
-    );
-  });
-
-  it("task plan compact format saves 30%+ vs markdown sections", () => {
-    const tasks = [sampleTaskDone, sampleTaskPending];
-
-    // Simulate verbose markdown task format
-    const markdownTasks = [
-      "## T01 - Database schema",
-      "",
-      "- **Status:** Done",
-      "- **Estimate:** 30m",
-      "- **Description:** Create tables for decisions and requirements",
-      "- **Files:**",
-      "  - src/db.ts",
-      "  - src/schema.ts",
-      "",
-      "## T02 - API endpoints",
-      "",
-      "- **Status:** Pending",
-      "- **Estimate:** 1h",
-      "- **Description:** REST endpoints for CRUD operations",
-      "- **Files:**",
-      "  - src/api.ts",
-      "- **Verify:** npm test",
-    ].join("\n");
-
-    const compactOutput = formatTaskPlanCompact(tasks);
-    const savings = measureSavings(compactOutput, markdownTasks);
-    assert.ok(
-      savings >= 30,
-      `expected >=30% savings, got ${savings.toFixed(1)}%`,
-    );
-  });
-});

package/src/resources/extensions/gsd/tests/stuck-detection-coverage.test.ts

@@ -142,9 +142,9 @@ test("Rule 3: A-A-A-A triggers Rule 2 not Rule 3", () => {
 
 test("Rule 4: same ENOENT path in two entries triggers stuck", () => {
   const result = detectStuck([
-    { key: "A", error: "ENOENT: no such file or directory, access '/home/user/.gsd/agent/skills/debug-like-expert/SKILL.md'" },
+    { key: "A", error: "ENOENT: no such file or directory, access '/home/user/.agents/skills/debug-like-expert/SKILL.md'" },
     { key: "B" },
-    { key: "A", error: "ENOENT: no such file or directory, access '/home/user/.gsd/agent/skills/debug-like-expert/SKILL.md'" },
+    { key: "A", error: "ENOENT: no such file or directory, access '/home/user/.agents/skills/debug-like-expert/SKILL.md'" },
   ]);
   assert.notEqual(result, null);
   assert.equal(result!.stuck, true);

package/src/resources/extensions/gsd/tests/subagent-model-dispatch.test.ts

@@ -15,6 +15,7 @@ import { join, dirname } from "node:path";
 import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { validatePreferences } from "../preferences-validation.ts";
+import { extractSourceRegion } from "./test-helpers.ts";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const promptsSrc = readFileSync(join(__dirname, "..", "auto-prompts.ts"), "utf-8");
@@ -59,7 +60,7 @@ test("reactive_execution: subagent_model rejects empty string", () => {
 test("buildReactiveExecutePrompt: accepts subagentModel parameter", () => {
   const fnStart = promptsSrc.indexOf("export async function buildReactiveExecutePrompt");
   assert.ok(fnStart !== -1, "buildReactiveExecutePrompt should be exported");
-  const signature = promptsSrc.slice(fnStart, fnStart + 300);
+  const signature = extractSourceRegion(promptsSrc, "export async function buildReactiveExecutePrompt", { fromIdx: fnStart });
   assert.ok(
     signature.includes("subagentModel"),
     "buildReactiveExecutePrompt should accept a subagentModel parameter",
@@ -69,7 +70,7 @@ test("buildReactiveExecutePrompt: accepts subagentModel parameter", () => {
 test("buildParallelResearchSlicesPrompt: accepts subagentModel parameter", () => {
   const fnStart = promptsSrc.indexOf("export async function buildParallelResearchSlicesPrompt");
   assert.ok(fnStart !== -1, "buildParallelResearchSlicesPrompt should be exported");
-  const signature = promptsSrc.slice(fnStart, fnStart + 300);
+  const signature = extractSourceRegion(promptsSrc, "export async function buildParallelResearchSlicesPrompt", { fromIdx: fnStart });
   assert.ok(
     signature.includes("subagentModel"),
     "buildParallelResearchSlicesPrompt should accept a subagentModel parameter",
@@ -79,7 +80,7 @@ test("buildParallelResearchSlicesPrompt: accepts subagentModel parameter", () =>
 test("buildGateEvaluatePrompt: accepts subagentModel parameter", () => {
   const fnStart = promptsSrc.indexOf("export async function buildGateEvaluatePrompt");
   assert.ok(fnStart !== -1, "buildGateEvaluatePrompt should be exported");
-  const signature = promptsSrc.slice(fnStart, fnStart + 300);
+  const signature = extractSourceRegion(promptsSrc, "export async function buildGateEvaluatePrompt", { fromIdx: fnStart });
   assert.ok(
     signature.includes("subagentModel"),
     "buildGateEvaluatePrompt should accept a subagentModel parameter",
@@ -129,7 +130,7 @@ test("auto-dispatch: passes model to buildReactiveExecutePrompt", () => {
   // Find the reactive-execute dispatch rule
   const ruleStart = dispatchSrc.indexOf("reactive-execute (parallel dispatch)");
   assert.ok(ruleStart !== -1, "reactive-execute dispatch rule should exist");
-  const ruleBlock = dispatchSrc.slice(ruleStart, ruleStart + 1000);
+  const ruleBlock = extractSourceRegion(dispatchSrc, "reactive-execute (parallel dispatch)", { fromIdx: ruleStart });
   assert.ok(
     ruleBlock.includes("subagent_model") || ruleBlock.includes("subagentModel"),
     "reactive-execute rule should resolve and pass the subagent model",
@@ -140,7 +141,7 @@ test("auto-dispatch: passes model to buildParallelResearchSlicesPrompt", () => {
   const callIdx = dispatchSrc.indexOf("buildParallelResearchSlicesPrompt(");
   assert.ok(callIdx !== -1, "buildParallelResearchSlicesPrompt call should exist");
   // The call site should pass a model argument (not just 4 args)
-  const callSite = dispatchSrc.slice(callIdx, callIdx + 300);
+  const callSite = extractSourceRegion(dispatchSrc, "buildParallelResearchSlicesPrompt(", { fromIdx: callIdx });
   assert.ok(
     callSite.includes("subagentModel") || callSite.includes("resolveModelWithFallbacksForUnit"),
     "buildParallelResearchSlicesPrompt call should include model argument",
@@ -150,7 +151,7 @@ test("auto-dispatch: passes model to buildParallelResearchSlicesPrompt", () => {
 test("auto-dispatch: passes model to buildGateEvaluatePrompt", () => {
   const callIdx = dispatchSrc.indexOf("buildGateEvaluatePrompt(");
   assert.ok(callIdx !== -1, "buildGateEvaluatePrompt call should exist");
-  const callSite = dispatchSrc.slice(callIdx, callIdx + 300);
+  const callSite = extractSourceRegion(dispatchSrc, "buildGateEvaluatePrompt(", { fromIdx: callIdx });
   assert.ok(
     callSite.includes("subagentModel") || callSite.includes("resolveModelWithFallbacksForUnit"),
     "buildGateEvaluatePrompt call should include model argument",

package/src/resources/extensions/gsd/tests/survivor-branch-complete.test.ts

@@ -1,108 +1,109 @@
 /**
- * Regression test for #2358: Survivor branch recovery skipped in phase=complete.
+ * survivor-branch-complete.test.ts — #2358
  *
- * When bootstrapAutoSession finds a survivor milestone branch and the derived
- * state phase is "complete", recovery/finalization is skipped entirely because
- * the survivor branch detection only triggers when phase === "pre-planning".
- * The milestone finalization (merge, cleanup) never runs, leaving the worktree
- * and branch alive.
+ * The bug: `bootstrapAutoSession` found a survivor milestone branch
+ * (previous session's worktree/branch that was never merged) but only
+ * triggered recovery when `state.phase === "pre-planning"`. In
+ * `phase === "complete"` the milestone artifacts existed but the
+ * finalization path (merge + cleanup) never ran, leaving the worktree
+ * and branch alive indefinitely.
  *
- * The fix broadens the survivor branch detection to also check phase === "complete",
- * and adds a finalization path that runs mergeAndExit before falling through to
- * the normal "complete" handling.
+ * The fix broadens the detection to include `phase === "complete"` and
+ * routes to a finalize-via-mergeAndExit path.
+ *
+ * The previous version of this file was 4 scenarios that re-implemented
+ * the decision logic inline and called `.includes(phase)` on
+ * locally-declared arrays — testing the test, not the code. Called out
+ * in #4832 and parent #4784 as a pure-tautology case (zero imports
+ * from production).
+ *
+ * This rewrite imports `decideSurvivorAction` from auto-start.ts (a
+ * helper extracted in the accompanying refactor) and drives the full
+ * decision table through the real function. The helper is wired into
+ * `bootstrapAutoSession` at the two call sites that previously used
+ * inline conditionals, so the assertions here fail if someone reverts
+ * the helper or narrows its branches.
  */
 
-import { createTestContext } from "./test-helpers.ts";
-
-const { assertTrue, assertEq, report } = createTestContext();
-
-// ═══ Test: survivor branch detection conditions ══════════════════════════════
-
-// The survivor branch detection block in auto-start.ts checks:
-//   state.activeMilestone &&
-//   state.phase === "pre-planning" &&  // <-- BUG: too restrictive
-//   shouldUseWorktreeIsolation() &&
-//   !detectWorktreeName(base) &&
-//   !base.includes(...)
-//
-// The fix should also include state.phase === "complete".
-
-{
-  console.log("\n=== #2358: survivor branch should be detected in phase=complete ===");
-
-  // Simulate the condition check before the fix (only pre-planning)
-  const phasesBeforeFix = ["pre-planning"];
-  const phasesAfterFix = ["pre-planning", "complete"];
-
-  const testPhase = "complete";
-
-  const detectedBefore = phasesBeforeFix.includes(testPhase);
-  assertEq(detectedBefore, false, "before fix: phase=complete should NOT trigger survivor detection");
-
-  const detectedAfter = phasesAfterFix.includes(testPhase);
-  assertEq(detectedAfter, true, "after fix: phase=complete SHOULD trigger survivor detection");
-}
-
-// ═══ Test: pre-planning survivor detection still works ═══════════════════════
-
-{
-  console.log("\n=== #2358: pre-planning survivor detection is not broken ===");
-
-  const phasesAfterFix = ["pre-planning", "complete"];
-  const testPhase = "pre-planning";
-
-  const detected = phasesAfterFix.includes(testPhase);
-  assertEq(detected, true, "pre-planning should still trigger survivor detection after fix");
-}
-
-// ═══ Test: other phases do NOT trigger survivor detection ════════════════════
-
-{
-  console.log("\n=== #2358: other phases should NOT trigger survivor detection ===");
-
-  const phasesAfterFix = ["pre-planning", "complete"];
-
-  for (const phase of ["planning", "executing", "blocked", "needs-discussion"]) {
-    const detected = phasesAfterFix.includes(phase);
-    assertEq(detected, false, `phase=${phase} should NOT trigger survivor detection`);
-  }
-}
-
-// ═══ Test: phase=complete + hasSurvivorBranch should trigger finalization ═════
-
-{
-  console.log("\n=== #2358: phase=complete + survivor branch triggers finalization path ===");
-
-  // Simulate the decision logic after the fix:
-  // if (hasSurvivorBranch && state.phase === "complete") -> finalize
-  // if (hasSurvivorBranch && state.phase === "needs-discussion") -> discuss
-  // if (!hasSurvivorBranch && state.phase === "complete") -> showSmartEntry
-
-  const scenarios = [
-    { hasSurvivorBranch: true, phase: "complete", expected: "finalize" },
-    { hasSurvivorBranch: true, phase: "needs-discussion", expected: "discuss" },
-    { hasSurvivorBranch: true, phase: "pre-planning", expected: "continue" },
-    { hasSurvivorBranch: false, phase: "complete", expected: "showSmartEntry" },
-  ];
-
-  for (const { hasSurvivorBranch, phase, expected } of scenarios) {
-    let result: string;
-    if (hasSurvivorBranch && phase === "complete") {
-      result = "finalize";
-    } else if (hasSurvivorBranch && phase === "needs-discussion") {
-      result = "discuss";
-    } else if (!hasSurvivorBranch && (!phase || phase === "complete")) {
-      result = "showSmartEntry";
-    } else {
-      result = "continue";
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+
+import { decideSurvivorAction } from "../auto-start.ts";
+import type { SurvivorAction } from "../auto-start.ts";
+
+describe("decideSurvivorAction (#2358)", () => {
+  test("no survivor branch → no action, regardless of phase", () => {
+    const phases = [
+      "pre-planning",
+      "planning",
+      "executing",
+      "complete",
+      "needs-discussion",
+      "blocked",
+      "",
+      null,
+      undefined,
+    ];
+    for (const phase of phases) {
+      const got: SurvivorAction = decideSurvivorAction(false, phase);
+      assert.equal(got, "none", `phase=${phase ?? "(nullish)"} → expected 'none', got '${got}'`);
     }
-
-    assertEq(
-      result,
-      expected,
-      `hasSurvivorBranch=${hasSurvivorBranch}, phase=${phase} -> expected ${expected}, got ${result}`,
+  });
+
+  test("survivor + needs-discussion → 'discuss' (#1726)", () => {
+    assert.equal(decideSurvivorAction(true, "needs-discussion"), "discuss");
+  });
+
+  test("survivor + complete → 'finalize' (#2358 — the bug this regression guards)", () => {
+    // This is THE assertion that fails if someone reverts the fix and
+    // narrows the recovery to pre-planning only.
+    assert.equal(decideSurvivorAction(true, "complete"), "finalize");
+  });
+
+  test("survivor + other phase → 'none' (caller continues normal flow)", () => {
+    // pre-planning, planning, executing, blocked — survivor alone is
+    // not sufficient to trigger recovery. Normal auto-mode picks up
+    // from state. This protects against regressions that try to run
+    // finalize on every survivor regardless of phase.
+    const passThroughPhases = ["pre-planning", "planning", "executing", "blocked", ""];
+    for (const phase of passThroughPhases) {
+      assert.equal(
+        decideSurvivorAction(true, phase),
+        "none",
+        `survivor + phase=${phase} → expected 'none', got ${decideSurvivorAction(true, phase)}`,
+      );
+    }
+  });
+
+  test("decision table covers the three outcomes the bootstrap code needs", () => {
+    // Belt-and-suspenders: enumerate (hasSurvivor, phase) and assert
+    // the complete truth table. If someone adds a 4th outcome, this
+    // test fails loudly so they must update both the helper and the
+    // bootstrap wiring.
+    const cases: Array<{ hasSurvivor: boolean; phase: string | null; expected: SurvivorAction }> = [
+      { hasSurvivor: true, phase: "needs-discussion", expected: "discuss" },
+      { hasSurvivor: true, phase: "complete", expected: "finalize" },
+      { hasSurvivor: true, phase: "pre-planning", expected: "none" },
+      { hasSurvivor: true, phase: "planning", expected: "none" },
+      { hasSurvivor: true, phase: null, expected: "none" },
+      { hasSurvivor: false, phase: "complete", expected: "none" },
+      { hasSurvivor: false, phase: "needs-discussion", expected: "none" },
+      { hasSurvivor: false, phase: null, expected: "none" },
+    ];
+    const outcomes = new Set<SurvivorAction>();
+    for (const { hasSurvivor, phase, expected } of cases) {
+      const got = decideSurvivorAction(hasSurvivor, phase);
+      outcomes.add(got);
+      assert.equal(
+        got,
+        expected,
+        `(hasSurvivor=${hasSurvivor}, phase=${phase}) → expected '${expected}', got '${got}'`,
+      );
+    }
+    assert.deepEqual(
+      [...outcomes].sort(),
+      ["discuss", "finalize", "none"],
+      "decision function should produce exactly three outcomes",
     );
-  }
-}
-
-report();
+  });
+});

package/src/resources/extensions/gsd/tests/sync-lock.test.ts

@@ -120,3 +120,34 @@ test('sync-lock: overrides stale lock file (mtime backdated)', (t) => {
     cleanupDir(base);
   }
 });
+
+test('sync-lock: EPERM from live owner PID prevents stale lock stealing', () => {
+  const base = tempDir();
+  fs.mkdirSync(path.join(base, '.gsd'), { recursive: true });
+  const lockPath = path.join(base, '.gsd', 'sync.lock');
+  const fakePid = process.pid + 100_000;
+  const originalKill = process.kill;
+
+  try {
+    fs.writeFileSync(lockPath, JSON.stringify({ pid: fakePid, acquired_at: new Date(0).toISOString() }));
+    const staleTime = new Date(Date.now() - 120_000);
+    fs.utimesSync(lockPath, staleTime, staleTime);
+
+    process.kill = ((pid: number, signal?: NodeJS.Signals | number) => {
+      if (pid === fakePid && signal === 0) {
+        const err = new Error('operation not permitted') as NodeJS.ErrnoException;
+        err.code = 'EPERM';
+        throw err;
+      }
+      return originalKill(pid, signal);
+    }) as typeof process.kill;
+
+    const result = acquireSyncLock(base, 100);
+    assert.strictEqual(result.acquired, false, 'EPERM owner should be treated as live');
+    const content = JSON.parse(fs.readFileSync(lockPath, 'utf-8'));
+    assert.strictEqual(content.pid, fakePid, 'lock file should not be overwritten');
+  } finally {
+    process.kill = originalKill;
+    cleanupDir(base);
+  }
+});

package/src/resources/extensions/gsd/tests/sync-worktree-skip-current.test.ts

@@ -13,6 +13,7 @@ import { describe, it } from 'node:test'
 import assert from 'node:assert/strict'
 import { readFileSync } from 'node:fs'
 import { resolve } from 'node:path'
+import { extractSourceRegion } from "./test-helpers.ts";
 
 const src = readFileSync(
   resolve(process.cwd(), 'src', 'resources', 'extensions', 'gsd', 'auto-worktree.ts'),
@@ -33,14 +34,14 @@ describe('syncWorktreeStateBack skips current milestone (#3641)', () => {
     assert.ok(fnStart !== -1)
 
     // Get a reasonable portion of the function
-    const fnBlock = src.slice(fnStart, fnStart + 3000)
+    const fnBlock = extractSourceRegion(src, 'function syncWorktreeStateBack(', { fromIdx: fnStart })
 
     // Find the for loop iterating milestones
     const loopIdx = fnBlock.indexOf('for (const mid of wtMilestones)')
     assert.ok(loopIdx !== -1, 'milestone iteration loop must exist')
 
     // After the loop, there should be the skip guard
-    const loopBody = fnBlock.slice(loopIdx, loopIdx + 300)
+    const loopBody = extractSourceRegion(fnBlock, 'for (const mid of wtMilestones)', { fromIdx: loopIdx })
     assert.ok(
       loopBody.includes('mid === milestoneId'),
       'mid === milestoneId skip guard must exist inside the milestone loop',
@@ -55,7 +56,7 @@ describe('syncWorktreeStateBack skips current milestone (#3641)', () => {
     const fnStart = src.indexOf('function syncWorktreeStateBack(')
     assert.ok(fnStart !== -1)
 
-    const fnBlock = src.slice(fnStart, fnStart + 3000)
+    const fnBlock = extractSourceRegion(src, 'function syncWorktreeStateBack(', { fromIdx: fnStart })
 
     assert.ok(
       fnBlock.includes('syncMilestoneDir('),

package/src/resources/extensions/gsd/tests/test-helpers.test.ts

@@ -0,0 +1,98 @@
+/**
+ * Tests for test-helpers.ts — the timing helpers (waitForCondition,
+ * findLine) used to replace magic-number sleeps and positional line
+ * indexing in the test suite.
+ *
+ * The `extractSourceRegion` helper (introduced in #4773/#4774) is
+ * deliberately NOT tested here. It is the source-grep antipattern that
+ * #4784 names as the root problem; tests against toy fixtures only
+ * legitimize the pattern without validating behaviour. Its test cases
+ * were removed as part of #4834 — callers are being migrated to
+ * behaviour tests one file at a time, after which the helper is slated
+ * for deletion.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { waitForCondition, findLine } from "./test-helpers.ts";
+
+// ─── waitForCondition ─────────────────────────────────────────────────────
+
+test("waitForCondition returns immediately when condition is true", async () => {
+  const result = await waitForCondition(() => true);
+  assert.equal(result, true);
+});
+
+test("waitForCondition waits and returns when condition becomes true", async () => {
+  let flipped = false;
+  setTimeout(() => { flipped = true; }, 30);
+  const result = await waitForCondition(() => flipped, { intervalMs: 5 });
+  assert.equal(result, true);
+});
+
+test("waitForCondition throws after timeout with description", async () => {
+  await assert.rejects(
+    waitForCondition(() => false, { timeoutMs: 50, intervalMs: 5, description: "the flag to flip" }),
+    /waiting for the flag to flip/i,
+  );
+});
+
+test("waitForCondition surfaces last error on timeout", async () => {
+  await assert.rejects(
+    waitForCondition(
+      () => { throw new Error("probe failed"); },
+      { timeoutMs: 30, intervalMs: 5, description: "probe" },
+    ),
+    /probe failed/,
+  );
+});
+
+test("waitForCondition returns the truthy value (not just true)", async () => {
+  let n = 0;
+  const result = await waitForCondition(() => {
+    n++;
+    return n >= 3 ? { ready: true, iteration: n } : null;
+  }, { intervalMs: 5 });
+  // The helper only resolves when the condition returns a truthy value, so
+  // result cannot be null here. Assert it and narrow for the follow-ups.
+  assert.ok(result, "waitForCondition must resolve with a truthy value, not null");
+  assert.equal(result.ready, true);
+  assert.equal(result.iteration, 3);
+});
+
+// ─── findLine ─────────────────────────────────────────────────────────────
+
+test("findLine locates a line by regex", () => {
+  const output = "header\nstatus: ok\nfooter";
+  const match = findLine(output, /^status:/);
+  assert.equal(match.index, 1);
+  assert.equal(match.text, "status: ok");
+});
+
+test("findLine locates a line by predicate", () => {
+  const output = "a\nb\nc";
+  const match = findLine(output, (l) => l === "b");
+  assert.equal(match.index, 1);
+  assert.equal(match.text, "b");
+});
+
+test("findLine throws with preview when no line matches", () => {
+  assert.throws(
+    () => findLine("a\nb\nc", /NOTFOUND/),
+    /First 10 lines/,
+  );
+});
+
+test("findLine resets lastIndex between lines for /g regex patterns", () => {
+  // Without the reset, RegExp.test with /g flag stateful-advances lastIndex
+  // and can skip matches on subsequent calls. Verify the reset keeps
+  // per-line testing deterministic.
+  const output = "foo\nfoo\nfoo";
+  const globalRe = /foo/g;
+  const match = findLine(output, globalRe);
+  assert.equal(match.index, 0);
+  // Second call on the same pattern must also match — would fail without reset
+  const match2 = findLine(output, globalRe);
+  assert.equal(match2.index, 0);
+});