@stigmer/runner 3.1.1 → 3.1.3

package/src/shared/tool-row.ts

@@ -18,10 +18,11 @@
  */
 
 import { ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
-import type { ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import type { AgentMessage, ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
 import type { SubAgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/subagent_pb";
 import { extractFilePath } from "./file-tools.js";
 import { isSecretLikePath } from "./filereview/secret-paths.js";
+import { toolApprovalCategory } from "./tool-kind.js";
 import { utcTimestamp } from "./status.js";
 
 /**
@@ -52,11 +53,63 @@ export function stampFileEditRow(tc: ToolCall, changeSetId: string): void {
   if (tc.fileChangeSetId) return;
   tc.fileChangeSetId = changeSetId;
 
-  const path = extractFilePath((tc.args ?? {}) as Record<string, unknown>) ?? "";
-  if (isSecretLikePath(path)) {
-    tc.args = path ? { path } : undefined;
+  if (withholdSecretFileContent(tc)) {
+    // A FLOWED row's `result` is the tool's own output — for an edit that can
+    // echo the changed lines — so drop it too. withholdSecretFileContent keeps
+    // `result` intact because the deny-gate path (below) uses it for the safe
+    // "blocked for security" message; here the row actually ran, so clear it.
     tc.result = "";
-    tc.argsPreview = "";
+  }
+}
+
+/**
+ * Withhold a file-mutating row's CONTENT while keeping its path visible: reduce
+ * `args` to `{ path }` (or `undefined` when the path cannot be determined) and
+ * clear `args_preview`. `result` and `status` are left untouched — a caller that
+ * needs the diff dropped clears it explicitly (see {@link stampFileEditRow}).
+ * Returns whether the row was secret-like (and therefore withheld).
+ *
+ * The single primitive behind the never-persist-secret-contents contract (design
+ * doc 12, D4): a file-mutating tool's `args` holds the full write body, which for
+ * a secret-like path must never reach the transcript / Temporal history. A
+ * filename is not itself the secret, so the path is kept. Fail-closed: an
+ * undeterminable path is treated as secret-like ({@link isSecretLikePath} of "").
+ */
+export function withholdSecretFileContent(tc: ToolCall): boolean {
+  const path = extractFilePath((tc.args ?? {}) as Record<string, unknown>) ?? "";
+  if (!isSecretLikePath(path)) return false;
+  tc.args = path ? { path } : undefined;
+  tc.argsPreview = "";
+  return true;
+}
+
+/**
+ * Universal backstop (DD-26 follow-up #2): withhold secret content from every
+ * built-in file-WRITE row in a transcript (top-level + each sub-agent's), across
+ * BOTH harnesses, right before the status is persisted.
+ *
+ * This is the ONLY guarantee that survives `spec.auto_approve_all`, where the
+ * approval gate / deny-gate is never installed, so no per-harness hard-block runs
+ * — yet a secret write still flows and its content lands on the streamed row. It
+ * is a no-op in capture mode (the flowed rows are already content-less after
+ * {@link stampFileEditRow}, which shares {@link withholdSecretFileContent}), and
+ * is the deny-gate analog of the capture-mode stamping pass, which does not run
+ * when there is no change set. Scoped to `write` (FILE_WRITE/FILE_EDIT) because a
+ * delete carries no content.
+ */
+export function withholdSecretContentFromMessages(
+  messages: readonly AgentMessage[],
+  subAgents?: readonly SubAgentExecution[],
+): void {
+  for (const msg of messages) {
+    for (const tc of msg.toolCalls) {
+      if (toolApprovalCategory(tc.name) === "write") {
+        withholdSecretFileContent(tc);
+      }
+    }
+  }
+  for (const sa of subAgents ?? []) {
+    withholdSecretContentFromMessages(sa.messages);
   }
 }
 

package/src/shared/workspace/__tests__/session-root.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { resolveSessionWorkspaceRoot } from "../session-root.js";
+
+let rootDir: string;
+
+beforeEach(async () => {
+  rootDir = await mkdtemp(join(tmpdir(), "stigmer-session-root-"));
+});
+
+afterEach(async () => {
+  await rm(rootDir, { recursive: true, force: true });
+});
+
+describe("resolveSessionWorkspaceRoot", () => {
+  it("returns the shared root untouched when the session has workspace entries", async () => {
+    const resolved = await resolveSessionWorkspaceRoot(rootDir, [{}], "ses_1");
+    expect(resolved).toBe(rootDir);
+  });
+
+  it("creates and returns a per-session directory when the session has no entries", async () => {
+    const resolved = await resolveSessionWorkspaceRoot(rootDir, [], "ses_1");
+    expect(resolved).toBe(join(rootDir, "sessions", "ses_1"));
+    expect((await stat(resolved)).isDirectory()).toBe(true);
+  });
+
+  it("is deterministic across calls (stable across turns and retries)", async () => {
+    const first = await resolveSessionWorkspaceRoot(rootDir, [], "ses_1");
+    const second = await resolveSessionWorkspaceRoot(rootDir, [], "ses_1");
+    expect(second).toBe(first);
+  });
+
+  it("rejects an empty sessionId for a no-entry session", async () => {
+    // An empty id would collapse every no-entry session onto one directory —
+    // the exact cross-session leakage this helper exists to prevent.
+    await expect(resolveSessionWorkspaceRoot(rootDir, [], "")).rejects.toThrow(
+      /sessionId is required/,
+    );
+  });
+});

package/src/shared/workspace/__tests__/workspace-lock.test.ts

@@ -0,0 +1,200 @@
+/**
+ * Tests for the per-workspace turn lock (workspace-lock.ts).
+ *
+ * These run against the real proper-lockfile substrate on tmp directories —
+ * the lock's correctness IS its filesystem behavior, so mocking it would
+ * test nothing.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, mkdir, readdir, rm, symlink, utimes } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  acquireWorkspaceLock,
+  WorkspaceLockTimeoutError,
+  WorkspaceLockCancelledError,
+} from "../workspace-lock.js";
+
+let baseDir: string;
+let workspaceDir: string;
+let lockDir: string;
+
+beforeEach(async () => {
+  baseDir = await mkdtemp(join(tmpdir(), "stigmer-workspace-lock-"));
+  workspaceDir = join(baseDir, "workspace");
+  lockDir = join(baseDir, "locks");
+  await mkdir(workspaceDir, { recursive: true });
+});
+
+afterEach(async () => {
+  await rm(baseDir, { recursive: true, force: true });
+});
+
+/** Resolves true once `promise` settles; used to assert "still pending". */
+function settled(promise: Promise<unknown>): { get: () => boolean } {
+  let done = false;
+  promise.then(() => { done = true; }, () => { done = true; });
+  return { get: () => done };
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+describe("acquireWorkspaceLock", () => {
+  it("serializes two concurrent acquires on the same workspace", async () => {
+    const release1 = await acquireWorkspaceLock(workspaceDir, { lockDir });
+
+    const second = acquireWorkspaceLock(workspaceDir, {
+      lockDir,
+      pollIntervalMs: 25,
+    });
+    const secondSettled = settled(second);
+
+    await sleep(120);
+    expect(secondSettled.get()).toBe(false);
+
+    await release1();
+    const release2 = await second;
+    expect(secondSettled.get()).toBe(true);
+    await release2();
+  });
+
+  it("converges symlink aliases of one directory onto one lock", async () => {
+    const alias = join(baseDir, "workspace-alias");
+    await symlink(workspaceDir, alias);
+
+    const release = await acquireWorkspaceLock(workspaceDir, { lockDir });
+    await expect(
+      acquireWorkspaceLock(alias, {
+        lockDir,
+        pollIntervalMs: 20,
+        timeoutMs: 100,
+      }),
+    ).rejects.toBeInstanceOf(WorkspaceLockTimeoutError);
+    await release();
+  });
+
+  it("does not contend across distinct workspaces", async () => {
+    const otherDir = join(baseDir, "other-workspace");
+    await mkdir(otherDir, { recursive: true });
+
+    const release1 = await acquireWorkspaceLock(workspaceDir, { lockDir });
+    const release2 = await acquireWorkspaceLock(otherDir, {
+      lockDir,
+      timeoutMs: 200,
+      pollIntervalMs: 20,
+    });
+    await release1();
+    await release2();
+  });
+
+  it("recovers a stale lock left by a crashed holder", async () => {
+    const release = await acquireWorkspaceLock(workspaceDir, {
+      lockDir,
+      staleMs: 5_000,
+    });
+    // Simulate a crashed holder: the artifact exists but its mtime refresh
+    // has stopped. Backdate it past the staleness bound.
+    const [artifact] = await readdir(lockDir);
+    const past = new Date(Date.now() - 60_000);
+    await utimes(join(lockDir, artifact), past, past);
+
+    const release2 = await acquireWorkspaceLock(workspaceDir, {
+      lockDir,
+      staleMs: 5_000,
+      timeoutMs: 2_000,
+      pollIntervalMs: 20,
+    });
+    await release2();
+    await release(); // original holder's release must not throw (idempotent wrapper)
+  });
+
+  it("times out with a typed, actionable error when the workspace stays busy", async () => {
+    const release = await acquireWorkspaceLock(workspaceDir, { lockDir });
+    const err = await acquireWorkspaceLock(workspaceDir, {
+      lockDir,
+      timeoutMs: 120,
+      pollIntervalMs: 25,
+    }).catch((e: unknown) => e);
+
+    expect(err).toBeInstanceOf(WorkspaceLockTimeoutError);
+    expect(String(err)).toContain("in use by another session");
+    await release();
+  });
+
+  it("aborts the wait immediately on cancellation", async () => {
+    const release = await acquireWorkspaceLock(workspaceDir, { lockDir });
+    const controller = new AbortController();
+
+    const waiting = acquireWorkspaceLock(workspaceDir, {
+      lockDir,
+      pollIntervalMs: 5_000, // long poll: proves abort wakes the sleep early
+      timeoutMs: 60_000,
+      signal: controller.signal,
+    });
+
+    await sleep(50);
+    const before = Date.now();
+    controller.abort();
+    await expect(waiting).rejects.toBeInstanceOf(WorkspaceLockCancelledError);
+    expect(Date.now() - before).toBeLessThan(1_000);
+    await release();
+  });
+
+  it("invokes onWaiting exactly once and heartbeats on every poll", async () => {
+    const release1 = await acquireWorkspaceLock(workspaceDir, { lockDir });
+
+    let waitingCalls = 0;
+    let heartbeats = 0;
+    const second = acquireWorkspaceLock(workspaceDir, {
+      lockDir,
+      pollIntervalMs: 25,
+      onWaiting: () => { waitingCalls += 1; },
+      heartbeat: () => { heartbeats += 1; },
+    });
+
+    // Deterministic under load: hold the lock until the waiter has provably
+    // polled at least twice, rather than sleeping a fixed wall-clock time.
+    while (heartbeats < 2) {
+      await sleep(20);
+    }
+    await release1();
+    const release2 = await second;
+
+    expect(waitingCalls).toBe(1);
+    expect(heartbeats).toBeGreaterThanOrEqual(2);
+    await release2();
+  });
+
+  it("never invokes onWaiting on an uncontended acquire", async () => {
+    let waitingCalls = 0;
+    const release = await acquireWorkspaceLock(workspaceDir, {
+      lockDir,
+      onWaiting: () => { waitingCalls += 1; },
+    });
+    expect(waitingCalls).toBe(0);
+    await release();
+  });
+
+  it("release is idempotent", async () => {
+    const release = await acquireWorkspaceLock(workspaceDir, { lockDir });
+    await release();
+    await expect(release()).resolves.toBeUndefined();
+    // Lock is actually free again.
+    const release2 = await acquireWorkspaceLock(workspaceDir, {
+      lockDir,
+      timeoutMs: 200,
+      pollIntervalMs: 20,
+    });
+    await release2();
+  });
+
+  it("keeps every lock artifact outside the workspace (issue #173)", async () => {
+    const release = await acquireWorkspaceLock(workspaceDir, { lockDir });
+    expect(await readdir(workspaceDir)).toEqual([]);
+    expect((await readdir(lockDir)).length).toBeGreaterThan(0);
+    await release();
+  });
+});

package/src/shared/workspace/session-root.ts

@@ -0,0 +1,60 @@
+/**
+ * Session workspace-root resolution — shared by both executors (Cursor and
+ * deep-agent) so their placement rules can never drift.
+ *
+ * SessionSpec.workspace_entries promises: "When empty, the session uses an
+ * empty workspace directory." Handing every no-entry session the shared
+ * `config.workspaceRootDir` broke that contract twice over: a "new" session
+ * started amid every prior session's leftovers, and — under the per-workspace
+ * turn lock (workspace-lock.ts) — unrelated no-entry sessions would falsely
+ * serialize against each other. A per-session directory honors the contract,
+ * isolates the default quickstart case, and removes the false contention.
+ *
+ * Sessions WITH entries keep the shared root: their content identity is the
+ * entry source (a git URL clones idempotently, a localPath IS the user's
+ * directory), and cross-session sharing of that content is intentional —
+ * that sharing is exactly what the turn lock serializes.
+ */
+
+import { join } from "node:path";
+import { mkdir } from "node:fs/promises";
+
+/**
+ * Resolve (and create) the working-tree root for a session.
+ *
+ * - No workspace entries → `{workspaceRootDir}/sessions/{sessionId}`, created
+ *   on demand. Deterministic from sessionId alone, so it is stable across
+ *   turns, HITL reinvocations, and Temporal retries with no persisted state.
+ * - One or more entries → the shared `workspaceRootDir`, where the
+ *   provisioner materializes each entry (in place, or per-entry subdirs).
+ *
+ * The `sessions/` namespace lives under the configured workspace root (the
+ * volume operators size and mount for workspace content), not under $HOME.
+ * It can coexist with a single-entry clone at the root: cloneInPlace
+ * (sources/git.ts) tolerates non-empty targets, colliding only if the repo
+ * itself ships a root-level `sessions` path — a strictly smaller surface
+ * than the old behavior, where any file a no-entry session dropped at the
+ * root could break the checkout.
+ */
+export async function resolveSessionWorkspaceRoot(
+  workspaceRootDir: string,
+  workspaceEntries: readonly unknown[],
+  sessionId: string,
+): Promise<string> {
+  if (workspaceEntries.length > 0) {
+    return workspaceRootDir;
+  }
+  if (!sessionId) {
+    // Same invariant as resolvePlatformOptions: an empty sessionId would
+    // collapse every no-entry session onto one directory — the exact leakage
+    // this function exists to prevent.
+    throw new Error(
+      "resolveSessionWorkspaceRoot: sessionId is required for a session with " +
+      "no workspace entries; an empty value would collapse every such session " +
+      "onto one shared directory.",
+    );
+  }
+  const sessionRoot = join(workspaceRootDir, "sessions", sessionId);
+  await mkdir(sessionRoot, { recursive: true });
+  return sessionRoot;
+}

package/src/shared/workspace/workspace-lock.ts

@@ -0,0 +1,241 @@
+/**
+ * Per-workspace turn lock — serializes agent-execution turns that share a
+ * working tree.
+ *
+ * Why this exists: the file-review substrate (shared/filereview) computes a
+ * turn's change set as `git diff baselineTree candidateTree`, where both trees
+ * are live snapshots of the working directory at turn start/end. That model is
+ * correct for a single writer, but nothing scopes a working tree to one
+ * execution: sessions declaring the same `localPath` (or sharing the runner's
+ * `workspaceRootDir`) resolve to the SAME directory, and the runner happily
+ * runs activities concurrently. A concurrent turn's write landing between
+ * another turn's baseline and candidate gets misattributed to that other turn
+ * (observed in prod: aex_01kwpzhmvbvwqdez9cb331nekr reviewed a notes.md it
+ * never wrote). The same race lets a reject-reconcile in one session silently
+ * revert a file another session's user just approved.
+ *
+ * Why a FILE lock and not in-process/server-side coordination: the shared
+ * resource is a directory on one host. A `localPath` entry resolves to the
+ * user's literal directory in ANY runner process on the machine — the CLI
+ * daemon and the desktop app's embedded runner can contend on one tree while
+ * answering to DIFFERENT control planes, so no single server can see all
+ * contenders and no in-process mutex can exclude a sibling process. Mutual
+ * exclusion must live where the collision happens: the filesystem.
+ *
+ * Mechanics (proper-lockfile):
+ * - The lock artifact lives under `~/.stigmer/workspace-locks/{key}.lock`,
+ *   NEVER inside the user's workspace (issue #173: attaching a real repo must
+ *   leave no Stigmer droppings). The key is sha256(realpath(workspaceRoot)),
+ *   so symlink aliases of one directory converge on one lock — the same
+ *   keying pattern as getHitlGateDir in platform-dir.ts.
+ * - While held, proper-lockfile refreshes the artifact's mtime on an interval;
+ *   if the holder process dies, refreshing stops and the artifact goes stale,
+ *   so the next waiter simply takes over. A crashed runner can never deadlock
+ *   a workspace, and no human ever has to delete a lock file.
+ * - Deadlock-free by construction: an activity holds at most ONE lock (its
+ *   primary workspace root), and a turn that pauses for human approval ENDS
+ *   its activity — releasing the lock — so a change set sitting unreviewed
+ *   never blocks the workspace.
+ */
+
+import { join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { createHash } from "node:crypto";
+import { mkdir, realpath } from "node:fs/promises";
+import lockfile from "proper-lockfile";
+
+/** How long a waiter polls between acquisition attempts. */
+const DEFAULT_POLL_INTERVAL_MS = 1_000;
+
+/**
+ * Default bound on how long an execution waits for a contended workspace
+ * before failing with {@link WorkspaceLockTimeoutError}. Generous — an agent
+ * turn legitimately runs for minutes — but finite, so a pathological holder
+ * produces an explicit, actionable failure instead of an invisible hang.
+ */
+export const DEFAULT_WORKSPACE_LOCK_TIMEOUT_MS = 15 * 60 * 1_000;
+
+/**
+ * How long a lock artifact may go un-refreshed before waiters treat the
+ * holder as dead and take over. proper-lockfile refreshes at stale/2, so a
+ * live holder can never be usurped; only a crashed process trips this.
+ */
+const DEFAULT_STALE_MS = 10_000;
+
+/** The acquisition wait exceeded its bound — the workspace stayed busy. */
+export class WorkspaceLockTimeoutError extends Error {
+  constructor(workspaceRoot: string, waitedMs: number) {
+    super(
+      `Workspace is in use by another session: ${workspaceRoot} ` +
+      `(waited ${Math.round(waitedMs / 1000)}s). Another agent execution is ` +
+      `operating on this workspace directory; retry after it finishes.`,
+    );
+    this.name = "WorkspaceLockTimeoutError";
+  }
+}
+
+/** The acquisition wait was cancelled (e.g. the user cancelled the execution). */
+export class WorkspaceLockCancelledError extends Error {
+  constructor(workspaceRoot: string) {
+    super(`Workspace lock wait cancelled for ${workspaceRoot}`);
+    this.name = "WorkspaceLockCancelledError";
+  }
+}
+
+export interface AcquireWorkspaceLockOptions {
+  /**
+   * Invoked once, when the first acquisition attempt finds the workspace
+   * held by another turn — the hook for surfacing a visible "waiting for
+   * workspace" state to the user. Never invoked on an uncontended acquire.
+   */
+  readonly onWaiting?: () => void | Promise<void>;
+  /** Invoked on every poll while waiting (Temporal activity liveness). */
+  readonly heartbeat?: () => void;
+  /** Aborts the wait immediately (Temporal activity cancellation). */
+  readonly signal?: AbortSignal;
+  /** Max wait before {@link WorkspaceLockTimeoutError}. */
+  readonly timeoutMs?: number;
+  /** Poll interval override (tests). */
+  readonly pollIntervalMs?: number;
+  /** Staleness bound override (tests). */
+  readonly staleMs?: number;
+  /** Lock-artifact directory override (tests). */
+  readonly lockDir?: string;
+}
+
+/** Idempotent releaser returned by {@link acquireWorkspaceLock}. */
+export type ReleaseWorkspaceLock = () => Promise<void>;
+
+/** Runner-owned home for lock artifacts (HOME override honored, as in platform-dir.ts). */
+function defaultLockDir(): string {
+  const home = process.env.HOME || process.env.USERPROFILE || homedir();
+  return join(home, ".stigmer", "workspace-locks");
+}
+
+/**
+ * Acquire the exclusive turn lock for a workspace working tree, waiting (with
+ * heartbeats and cancellation) while another turn holds it.
+ *
+ * The caller must hold the lock across the turn's ENTIRE tree-mutating window
+ * — decision reconcile, HITL gate install, the agent's own writes, and the
+ * candidate capture — and release it in a `finally` as the last
+ * workspace-touching step.
+ */
+export async function acquireWorkspaceLock(
+  workspaceRoot: string,
+  options: AcquireWorkspaceLockOptions = {},
+): Promise<ReleaseWorkspaceLock> {
+  const {
+    onWaiting,
+    heartbeat,
+    signal,
+    timeoutMs = DEFAULT_WORKSPACE_LOCK_TIMEOUT_MS,
+    pollIntervalMs = DEFAULT_POLL_INTERVAL_MS,
+    staleMs = DEFAULT_STALE_MS,
+    lockDir = defaultLockDir(),
+  } = options;
+
+  // Resolve symlink aliases so every path spelling of one directory contends
+  // on one lock. The resolved path is also what we hand proper-lockfile as
+  // the target (with realpath:false — already resolved here). A root that
+  // does not exist yet cannot be realpath'd, so it locks on its canonical
+  // absolute spelling instead — proper-lockfile never touches the target
+  // itself (the artifact lives at lockfilePath), so the lock still works.
+  const resolvedRoot = await realpath(workspaceRoot).catch(() => resolve(workspaceRoot));
+  const key = createHash("sha256").update(resolvedRoot).digest("hex").slice(0, 16);
+  await mkdir(lockDir, { recursive: true });
+  const lockfilePath = join(lockDir, `${key}.lock`);
+
+  const startedAt = Date.now();
+  let waitingReported = false;
+
+  for (;;) {
+    if (signal?.aborted) {
+      throw new WorkspaceLockCancelledError(resolvedRoot);
+    }
+
+    try {
+      const release = await lockfile.lock(resolvedRoot, {
+        lockfilePath,
+        realpath: false,
+        stale: staleMs,
+        // No library-side retries: the wait loop below owns retry policy so it
+        // can heartbeat, report waiting, honor cancellation, and bound the wait.
+        retries: 0,
+        // A compromised lock (artifact vanished / refresh missed its staleness
+        // window under extreme event-loop stall) must not crash the worker
+        // process — the default behavior throws uncaught. Log loudly and let
+        // the turn finish: the exposure is bounded to pre-lock semantics.
+        onCompromised: (err) => {
+          console.error(
+            `[workspace-lock] lock on ${resolvedRoot} compromised mid-turn ` +
+            `(continuing unlocked): ${err}`,
+          );
+        },
+      });
+
+      if (waitingReported) {
+        console.log(
+          `[workspace-lock] acquired ${resolvedRoot} after waiting ` +
+          `${Date.now() - startedAt}ms`,
+        );
+      }
+
+      // Idempotent wrapper: the executors release in a `finally` that also
+      // runs on paths where an earlier error may already have torn the lock
+      // down; a double release (or a release racing staleness takeover) must
+      // never mask the turn's real outcome.
+      let released = false;
+      return async () => {
+        if (released) return;
+        released = true;
+        try {
+          await release();
+        } catch (err) {
+          console.warn(`[workspace-lock] release of ${resolvedRoot} failed (ignored): ${err}`);
+        }
+      };
+    } catch (err) {
+      if (!isLockHeldError(err)) throw err;
+    }
+
+    if (!waitingReported) {
+      waitingReported = true;
+      console.log(`[workspace-lock] ${resolvedRoot} is held by another turn; waiting`);
+      try {
+        await onWaiting?.();
+      } catch (err) {
+        console.warn(`[workspace-lock] onWaiting callback failed (non-fatal): ${err}`);
+      }
+    }
+
+    const waitedMs = Date.now() - startedAt;
+    if (waitedMs + pollIntervalMs > timeoutMs) {
+      throw new WorkspaceLockTimeoutError(resolvedRoot, waitedMs);
+    }
+
+    heartbeat?.();
+    await sleepAbortable(pollIntervalMs, signal);
+  }
+}
+
+/** proper-lockfile signals "already held" with code ELOCKED. */
+function isLockHeldError(err: unknown): boolean {
+  return typeof err === "object" && err !== null &&
+    (err as { code?: unknown }).code === "ELOCKED";
+}
+
+/** Sleep that wakes immediately when the signal aborts (wait stays responsive). */
+function sleepAbortable(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}